X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=88cbb0a6e5fcd91ee83ac562bc89084254856163;hb=a3dfe201291c96fc01babd3d4782d52ba945f2a3;hp=c1bc4c5743a39a4fb56eba3fab69e486793872b5;hpb=820475bd7227fcbc2178bb45a4d501c4ccc2133b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index c1bc4c5..88cbb0a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -523,8 +523,8 @@ C statement. In particular, for a C statement, $filename is C<(eval)>, but $evaltext is undefined. (Note also that each C statement creates a C frame inside an C) frame. C<$hints> contains pragmatic hints that the caller was -compiled with. It currently only reflects the hint corresponding to -C. +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 @@ -539,8 +539,10 @@ previous time C was called. =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. +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 does nothing. It returns true upon success, false +otherwise. See the example under C. =item chmod LIST @@ -925,35 +927,55 @@ See also L, L, L. =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 Cd 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 Cd 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. + +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, prints the value of LIST to C and @@ -1386,27 +1408,46 @@ any C methods in your objects. =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{"A"}> -and C<$ref-E{"A"}-E{"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{"A"}> and C<$ref-E{"A"}-E{"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"}) { } @@ -1419,6 +1460,12 @@ release. See L 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: @@ -1512,11 +1559,11 @@ in the way of your getting your job done.) 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 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 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 @@ -2759,6 +2806,34 @@ declared global variable without qualifying it with a package name. (But only within the lexical scope of the C declaration. In this it differs from "use vars", which is package scoped.) +An C 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 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 @@ -3451,13 +3526,16 @@ for this. Other restrictions include whether it works on directories, open files, or pre-existing files. Check L 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 @@ -3829,7 +3907,7 @@ array by 1 and moving everything down. If there are no elements in the 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, C, C, C, and C +the C, C, C, C, and C constructs. See also C, C, and C. C and C do the @@ -4232,6 +4310,10 @@ In addition, Perl permits the following widely-supported conversions: %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: @@ -4390,9 +4472,9 @@ meaning of the fields: 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 @@ -5068,13 +5150,17 @@ package. It is exactly equivalent to except that Module I be a bareword. -If the first argument to C 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 Cing 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 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 +Cing 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 forces the C and C to happen at compile time. The C makes sure the module is loaded into memory if it hasn't been @@ -5084,8 +5170,7 @@ features back into the current package. The module can implement its C method any way it likes, though most modules just choose to derive their C method via inheritance from the C class that is defined in the C module. See L. If no C -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: @@ -5188,9 +5273,13 @@ to give the expression the correct precedence as in vec($image, $max_x * $x + $y, 8) = 3; -Vectors created with C 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 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. The following code will build up an ASCII string saying C<'PerlPerlPerl'>.