$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 ever existed
- %hash = (); # completely empty %hash
- undef %hash; # forget %hash every 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
=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 $array{$key};
- print "Defined\n" if defined $array{$key};
- print "True\n" if $array{$key};
+ print "Exists\n" if exists $hash{$key};
+ print "Defined\n" if defined $hash{$key};
+ print "True\n" if $hash{$key};
-A hash element can be true only if it's defined, and defined if
+ print "Exists\n" if exists $array[$index];
+ print "Defined\n" if defined $array[$index];
+ print "True\n" if $array[$index];
+
+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:
OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
-you can use the symbolic names if import them from the Fcntl module,
+you can use the symbolic names if you import them from the Fcntl module,
either individually, or as a group using the ':flock' tag. LOCK_SH
requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
-releases a previously requested lock. If LOCK_NB is added to LOCK_SH or
-LOCK_EX then C<flock> will return immediately rather than blocking
+releases a previously requested lock. If LOCK_NB is bitwise-or'ed with
+LOCK_SH or LOCK_EX then C<flock> will return immediately rather than blocking
waiting for the lock (check the return status to see if you got it).
To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
(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
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
+And the following Perl-specific conversion:
+
+ %v a string, output as a tuple of integers ("Perl" is 80.101.114.108)
+
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
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
C<import> method any way it likes, though most modules just choose to
derive their C<import> method via inheritance from the C<Exporter> class that
is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
-method can be found then the error is currently silently ignored. This
-may change to a fatal error in a future version.
+method can be found then the call is skipped.
If you don't want your namespace altered, explicitly supply an empty list:
vec($image, $max_x * $x + $y, 8) = 3;
-Vectors created with C<vec> can also be manipulated with the logical
-operators C<|>, C<&>, and C<^>, which will assume a bit vector
-operation is desired when both operands are strings.
+If the selected element is off the end of the string, the value 0 is
+returned. If an element off the end of the string is written to,
+Perl will first extend the string with sufficiently many zero bytes.
+
+Strings created with C<vec> can also be manipulated with the logical
+operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit
+vector operation is desired when both operands are strings.
See L<perlop/"Bitwise String Operators">.
The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
projects / p5sagit/p5-mst-13.2.git / blobdiff