$filename is C<(eval)>, but $evaltext is undefined. (Note also that
each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
frame. C<$hints> contains pragmatic hints that the caller was
-compiled with. It currently only reflects the hint corresponding to
-C<use utf8>.
+compiled with. The C<$hints> value is subject to change between versions
+of Perl, and is not meant for external use.
Furthermore, when called from within the DB package, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
=item chdir EXPR
Changes the working directory to EXPR, if possible. If EXPR is omitted,
-changes to the user's home directory. Returns true upon success,
-false otherwise. See the example under C<die>.
+changes to the directory specified by C<$ENV{HOME}>, if set; if not,
+changes to the directory specified by C<$ENV{LOGDIR}>. If neither is
+set, C<chdir> does nothing. It returns true upon success, false
+otherwise. See the example under C<die>.
=item chmod LIST
=item delete EXPR
-Deletes the specified key(s) and their associated values from a hash.
-For each key, returns the deleted value associated with that key, or
-the undefined value if there was no such key. Deleting from C<$ENV{}>
-modifies the environment. Deleting from a hash tied to a DBM file
-deletes the entry from the DBM file. (But deleting from a C<tie>d hash
-doesn't necessarily return anything.)
+Given an expression that specifies a hash element, array element, hash slice,
+or array slice, deletes the specified element(s) from the hash or array.
+If the array elements happen to be at the end of the array, the size
+of the array will shrink by that number of elements.
-The following deletes all the values of a hash:
+Returns each element so deleted or the undefined value if there was no such
+element. Deleting from C<$ENV{}> modifies the environment. Deleting from
+a hash tied to a DBM file deletes the entry from the DBM file. Deleting
+from a C<tie>d hash or array may not necessarily return anything.
+
+Deleting an array element effectively returns that position of the array
+to its initial, uninitialized state. Subsequently testing for the same
+element with exists() will return false. See L</exists>.
+
+The following (inefficiently) deletes all the values of %HASH and @ARRAY:
foreach $key (keys %HASH) {
delete $HASH{$key};
}
-And so does this:
+ foreach $index (0 .. $#ARRAY) {
+ delete $ARRAY[$index];
+ }
+
+And so do these:
+
+ delete @HASH{keys %HASH};
- delete @HASH{keys %HASH}
+ delete @ARRAY[0 .. $#ARRAY];
But both of these are slower than just assigning the empty list
-or undefining it:
+or undefining %HASH or @ARRAY:
- %hash = (); # completely empty %hash
- undef %hash; # forget %hash every existed
+ %HASH = (); # completely empty %HASH
+ undef %HASH; # forget %HASH ever existed
+
+ @ARRAY = (); # completely empty @ARRAY
+ undef @ARRAY; # forget @ARRAY ever existed
Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash element lookup or hash slice:
+operation is a hash element, array element, hash slice, or array slice
+lookup:
delete $ref->[$x][$y]{$key};
delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
+ delete $ref->[$x][$y][$index];
+ delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
+
=item die LIST
Outside an C<eval>, prints the value of LIST to C<STDERR> and
C<eof(FILEHANDLE)> on it) after end-of-file is reached. File types such
as terminals may lose the end-of-file condition if you do.
-An C<eof> without an argument uses the last file read as argument.
-Using C<eof()> with empty parentheses is very different. It indicates
-the pseudo file formed of the files listed on the command line,
-i.e., C<eof()> is reasonable to use inside a C<while (E<lt>E<gt>)>
-loop to detect the end of only the last file. Use C<eof(ARGV)> or
-C<eof> without the parentheses to test I<each> file in a while
-(E<lt>E<gt>) loop. Examples:
+An C<eof> without an argument uses the last file read. Using C<eof()>
+with empty parentheses is very different. It refers to the pseudo file
+formed from the files listed on the command line and accessed via the
+C<E<lt>E<gt>> operator. Since C<E<lt>E<gt>> isn't explicitly opened,
+as a normal filehandle is, an C<eof()> before C<E<lt>E<gt>> has been
+used will cause C<@ARGV> to be examined to determine if input is
+available.
+
+In a C<while (E<lt>E<gt>)> loop, C<eof> or C<eof(ARGV)> can be used to
+detect the end of each file, C<eof()> will only detect the end of the
+last file. Examples:
# reset line numbering on each input file
while (<>) {
=item exists EXPR
-Returns true if the specified hash key exists in its hash, even
-if the corresponding value is undefined.
+Given an expression that specifies a hash element or array element,
+returns true if the specified element in the hash or array has ever
+been initialized, even if the corresponding value is undefined. The
+element is not autovivified if it doesn't exist.
+
+ print "Exists\n" if exists $hash{$key};
+ print "Defined\n" if defined $hash{$key};
+ print "True\n" if $hash{$key};
- print "Exists\n" if exists $array{$key};
- print "Defined\n" if defined $array{$key};
- print "True\n" if $array{$key};
+ print "Exists\n" if exists $array[$index];
+ print "Defined\n" if defined $array[$index];
+ print "True\n" if $array[$index];
-A hash element can be true only if it's defined, and defined if
+A hash or array element can be true only if it's defined, and defined if
it exists, but the reverse doesn't necessarily hold true.
+Given an expression that specifies the name of a subroutine,
+returns true if the specified subroutine has ever been declared, even
+if it is undefined. Mentioning a subroutine name for exists or defined
+does not count as declaring it.
+
+ print "Exists\n" if exists &subroutine;
+ print "Defined\n" if defined &subroutine;
+
Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash key lookup:
+operation is a hash or array key lookup or subroutine name:
if (exists $ref->{A}->{B}->{$key}) { }
if (exists $hash{A}{B}{$key}) { }
-Although the last element will not spring into existence just because
-its existence was tested, intervening ones will. Thus C<$ref-E<gt>{"A"}>
-and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring into existence due to the
-existence test for a $key element. This happens anywhere the arrow
-operator is used, including even
+ if (exists $ref->{A}->{B}->[$ix]) { }
+ if (exists $hash{A}{B}[$ix]) { }
+
+ if (exists &{$ref->{A}{B}{$key}}) { }
+
+Although the deepest nested array or hash will not spring into existence
+just because its existence was tested, any intervening ones will.
+Thus C<$ref-E<gt>{"A"}> and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring
+into existence due to the existence test for the $key element above.
+This happens anywhere the arrow operator is used, including even:
undef $ref;
if (exists $ref->{"Some key"}) { }
See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
used on a pseudo-hash.
+Use of a subroutine call, rather than a subroutine name, as an argument
+to exists() is an error.
+
+ exists ⊂ # OK
+ exists &sub(); # Error
+
=item exit EXPR
Evaluates EXPR and exits immediately with that value. Example:
then you create non-Y2K-compliant programs--and you wouldn't want to do
that, would you?
+The proper way to get a complete 4-digit year is simply:
+
+ $year += 1900;
+
+And to get the last two digits of the year (e.g., '01' in 2001) do:
+
+ $year = sprintf("%02d", $year % 100);
+
If EXPR is omitted, does C<gmtime(time())>.
In scalar context, returns the ctime(3) value:
then you create non-Y2K-compliant programs--and you wouldn't want to do
that, would you?
+The proper way to get a complete 4-digit year is simply:
+
+ $year += 1900;
+
+And to get the last two digits of the year (e.g., '01' in 2001) do:
+
+ $year = sprintf("%02d", $year % 100);
+
If EXPR is omitted, uses the current time (C<localtime(time)>).
In scalar context, returns the ctime(3) value:
(But only within the lexical scope of the C<our> declaration. In this
it differs from "use vars", which is package scoped.)
+An C<our> declaration declares a global variable that will be visible
+across its entire lexical scope, even across package boundaries. The
+package in which the variable is entered is determined at the point
+of the declaration, not at the point of use. This means the following
+behavior holds:
+
+ package Foo;
+ our $bar; # declares $Foo::bar for rest of lexical scope
+ $bar = 20;
+
+ package Bar;
+ print $bar; # prints 20
+
+Multiple C<our> declarations in the same lexical scope are allowed
+if they are in different packages. If they happened to be in the same
+package, Perl will emit warnings if you have asked for them.
+
+ use warnings;
+ package Foo;
+ our $bar; # declares $Foo::bar for rest of lexical scope
+ $bar = 20;
+
+ package Bar;
+ our $bar = 30; # declares $Bar::bar for rest of lexical scope
+ print $bar; # prints 30
+
+ our $bar; # emits warning
+
=item pack TEMPLATE,LIST
Takes a LIST of values and converts it into a string using the rules
open files, or pre-existing files. Check L<perlport> and either the
rename(2) manpage or equivalent system documentation for details.
+=item require VERSION
+
=item require EXPR
=item require
Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied. If EXPR is numeric, demands that the current version of Perl
-(C<$]> or $PERL_VERSION) be equal or greater than EXPR.
+supplied. If a version number or tuple is specified, or if EXPR is
+numeric, demands that the current version of Perl
+(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR.
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
array, returns the undefined value. If ARRAY is omitted, shifts the
C<@_> array within the lexical scope of subroutines and formats, and the
C<@ARGV> array at file scopes or within the lexical scopes established by
-the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<STOP {}>, and C<END {}>
+the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}>
constructs.
See also C<unshift>, C<push>, and C<pop>. C<Shift()> and C<unshift> do the
5 gid numeric group ID of file's owner
6 rdev the device identifier (special files only)
7 size total size of file, in bytes
- 8 atime last access time since the epoch
- 9 mtime last modify time since the epoch
- 10 ctime inode change time (NOT creation time!) since the epoch
+ 8 atime last access time in seconds since the epoch
+ 9 mtime last modify time in seconds since the epoch
+ 10 ctime inode change time (NOT creation time!) in seconds since the epoch
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocated
except that Module I<must> be a bareword.
-If the first argument to C<use> is a number, it is treated as a version
-number instead of a module name. If the version of the Perl interpreter
-is less than VERSION, then an error message is printed and Perl exits
-immediately. This is often useful if you need to check the current
-Perl version before C<use>ing library modules that have changed in
-incompatible ways from older versions of Perl. (We try not to do
-this more than we have to.)
+If the first argument to C<use> is a number or a version tuple, it is
+treated as a version instead of a module name. If the version
+of the Perl interpreter is less than VERSION, then an error message
+is printed and Perl exits immediately.
+
+ use 5.005_03; # version number
+ use v5.6.0; # version tuple
+
+This is often useful if you need to check the current Perl version before
+C<use>ing library modules that have changed in incompatible ways from
+older versions of Perl. (We try not to do this more than we have to.)
The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been