X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/dba7b06570fc6c08715b9cb0ae9b7662e7e6fee2..bf8b9e96e2b168f1f323a8c9066ae58cbe5b4ad9:/pod/perlfunc.pod diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index dbb8044..8f157fd 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -194,19 +194,19 @@ X C, C, C, C, C, C, C, C C, C<__FILE__>, C, C, C<__LINE__>, C, C<__PACKAGE__>, -C, C, C, C, C<__SUB__>, C +C, C, C, C<__SUB__>, C C is available only if you enable the experimental C<"switch"> -feature or use the C prefix. The C<"switch"> feature also enables +feature or use the C prefix. The C<"switch"> feature also enables the C, C and C statements, which are documented in -L. The C<"switch"> feature is enabled +L. The C<"switch"> feature is enabled automatically with a C (or higher) declaration in the current -scope. In Perl v5.14 and earlier, C required the C<"switch"> +scope. In Perl v5.14 and earlier, C required the C<"switch"> feature, like the other keywords. -C is only available with with the C<"evalbytes"> feature (see +C is only available with the C<"evalbytes"> feature (see L) or if prefixed with C. C<__SUB__> is only available -with with the C<"current_sub"> feature or if prefixed with C. Both +with the C<"current_sub"> feature or if prefixed with C. Both the C<"evalbytes"> and C<"current_sub"> features are enabled automatically with a C (or higher) declaration in the current scope. @@ -224,9 +224,7 @@ with a C (or higher) declaration in the current scope. =for Pod::Functions =Misc -C, C, C, C, -C, C, C, C, C, C, -C, C, C, C, C +C, C, C, C, C, C, C =item Functions for processes and process groups X X X @@ -396,7 +394,8 @@ operator may be any of: -M Script start time minus file modification time, in days. -A Same for access time. - -C Same for inode change time (Unix, may differ for other platforms) + -C Same for inode change time (Unix, may differ for other + platforms) Example: @@ -481,9 +480,9 @@ Example: print "Text\n" if -T _; print "Binary\n" if -B _; -As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file +As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file test operators, in a way that C<-f -w -x $file> is equivalent to -C<-x $file && -w _ && -f _>. (This is only fancy fancy: if you use +C<-x $file && -w _ && -f _>. (This is only fancy syntax: if you use the return value of C<-f $file> as an argument to another filetest operator, no special magic will happen.) @@ -706,7 +705,7 @@ in the CLASSNAME package. If CLASSNAME is omitted, the current package is used. Because a C is often the last thing in a constructor, it returns the reference for convenience. Always use the two-argument version if a derived class might inherit the function doing the blessing. -SeeL for more about the blessing (and blessings) of objects. +See L for more about the blessing (and blessings) of objects. Consider always blessing objects in CLASSNAMEs that are mixed case. Namespaces with all lowercase names are considered reserved for @@ -722,10 +721,10 @@ See L. Break out of a C block. -This keyword is enabled by the C<"switch"> feature: see -L for more information. You can also access it by -prefixing it with C. Alternately, include a C or later to the current scope. +This keyword is enabled by the C<"switch"> feature; see L for +more information on C<"switch">. You can also access it by prefixing it +with C. Alternatively, include a C or later to the +current scope. =item caller EXPR X X X X @@ -764,8 +763,10 @@ frame.) $subroutine may also be C<(unknown)> if this particular subroutine happens to have been deleted from the symbol table. C<$hasargs> is true if a new instance of C<@_> was set up for the frame. C<$hints> and C<$bitmask> contain pragmatic hints that the caller was -compiled with. The C<$hints> and C<$bitmask> values are subject to change -between versions of Perl, and are not meant for external use. +compiled with. C<$hints> corresponds to C<$^H>, and C<$bitmask> +corresponds to C<${^WARNING_BITS}>. The +C<$hints> and C<$bitmask> values are subject +to change between versions of Perl, and are not meant for external use. C<$hinthash> is a reference to a hash containing the value of C<%^H> when the caller was compiled, or C if C<%^H> was empty. Do not modify the values @@ -883,7 +884,8 @@ If VARIABLE is omitted, it chomps C<$_>. Example: # ... } -If VARIABLE is a hash, it chomps the hash's values, but not its keys. +If VARIABLE is a hash, it chomps the hash's values, but not its keys, +resetting the C iterator in the process. You can actually chomp anything that's an lvalue, including an assignment: @@ -912,7 +914,8 @@ X Chops off the last character of a string and returns the character chopped. It is much more efficient than C because it neither scans nor copies the string. If VARIABLE is omitted, chops C<$_>. -If VARIABLE is a hash, it chops the hash's values, but not its keys. +If VARIABLE is a hash, it chops the hash's values, but not its keys, +resetting the C iterator in the process. You can actually chop anything that's an lvalue, including an assignment. @@ -1379,9 +1382,9 @@ temporarily no longer exist. See L. %hash = (foo => 11, bar => 22, baz => 33); - $scalar = delete $hash{foo}; # $scalar is 11 - $scalar = delete @hash{qw(foo bar)}; # $scalar is 22 - @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33) + $scalar = delete $hash{foo}; # $scalar is 11 + $scalar = delete @hash{qw(foo bar)}; # $scalar is 22 + @array = delete @hash{qw(foo baz)}; # @array is (undef,33) The following (inefficiently) deletes all the values of %HASH and @ARRAY: @@ -1496,7 +1499,8 @@ before any manipulations. Here's an example: eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; if (my $ev_err = $@) { - if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) { + if (blessed($ev_err) + && $ev_err->isa("Some::Module::Exception")) { # handle Some::Module::Exception } else { @@ -1545,8 +1549,8 @@ See L for alternative strategies. =item do SUBROUTINE(LIST) X -This form of subroutine call is deprecated. SUBROUTINE can be a bareword, -a scalar variable or a subroutine beginning with C<&>. +This form of subroutine call is deprecated. SUBROUTINE can be a bareword +or scalar variable. =item do EXPR X @@ -1556,11 +1560,12 @@ file as a Perl script. do 'stat.pl'; -is just like +is largely like eval `cat stat.pl`; -except that it's more efficient and concise, keeps track of the current +except that it's more concise, runs no external processes, keeps track of +the current filename for error messages, searches the C<@INC> directories, and updates C<%INC> if the file is found. See L and L for these variables. It also differs in that code evaluated with C @@ -1595,6 +1600,8 @@ file. Manual error checking can be done this way: =item dump LABEL X X X +=item dump EXPR + =item dump =for Pod::Functions create an immediate core dump @@ -1607,7 +1614,9 @@ having initialized all your variables at the beginning of the program. When the new binary is executed it will begin by executing a C (with all the restrictions that C suffers). Think of it as a goto with an intervening core dump and reincarnation. -If C keyword, which always treats its input as a byte stream and works properly with source filters, and the L pragma. +Problems can arise if the string expands a scalar containing a floating +point number. That scalar can expand to letters, such as C<"NaN"> or +C<"Infinity">; or, within the scope of a C, the decimal +point character may be something other than a dot (such as a comma). +None of these are likely to parse as you are likely expecting. + In the second form, the code within the BLOCK is parsed only once--at the same time the code surrounding the C itself was parsed--and executed within the context of the current Perl program. This form is typically @@ -1885,10 +1919,10 @@ errors: { my $e; { - local $@; # protect existing $@ - eval { test_repugnancy() }; - # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only - $@ =~ /nefarious/ and $e = $@; + local $@; # protect existing $@ + eval { test_repugnancy() }; + # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only + $@ =~ /nefarious/ and $e = $@; } die $e if defined $e } @@ -1896,7 +1930,8 @@ errors: C does I count as a loop, so the loop control statements C, C, or C cannot be used to leave or restart the block. -An C executed within the C package doesn't see the usual +An C executed within a subroutine defined +in the C package doesn't see the usual surrounding lexical scope, but rather the scope of the first non-DB piece of code that called it. You don't normally need to worry about this unless you are writing a Perl debugger. @@ -1987,11 +2022,11 @@ program, passing it C<"surprise"> an argument. The second version didn't; it tried to run a program named I<"echo surprise">, didn't find it, and set C<$?> to a non-zero value indicating failure. -Beginning with v5.6.0, Perl attempts to flush all files opened for -output before the exec, but this may not be supported on some platforms -(see L). To be safe, you may need to set C<$|> ($AUTOFLUSH -in English) or call the C method of C on any -open handles to avoid lost output. +Perl attempts to flush all files opened for output before the exec, +but this may not be supported on some platforms (see L). +To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or +call the C method of C on any open handles +to avoid lost output. Note that C will not call your C blocks, nor will it invoke C methods on your objects. @@ -2093,7 +2128,7 @@ defined C routines first, but these C routines may not themselves abort the exit. Likewise any object destructors that need to be called are called before the real exit. C routines and destructors can change the exit status by modifying C<$?>. If this is a problem, you -can call C to avoid END and destructor processing. +can call C to avoid END and destructor processing. See L for details. Portability issues: L. @@ -2125,11 +2160,11 @@ regardless of case. Roughly, if you ever found yourself writing this - lc($this) eq lc($that) # Wrong! + lc($this) eq lc($that) # Wrong! # or - uc($this) eq uc($that) # Also wrong! + uc($this) eq uc($that) # Also wrong! # or - $this =~ /\Q$that/i # Right! + $this =~ /^\Q$that\E\z/i # Right! Now you can write @@ -2137,7 +2172,9 @@ Now you can write And get the correct results. -Perl only implements the full form of casefolding. +Perl only implements the full form of casefolding, +but you can access the simple folds using L and +L. For further information on casefolding, refer to the Unicode Standard, specifically sections 3.13 C, 4.2 C, and 5.18 C, @@ -2146,8 +2183,16 @@ Case Charts available at L. If EXPR is omitted, uses C<$_>. -This function behaves the same way under various pragma, such as in a locale, -as L does. +This function behaves the same way under various pragma, such as within +S>, as L does, with the single +exception of C of LATIN CAPITAL LETTER SHARP S (U+1E9E) within the +scope of S>. The foldcase of this character would +normally be C<"ss">, but as explained in the L section, case +changes that cross the 255/256 boundary are problematic under locales, +and are hence prohibited. Therefore, this function under locale returns +instead the string C<"\x{17F}\x{17F}">, which is the LATIN SMALL LETTER +LONG S. Since that character itself folds to C<"s">, the string of two +of them together should be equivalent to a single U+1E9E when foldcased. While the Unicode Standard defines two additional forms of casefolding, one for Turkic languages and one that never maps one character into multiple @@ -2155,7 +2200,7 @@ characters, these are not provided by the Perl core; However, the CPAN module C may be used to provide an implementation. This keyword is available only when the C<"fc"> feature is enabled, -or when prefixed with C; See L. Alternately, +or when prefixed with C; See L. Alternately, include a C or later to the current scope. =item fcntl FILEHANDLE,FUNCTION,SCALAR @@ -2224,8 +2269,14 @@ filehandle, generally its name. You can use this to find out whether two handles refer to the same underlying descriptor: - if (fileno(THIS) == fileno(THAT)) { + if (fileno(THIS) != -1 && fileno(THIS) == fileno(THAT)) { print "THIS and THAT are dups\n"; + } elsif (fileno(THIS) != -1 && fileno(THAT) != -1) { + print "THIS and THAT have different " . + "underlying file descriptors\n"; + } else { + print "At least one of THIS and THAT does " . + "not have a real file descriptor\n"; } =item flock FILEHANDLE,OPERATION @@ -2282,7 +2333,8 @@ and build a new Perl. Here's a mailbox appender for BSD systems. - use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants + # import LOCK_* and SEEK_END constants + use Fcntl qw(:flock SEEK_END); sub lock { my ($fh) = @_; @@ -2326,7 +2378,7 @@ fork(), great care has gone into making it extremely efficient (for example, using copy-on-write technology on data pages), making it the dominant paradigm for multitasking over the last few decades. -Beginning with v5.6.0, Perl attempts to flush all files opened for +Perl attempts to flush all files opened for output before forking the child process, but this may not be supported on some platforms (see L). To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or call the C method of @@ -2434,8 +2486,7 @@ is left as an exercise to the reader. The C function can do this more portably on systems purporting POSIX compliance. See also the C -module from your nearest CPAN site; details on CPAN can be found under -L. +module from your nearest L site. =item getlogin X X @@ -2491,7 +2542,7 @@ Returns the process id of the parent process. Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work around non-POSIX thread semantics the minority of Linux systems (and Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation -has since been removed. See the documentation for L<$$|perlvar/$$> for +has since been removed. See the documentation for L<$$|perlvar/$$> for details. Portability issues: L. @@ -2794,7 +2845,8 @@ Here's an example to test whether Nagle's algorithm is enabled on a socket: my $packed = getsockopt($socket, $tcp, TCP_NODELAY) or die "getsockopt TCP_NODELAY: $!"; my $nodelay = unpack("I", $packed); - print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n"; + print "Nagle's algorithm is turned ", + $nodelay ? "off\n" : "on\n"; Portability issues: L. @@ -2838,7 +2890,7 @@ each pairing of fruits and colors: @many = glob "{apple,tomato,cherry}={green,yellow,red}"; -Beginning with v5.6.0, this operator is implemented using the standard +This operator is implemented using the standard C extension. See L for details, including C which does not treat whitespace as a pattern separator. @@ -2869,7 +2921,7 @@ X X X =for Pod::Functions create spaghetti code -The C form finds the statement labeled with LABEL and +The C form finds the statement labeled with LABEL and resumes execution there. It can't be used to get out of a block or subroutine given to C. It can be used to go almost anywhere else within the dynamic scope, including out of subroutines, but it's @@ -2879,23 +2931,30 @@ The author of Perl has never felt the need to use this form of C does not offer named loops combined with loop control. Perl does, and this replaces most structured uses of C in other languages.) -The C form expects a label name, whose scope will be resolved +The C form expects to evaluate C to a code reference or +a label name. If it evaluates to a code reference, it will be handled +like C, below. This is especially useful for implementing +tail recursion via C. + +If the expression evaluates to a label name, its scope will be resolved dynamically. This allows for computed Cs per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability: goto ("FOO", "BAR", "GLARCH")[$i]; -As shown in this example, C is exempt from the "looks like a +As shown in this example, C is exempt from the "looks like a function" rule. A pair of parentheses following it does not (necessarily) delimit its argument. C is equivalent to C. +Also, unlike most named operators, this has the same precedence as +assignment. -Use of C or C to jump into a construct is +Use of C or C to jump into a construct is deprecated and will issue a warning. Even then, it may not be used to go into any construct that requires initialization, such as a subroutine or a C loop. It also can't be used to go into a construct that is optimized away. -The C form is quite different from the other forms of +The C form is quite different from the other forms of C. In fact, it isn't a goto in the normal sense at all, and doesn't have the stigma associated with other gotos. Instead, it exits the current subroutine (losing any changes set by local()) and @@ -2942,7 +3001,8 @@ or another C) actually modifies the element in the original list. This is usually something to be avoided when writing clear code. If C<$_> is lexical in the scope where the C appears (because it has -been declared with C) then, in addition to being locally aliased to +been declared with the deprecated C construct) +then, in addition to being locally aliased to the list elements, C<$_> keeps being lexical inside the block; i.e., it can't be seen from the outside, avoiding any potential side-effects. @@ -3016,7 +3076,8 @@ X Implements the ioctl(2) function. You'll probably first have to say - require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph + require "sys/ioctl.ph"; # probably in + # $Config{archlib}/sys/ioctl.ph to get the correct function definitions. If F doesn't exist or doesn't have the correct definitions you'll have to roll your @@ -3077,16 +3138,20 @@ named hash, or in Perl 5.12 or later only, the indices of an array. Perl releases prior to 5.12 will produce a syntax error if you try to use an array argument. In scalar context, returns the number of keys or indices. -The keys of a hash are returned in an apparently random order. The actual -random order is subject to change in future versions of Perl, but it -is guaranteed to be the same order as either the C or C -function produces (given that the hash has not been modified). Since -Perl 5.8.1 the ordering can be different even between different runs of -Perl for security reasons (see L). - -As a side effect, calling keys() resets the internal interator of the HASH or ARRAY -(see L). In particular, calling keys() in void context resets +Hash entries are returned in an apparently random order. The actual random +order is specific to a given hash; the exact same series of operations +on two hashes may result in a different order for each hash. Any insertion +into the hash may change the order, as will any deletion, with the exception +that the most recent key returned by C or C may be deleted +without changing the order. So long as a given hash is unmodified you may +rely on C, C and C to repeatedly return the same order +as each other. See L for +details on why hash order is randomized. Aside from the guarantees +provided here the exact details of Perl's hash algorithm and the hash +traversal order are subject to change in any release of Perl. + +As a side effect, calling keys() resets the internal iterator of the HASH or +ARRAY (see L). In particular, calling keys() in void context resets the iterator with no other overhead. Here is yet another way to print your environment: @@ -3158,24 +3223,40 @@ Sends a signal to a list of processes. Returns the number of processes successfully signaled (which is not necessarily the same as the number actually killed). - $cnt = kill 1, $child1, $child2; - kill 9, @goners; + $cnt = kill 'HUP', $child1, $child2; + kill 'KILL', @goners; + +SIGNAL may be either a signal name (a string) or a signal number. A signal +name may start with a C prefix, thus C and C refer to the +same signal. The string form of SIGNAL is recommended for portability because +the same signal may have different numbers in different operating systems. -If SIGNAL is zero, no signal is sent to the process, but C -checks whether it's I to send a signal to it (that -means, to be brief, that the process is owned by the same user, or we are +A list of signal names supported by the current platform can be found in +C<$Config{sig_name}>, which is provided by the C module. See L +for more details. + +A negative signal name is the same as a negative signal number, killing process +groups instead of processes. For example, C and +C will send C to +the entire process group specified. That +means you usually want to use positive not negative signals. + +If SIGNAL is either the number 0 or the string C (or C), +no signal is sent to +the process, but C checks whether it's I to send a signal to it +(that means, to be brief, that the process is owned by the same user, or we are the super-user). This is useful to check that a child process is still alive (even if only as a zombie) and hasn't changed its UID. See L for notes on the portability of this construct. -Unlike in the shell, if SIGNAL is negative, it kills process groups instead -of processes. That means you usually -want to use positive not negative signals. -You may also use a signal name in quotes. - The behavior of kill when a I number is zero or negative depends on the operating system. For example, on POSIX-conforming systems, zero will -signal the current process group and -1 will signal all processes. +signal the current process group, -1 will signal all processes, and any +other negative PROCESS number will act as a negative signal number and +kill the entire process group specified. + +If both the SIGNAL and the PROCESS are negative, the results are undefined. +A warning may be produced in a future version. See L for more details. @@ -3196,13 +3277,18 @@ Portability issues: L. =item last LABEL X X +=item last EXPR + =item last =for Pod::Functions exit a block prematurely The C command is like the C statement in C (as used in loops); it immediately exits the loop in question. If the LABEL is -omitted, the command refers to the innermost enclosing loop. The +omitted, the command refers to the innermost enclosing +loop. The C form, available starting in Perl +5.18.0, allows a label name to be computed at run time, +and is otherwise identical to C. The C block, if any, is not executed: LINE: while () { @@ -3221,6 +3307,11 @@ exit out of such a block. See also L for an illustration of how C, C, and C work. +Unlike most named operators, this has the same precedence as assignment. +It is also exempt from the looks-like-a-function rule, so +C will cause "bar" to be part of the argument to +C. + =item lc EXPR X X @@ -3239,19 +3330,9 @@ What gets returned depends on several factors: =item If C is in effect: -=over - -=item On EBCDIC platforms - -The results are what the C language system call C returns. - -=item On ASCII platforms - The results follow ASCII semantics. Only characters C change, to C respectively. -=back - =item Otherwise, if C (but not C) is in effect: Respects current LC_CTYPE locale for code points < 256; and uses Unicode @@ -3272,27 +3353,17 @@ many) where the 255/256 boundary would otherwise be crossed. Unicode semantics are used for the case change. -=item Otherwise, if C or C) is in effect: +=item Otherwise, if C or C is in effect: Unicode semantics are used for the case change. =item Otherwise: -=over - -=item On EBCDIC platforms - -The results are what the C language system call C returns. - -=item On ASCII platforms - ASCII semantics are used for the case change. The lowercase of any character outside the ASCII range is the character itself. =back -=back - =item lcfirst EXPR X X @@ -3314,7 +3385,7 @@ X X =item length -=for Pod::Functions return the number of bytes in a string +=for Pod::Functions return the number of characters in a string Returns the length in I of the value of EXPR. If EXPR is omitted, returns the length of C<$_>. If EXPR is undefined, returns @@ -3396,7 +3467,7 @@ C<$mday> is the day of the month and C<$mon> the month in the range C<0..11>, with 0 indicating January and 11 indicating December. This makes it easy to get a month name from a list: - my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ); + my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec); print "$abbr[$mon] $mday"; # $mon=9, $mday=18 gives "Oct 18" @@ -3567,7 +3638,8 @@ most cases. See also L for an array composed of those items of the original list for which the BLOCK or EXPR evaluates to true. If C<$_> is lexical in the scope where the C appears (because it has -been declared with C), then, in addition to being locally aliased to +been declared with the deprecated C construct), +then, in addition to being locally aliased to the list elements, C<$_> keeps being lexical inside the block; that is, it can't be seen from the outside, avoiding any potential side-effects. @@ -3581,17 +3653,18 @@ encounters the missing (or unexpected) comma. The syntax error will be reported close to the C<}>, but you'll need to change something near the C<{> such as using a unary C<+> to give Perl some help: - %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong - %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right - %hash = map { ("\L$_" => 1) } @array # this also works - %hash = map { lc($_) => 1 } @array # as does this. - %hash = map +( lc($_) => 1 ), @array # this is EXPR and works! + %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong + %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right + %hash = map { ("\L$_" => 1) } @array # this also works + %hash = map { lc($_) => 1 } @array # as does this. + %hash = map +( lc($_) => 1 ), @array # this is EXPR and works! - %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array) + %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array) or to force an anon hash constructor use C<+{>: - @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end + @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs + # comma at end to get a list of anonymous hashes each with only one entry apiece. @@ -3686,19 +3759,19 @@ and C documentation. Portability issues: L. -=item my EXPR +=item my VARLIST X -=item my TYPE EXPR +=item my TYPE VARLIST -=item my EXPR : ATTRS +=item my VARLIST : ATTRS -=item my TYPE EXPR : ATTRS +=item my TYPE VARLIST : ATTRS =for Pod::Functions declare and assign a local variable (lexical scoping) A C declares the listed variables to be local (lexically) to the -enclosing block, file, or C. If more than one value is listed, +enclosing block, file, or C. If more than one variable is listed, the list must be placed in parentheses. The exact semantics and interface of TYPE and ATTRS are still @@ -3708,9 +3781,16 @@ from Perl 5.8.0 also via the C module. See L for details, and L, L, and L. +Note that with a parenthesised list, C can be used as a dummy +placeholder, for example to skip assignment of initial values: + + my ( undef, $min, $hour ) = localtime; + =item next LABEL X X +=item next EXPR + =item next =for Pod::Functions iterate a block prematurely @@ -3725,7 +3805,9 @@ the next iteration of the loop: Note that if there were a C block on the above, it would get executed even on discarded lines. If LABEL is omitted, the command -refers to the innermost enclosing loop. +refers to the innermost enclosing loop. The C form, available +as of Perl 5.18.0, allows a label name to be computed at run time, being +otherwise identical to C. C cannot be used to exit a block which returns a value such as C, C, or C, and should not be used to exit @@ -3737,6 +3819,11 @@ that executes once. Thus C will exit such a block early. See also L for an illustration of how C, C, and C work. +Unlike most named operators, this has the same precedence as assignment. +It is also exempt from the looks-like-a-function rule, so +C will cause "bar" to be part of the argument to +C. + =item no MODULE VERSION LIST X X @@ -3918,7 +4005,7 @@ works for symmetry, but you really should consider writing something to the temporary file first. You will need to seek() to do the reading. -Since v5.8.0, Perl has built using PerlIO by default. Unless you've +Perl is built using PerlIO by default; Unless you've changed this (such as building Perl with C), you can open filehandles directly to Perl scalars via: @@ -3957,7 +4044,7 @@ General examples: # in-memory files open(MEMORY, ">", \$var) or die "Can't open memory file: $!"; - print MEMORY "foo!\n"; # output will appear in $var + print MEMORY "foo!\n"; # output will appear in $var # process argument list of files along with any includes @@ -4068,6 +4155,7 @@ For example, use either $child_pid = open(FROM_KID, "-|") // die "can't fork: $!"; or + $child_pid = open(TO_KID, "|-") // die "can't fork: $!"; followed by @@ -4076,7 +4164,7 @@ followed by # am the parent: # either write TO_KID or else read FROM_KID ... - wait $child_pid; + waitpid $child_pid, 0; } else { # am the child; use STDIN/STDOUT normally ... @@ -4117,7 +4205,7 @@ that intentionally contain shell metacharacters, such as: See L for more examples of this. -Beginning with v5.6.0, Perl will attempt to flush all files opened for +Perl will attempt to flush all files opened for output before any operation that may do a fork, but this may not be supported on some platforms (see L). To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or call the C method @@ -4200,7 +4288,7 @@ zero, typically at scope exit: } B The previous example has a bug because the automatic -close that happens when the refcount on C does not +close that happens when the refcount on C reaches zero does not properly detect and report failures. I close the handle yourself and inspect the return value. @@ -4240,37 +4328,37 @@ If EXPR is an empty string, returns 0. If EXPR is omitted, uses C<$_>. For the reverse, see L. See L for more about Unicode. -=item our EXPR +=item our VARLIST X X -=item our TYPE EXPR +=item our TYPE VARLIST -=item our EXPR : ATTRS +=item our VARLIST : ATTRS -=item our TYPE EXPR : ATTRS +=item our TYPE VARLIST : ATTRS =for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping) -C associates a simple name with a package variable in the current -package for use within the current scope. When C is in -effect, C lets you use declared global variables without qualifying -them with package names, within the lexical scope of the C declaration. -In this way C differs from C, which is package-scoped. +C makes a lexical alias to a package variable of the same name in the current +package for use within the current lexical scope. -Unlike C or C, which allocates storage for a variable and -associates a simple name with that storage for use within the current -scope, C associates a simple name with a package (read: global) -variable in the current package, for use within the current lexical scope. -In other words, C has the same scoping rules as C or C, but -does not necessarily create a variable. +C has the same scoping rules as C or C, but C only +declares an alias, whereas C or C both declare a variable name and +allocate storage for that name within the current scope. -If more than one value is listed, the list must be placed +This means that when C is in effect, C lets you use +a package variable without qualifying it with the package name, but only within +the lexical scope of the C declaration. In this way, C differs from +C, which allows use of an unqualified name I within the +affected package, but across scopes. + +If more than one variable is listed, the list must be placed in parentheses. our $foo; our($bar, $baz); -An C declaration declares a global variable that will be visible +An C declaration declares an alias for a package 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 @@ -4313,6 +4401,11 @@ from Perl 5.8.0, also via the C module. See L for details, and L, L, and L. +Note that with a parenthesised list, C can be used as a dummy +placeholder, for example to skip assignment of initial values: + + our ( undef, $min, $hour ) = localtime; + =item pack TEMPLATE,LIST X @@ -4424,6 +4517,28 @@ The C<< > >> and C<< < >> modifiers can also be used on C<()> groups to force a particular byte-order on all components in that group, including all its subgroups. +=begin comment + +Larry recalls that the hex and bit string formats (H, h, B, b) were added to +pack for processing data from NASA's Magellan probe. Magellan was in an +elliptical orbit, using the antenna for the radar mapping when close to +Venus and for communicating data back to Earth for the rest of the orbit. +There were two transmission units, but one of these failed, and then the +other developed a fault whereby it would randomly flip the sense of all the +bits. It was easy to automatically detect complete records with the correct +sense, and complete records with all the bits flipped. However, this didn't +recover the records where the sense flipped midway. A colleague of Larry's +was able to pretty much eyeball where the records flipped, so they wrote an +editor named kybble (a pun on the dog food Kibbles 'n Bits) to enable him to +manually correct the records and recover the data. For this purpose pack +gained the hex and bit string format specifiers. + +git shows that they were added to perl 3.0 in patch #44 (Jan 1991, commit +27e2fb84680b9cc1), but the patch description makes no mention of their +addition, let alone the story behind them. + +=end comment + The following rules apply: =over @@ -4606,14 +4721,14 @@ the I is the string length, not the number of strings. With an explicit repeat count for pack, the packed string is adjusted to that length. For example: - This code: gives this result: - - unpack("W/a", "\004Gurusamy") ("Guru") - unpack("a3/A A*", "007 Bond J ") (" Bond", "J") - unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".") + This code: gives this result: + + unpack("W/a", "\004Gurusamy") ("Guru") + unpack("a3/A A*", "007 Bond J ") (" Bond", "J") + unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".") - pack("n/a* w/a","hello,","world") "\000\006hello,\005world" - pack("a/W2", ord("a") .. ord("z")) "2ab" + pack("n/a* w/a","hello,","world") "\000\006hello,\005world" + pack("a/W2", ord("a") .. ord("z")) "2ab" The I is not returned explicitly from C. @@ -4712,7 +4827,7 @@ immediately below. See also L. =item * -Starting with Perl 5.9.2, integer and floating-point formats, along with +Starting with Perl 5.10.0, integer and floating-point formats, along with the C

and C

formats and C<()> groups, may all be followed by the C<< > >> or C<< < >> endianness modifiers to respectively enforce big- or little-endian byte-order. These modifiers are especially useful @@ -4961,7 +5076,7 @@ when they're one of the special identifiers that qualify into C, like C, C, C, and the punctuation variables. A package statement affects dynamic variables only, including those -you've used C on, but I lexical variables, which are created +you've used C on, but I lexically-scoped variables, which are created with C, C, or C. Typically it would be the first declaration in a file included by C or C. You can switch into a package in more than one place, since this only determines which default @@ -5001,6 +5116,8 @@ unless you are very careful. In addition, note that Perl's pipes use IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE after each command, depending on the application. +Returns true on success. + See L, L, and L for examples of such things. @@ -5120,17 +5237,24 @@ X =for Pod::Functions output a formatted list to a filehandle Equivalent to C, except that C<$\> -(the output record separator) is not appended. The first argument of the -list will be interpreted as the C format. See +(the output record separator) is not appended. The FORMAT and the +LIST are actually parsed as a single list. The first argument +of the list will be interpreted as the C format. This +means that C will use C<$_[0]> as the format. See L for an -explanation of the format argument. If you omit the LIST, C<$_> is used; -to use FILEHANDLE without a LIST, you must use a real filehandle like -C, not an indirect one like C<$fh>. If C (including +explanation of the format argument. If C (including C) is in effect and POSIX::setlocale() has been called, the character used for the decimal separator in formatted floating-point numbers is affected by the LC_NUMERIC locale setting. See L and L. +For historical reasons, if you omit the list, C<$_> is used as the format; +to use FILEHANDLE without a list, you must use a real filehandle like +C, not an indirect one like C<$fh>. However, this will rarely do what +you want; if $_ contains formatting codes, they will be replaced with the +empty string and a warning will be emitted if warnings are enabled. Just +use C if you want to print the contents of $_. + Don't fall into the trap of using a C when a simple C would do. The C is more efficient and less error prone. @@ -5145,8 +5269,8 @@ function has no prototype). FUNCTION is a reference to, or the name of, the function whose prototype you want to retrieve. If FUNCTION is a string starting with C, the rest is taken as a -name for a Perl builtin. If the builtin is not I (such as -C) or if its arguments cannot be adequately expressed by a prototype +name for a Perl builtin. If the builtin's arguments +cannot be adequately expressed by a prototype (such as C), prototype() returns C, because the builtin does not really behave like a Perl function. Otherwise, the string describing the equivalent prototype is returned. @@ -5270,7 +5394,7 @@ This protects against those locales where characters such as C<"|"> are considered to be word characters. Otherwise, Perl quotes non-ASCII characters using an adaptation from -Unicode (see L.) +Unicode (see L). The only code points that are quoted are those that have any of the Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space, Default_Ignorable_Code_Point, or General_Category=Control. @@ -5387,7 +5511,7 @@ C there, it would have been testing the wrong file. @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh); closedir $dh; -As of Perl 5.11.2 you can use a bare C in a C loop, +As of Perl 5.12 you can use a bare C in a C loop, which will set C<$_> on every iteration. opendir(my $dh, $some_dir) || die; @@ -5510,6 +5634,8 @@ case pretty much any characters can be read. =item redo LABEL X +=item redo EXPR + =item redo =for Pod::Functions start this loop iteration over again @@ -5517,7 +5643,9 @@ X The C command restarts the loop block without evaluating the conditional again. The C block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing -loop. Programs that want to lie to themselves about what was just input +loop. The C form, available starting in Perl 5.18.0, allows a +label name to be computed at run time, and is otherwise identical to C. Programs that want to lie to themselves about what was just input normally use this command: # a simpleminded Pascal comment stripper @@ -5548,6 +5676,11 @@ turn it into a looping construct. See also L for an illustration of how C, C, and C work. +Unlike most named operators, this has the same precedence as assignment. +It is also exempt from the looks-like-a-function rule, so +C will cause "bar" to be part of the argument to +C. + =item ref EXPR X X @@ -5638,19 +5771,31 @@ version should be used instead. require v5.6.1; # run time version check require 5.6.1; # ditto - require 5.006_001; # ditto; preferred for backwards compatibility + require 5.006_001; # ditto; preferred for backwards + compatibility Otherwise, C 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 essentially just a variety of C with the caveat that lexical variables in the invoking script will be invisible -to the included code. Has semantics similar to the following subroutine: +to the included code. If it were implemented in pure Perl, it +would have semantics similar to the following: + + use Carp 'croak'; + use version; sub require { my ($filename) = @_; + if ( my $version = eval { version->parse($filename) } ) { + if ( $version > $^V ) { + my $vn = $version->normal; + croak "Perl $vn required--this is only $^V, stopped"; + } + return 1; + } if (exists $INC{$filename}) { return 1 if $INC{$filename}; - die "Compilation failed in require"; + croak "Compilation failed in require"; } my ($realfilename,$result); ITER: { @@ -5658,19 +5803,25 @@ to the included code. Has semantics similar to the following subroutine: $realfilename = "$prefix/$filename"; if (-f $realfilename) { $INC{$filename} = $realfilename; - $result = do $realfilename; + my $caller = caller; + my $do_as_caller = eval qq{ + package $caller; + sub { do \$_[0] } + }; + $result = $do_as_caller->($realfilename); last ITER; } } - die "Can't find $filename in \@INC"; + croak "Can't locate $filename in \@INC"; } if ($@) { $INC{$filename} = undef; - die $@; + croak $@; } elsif (!$result) { delete $INC{$filename}; - die "$filename did not return true value"; + croak "$filename did not return true value"; } else { + $! = 0; return $result; } } @@ -5723,17 +5874,22 @@ Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets called with two parameters, the first a reference to itself, and the second the name of the file to be included (e.g., "F"). The -subroutine should return either nothing or else a list of up to three +subroutine should return either nothing or else a list of up to four values in the following order: =over =item 1 -A filehandle, from which the file will be read. +A reference to a scalar, containing any initial source code to prepend to +the file or generator output. =item 2 +A filehandle, from which the file will be read. + +=item 3 + A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per call, writing the line into C<$_> and returning 1, then finally at end of @@ -5742,7 +5898,7 @@ called to act as a simple source filter, with the line as read in C<$_>. Again, return 1 for each valid line, and 0 after all lines have been returned. -=item 3 +=item 4 Optional state for the subroutine. The state is passed in as C<$_[1]>. A reference to the subroutine itself is passed in as C<$_[0]>. @@ -5843,6 +5999,10 @@ scalar context, and (of course) nothing at all in void context. or do FILE automatically returns the value of the last expression evaluated.) +Unlike most named operators, this is also exempt from the +looks-like-a-function rule, so C will +cause "bar" to be part of the argument to C. + =item reverse LIST X X X @@ -5860,12 +6020,12 @@ in the opposite order. Used without arguments in scalar context, reverse() reverses C<$_>. $_ = "dlrow ,olleH"; - print reverse; # No output, list context - print scalar reverse; # Hello, world + print reverse; # No output, list context + print scalar reverse; # Hello, world Note that reversing an array to itself (as in C<@a = reverse @a>) will -preserve non-existent elements whenever possible, i.e., for non magical -arrays or tied arrays with C and C methods. +preserve non-existent elements whenever possible; i.e., for non-magical +arrays or for tied arrays with C and C methods. This operator is also handy for inverting a hash, although there are some caveats. If a value is duplicated in the original hash, only one of those @@ -6512,32 +6672,32 @@ Examples: # sort lexically @articles = sort @files; - + # same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files; - + # now case-insensitively @articles = sort {fc($a) cmp fc($b)} @files; - + # same thing in reversed order @articles = sort {$b cmp $a} @files; - + # sort numerically ascending @articles = sort {$a <=> $b} @files; - + # sort numerically descending @articles = sort {$b <=> $a} @files; - + # this sorts the %age hash by value instead of key # using an in-line function @eldest = sort { $age{$b} <=> $age{$a} } keys %age; - + # sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class; - + sub backwards { $b cmp $a } @harry = qw(dog cat x Cain Abel); @george = qw(gone chased yz Punished Axed); @@ -6584,15 +6744,15 @@ Examples: # using a prototype allows you to use any comparison subroutine # as a sort subroutine (including other package's subroutines) package other; - sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here - + sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are + # not set here package main; @new = sort other::backwards @old; - + # guarantee stability, regardless of algorithm use sort 'stable'; @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; - + # force use of mergesort (not portable outside Perl 5.8) use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; @@ -6659,8 +6819,8 @@ If LENGTH is omitted, removes everything from OFFSET onward. If LENGTH is negative, removes the elements from OFFSET onward except for -LENGTH elements at the end of the array. If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is -past the end of the array, Perl issues a warning, and splices at the -end of the array. +past the end of the array and a LENGTH was provided, Perl issues a warning, +and splices at the end of the array. The following equivalences hold (assuming C<< $#a >= $i >> ) @@ -6751,7 +6911,10 @@ instead treated as if it were C; in particular, this means that I contiguous whitespace (not just a single space character) is used as a separator. However, this special treatment can be avoided by specifying the pattern S> instead of the string S>, thereby allowing -only a single space character to be a separator. +only a single space character to be a separator. In earlier Perls this +special case was restricted to the use of a plain S> as the +pattern argument to split, in Perl 5.18.0 and later this special case is +triggered by any expression which evaluates as the simple string S>. If omitted, PATTERN defaults to a single space, S>, triggering the previously described I emulation. @@ -6797,9 +6960,9 @@ In time-critical applications, it is worthwhile to avoid splitting into more fields than necessary. Thus, when assigning to a list, if LIMIT is omitted (or zero), then LIMIT is treated as though it were one larger than the number of variables in the list; for the -following, LIMIT is implicitly 4: +following, LIMIT is implicitly 3: - ($login, $passwd, $remainder) = split(/:/); + ($login, $passwd) = split(/:/); Note that splitting an EXPR that evaluates to the empty string always produces zero fields, regardless of the LIMIT specified. @@ -6995,7 +7158,8 @@ use to separate the numbers: You can also explicitly specify the argument number to use for the join string using something like C<*2$v>; for example: - printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses + printf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses + @addr[1..3], ":"; =item (minimum) width @@ -7004,11 +7168,11 @@ display the given value. You can override the width by putting a number here, or get the width from the next argument (with C<*>) or from a specified argument (e.g., with C<*2$>): - printf "<%s>", "a"; # prints "" - printf "<%6s>", "a"; # prints "< a>" - printf "<%*s>", 6, "a"; # prints "< a>" - printf "<%*2$s>", "a", 6; # prints "< a>" - printf "<%2s>", "long"; # prints "" (does not truncate) + printf "<%s>", "a"; # prints "" + printf "<%6s>", "a"; # prints "< a>" + printf "<%*s>", 6, "a"; # prints "< a>" + printf '<%*2$s>', "a", 6; # prints "< a>" + printf "<%2s>", "long"; # prints "" (does not truncate) If a field width obtained through C<*> is negative, it has the same effect as the C<-> flag: left-justification. @@ -7087,7 +7251,8 @@ You cannot currently get the precision from a specified number, but it is intended that this will be possible in the future, for example using C<.*2$>: - printf "<%.*2$x>", 1, 6; # INVALID, but in future will print "<000001>" + printf '<%.*2$x>', 1, 6; # INVALID, but in future will print + # "<000001>" =item size @@ -7098,16 +7263,22 @@ whatever the default integer size is on your platform (usually 32 or 64 bits), but you can override this to use instead one of the standard C types, as supported by the compiler used to build Perl: - hh interpret integer as C type "char" or "unsigned char" - on Perl 5.14 or later - h interpret integer as C type "short" or "unsigned short" - j interpret integer as C type "intmax_t" on Perl 5.14 - or later, and only with a C99 compiler (unportable) - l interpret integer as C type "long" or "unsigned long" - q, L, or ll interpret integer as C type "long long", "unsigned long long", - or "quad" (typically 64-bit integers) - t interpret integer as C type "ptrdiff_t" on Perl 5.14 or later - z interpret integer as C type "size_t" on Perl 5.14 or later + hh interpret integer as C type "char" or "unsigned + char" on Perl 5.14 or later + h interpret integer as C type "short" or + "unsigned short" + j interpret integer as C type "intmax_t" on Perl + 5.14 or later, and only with a C99 compiler + (unportable) + l interpret integer as C type "long" or + "unsigned long" + q, L, or ll interpret integer as C type "long long", + "unsigned long long", or "quad" (typically + 64-bit integers) + t interpret integer as C type "ptrdiff_t" on Perl + 5.14 or later + z interpret integer as C type "size_t" on Perl 5.14 + or later As of 5.14, none of these raises an exception if they are not supported on your platform. However, if warnings are enabled, a warning of the @@ -7124,7 +7295,8 @@ start running the program, put something like this at its top: You can find out whether your Perl supports quads via L: use Config; - if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) { + if ($Config{use64bitint} eq "define" + || $Config{longsize} >= 8) { print "Nice quads!\n"; } @@ -7142,7 +7314,7 @@ floating-point size to use on your platform via L: use Config; if ($Config{uselongdouble} eq "define") { - print "long doubles by default\n"; + print "long doubles by default\n"; } It can also be that long doubles and doubles are the same thing: @@ -7173,7 +7345,7 @@ So: uses C<$a> for the width, C<$b> for the precision, and C<$c> as the value to format; while: - printf "<%*1$.*s>", $a, $b; + printf '<%*1$.*s>', $a, $b; would use C<$a> for the width and precision, and C<$b> as the value to format. @@ -7181,10 +7353,10 @@ value to format. Here are some more examples; be aware that when using an explicit index, the C<$> may need escaping: - printf "%2\$d %d\n", 12, 34; # will print "34 12\n" - printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n" - printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n" - printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n" + printf "%2\$d %d\n", 12, 34; # will print "34 12\n" + printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n" + printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n" + printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n" =back @@ -7227,13 +7399,9 @@ of a recent vintage: use 5.014; # so srand returns the seed If C is not called explicitly, it is called implicitly without a -parameter at the first use of the C operator. However, this was not true -of versions of Perl before 5.004, so if your script will run under older -Perl versions, it should call C; otherwise most programs won't call -C at all. - -But there are a few situations in recent Perls where programs are likely to -want to call C. One is for generating predictable results generally for +parameter at the first use of the C operator. +However, there are a few situations where programs are likely to +want to call C. One is for generating predictable results, generally for testing or debugging. There, you use C, with the same C<$seed> each time. Another case is that you may want to call C after a C to avoid child processes sharing the same seed value as the @@ -7249,21 +7417,6 @@ truncate decimal numbers. This means C will usually produce the same results as C. To be safe, always pass C an integer. -In versions of Perl prior to 5.004 the default seed was just the -current C