C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
C<break> is available only if you enable the experimental C<"switch">
-feature or use the C<CORE::> prefix. The C<"switch"> feature also enables
+feature or use the C<CORE::> prefix. The C<"switch"> feature also enables
the C<default>, C<given> and C<when> statements, which are documented in
-L<perlsyn/"Switch Statements">. The C<"switch"> feature is enabled
+L<perlsyn/"Switch Statements">. The C<"switch"> feature is enabled
automatically with a C<use v5.10> (or higher) declaration in the current
-scope. In Perl v5.14 and earlier, C<continue> required the C<"switch">
+scope. In Perl v5.14 and earlier, C<continue> required the C<"switch">
feature, like the other keywords.
C<evalbytes> is only available with the C<"evalbytes"> feature (see
L<feature>) or if prefixed with C<CORE::>. C<__SUB__> is only available
-with the C<"current_sub"> feature or if prefixed with C<CORE::>. Both
+with the C<"current_sub"> feature or if prefixed with C<CORE::>. Both
the C<"evalbytes"> and C<"current_sub"> features are enabled automatically
with a C<use v5.16> (or higher) declaration in the current scope.
operator takes one argument, either a filename, a filehandle, or a dirhandle,
and tests the associated file to see if something is true about it. If the
argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
-Unless otherwise documented, it returns C<1> for true and C<''> for false, or
-the undefined value if the file doesn't exist. Despite the funny
-names, precedence is the same as any other named unary operator. The
-operator may be any of:
+Unless otherwise documented, it returns C<1> for true and C<''> for false.
+If the file doesn't exist or can't be examined, it returns C<undef> and
+sets C<$!> (errno). Despite the funny names, precedence is the same as any
+other named unary operator. The operator may be any of:
-r File is readable by effective uid/gid.
-w File is writable by effective uid/gid.
-f File is a plain file.
-d File is a directory.
- -l File is a symbolic link.
+ -l File is a symbolic link (false if symlinks aren't
+ supported by the file system).
-p File is a named pipe (FIFO), or Filehandle is a pipe.
-S File is a socket.
-b File is a block special file.
-g File has setgid bit set.
-k File has sticky bit set.
- -T File is an ASCII text file (heuristic guess).
+ -T File is an ASCII or UTF-8 text file (heuristic guess).
-B File is a "binary" file (opposite of -T).
-M Script start time minus file modification time, in days.
in effect. Read the documentation for the C<filetest> pragma for more
information.
-The C<-T> and C<-B> switches work as follows. The first block or so of the
-file is examined for odd characters such as strange control codes or
-characters with the high bit set. If too many strange characters (>30%)
-are found, it's a C<-B> file; otherwise it's a C<-T> file. Also, any file
-containing a zero byte in the first block is considered a binary file. If C<-T>
-or C<-B> is used on a filehandle, the current IO buffer is examined
+The C<-T> and C<-B> switches work as follows. The first block or so of
+the file is examined to see if it is valid UTF-8 that includes non-ASCII
+characters. If, so it's a C<-T> file. Otherwise, that same portion of
+the file is examined for odd characters such as strange control codes or
+characters with the high bit set. If more than a third of the
+characters are strange, it's a C<-B> file; otherwise it's a C<-T> file.
+Also, any file containing a zero byte in the examined portion is
+considered a binary file. (If executed within the scope of a L<S<use
+locale>|perllocale> which includes C<LC_CTYPE>, odd characters are
+anything that isn't a printable nor space in the current locale.) If
+C<-T> or C<-B> is used on a filehandle, the current IO buffer is
+examined
rather than the first block. Both C<-T> and C<-B> return true on an empty
file, or a file at EOF when testing a filehandle. Because you have to
read a file to do the C<-T> test, on most occasions you want to use a C<-f>
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.)
Break out of a C<given()> block.
-This keyword is enabled by the C<"switch"> feature: see
-L<feature> for more information. You can also access it by
-prefixing it with C<CORE::>. Alternately, include a C<use
-v5.10> or later to the current scope.
+This keyword is enabled by the C<"switch"> feature; see L<feature> for
+more information on C<"switch">. You can also access it by prefixing it
+with C<CORE::>. Alternatively, include a C<use v5.10> or later to the
+current scope.
=item caller EXPR
X<caller> X<call stack> X<stack> X<stack trace>
=for Pod::Functions get context of the current subroutine call
-Returns the context of the current subroutine call. In scalar context,
-returns the caller's package name if there I<is> a caller (that is, if
+Returns the context of the current pure perl subroutine call. In scalar
+context, returns the caller's package name if there I<is> a caller (that is, if
we're in a subroutine or C<eval> or C<require>) and the undefined value
-otherwise. In list context, returns
+otherwise. caller never returns XS subs and they are skipped. The next pure
+perl sub will appear instead of the XS
+sub in caller's return values. In list
+context, caller returns
# 0 1 2
($package, $filename, $line) = caller;
$wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
= caller($i);
-Here $subroutine may be C<(eval)> if the frame is not a subroutine
-call, but an C<eval>. In such a case additional elements $evaltext and
+Here, $subroutine is the function that the caller called (rather than the
+function containing the caller). Note that $subroutine may be C<(eval)> if
+the frame is not a subroutine call, but an C<eval>. In such a case
+additional elements $evaltext and
C<$is_require> are set: C<$is_require> is true if the frame is created by a
C<require> or C<use> statement, $evaltext contains the text of the
C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement,
# ...
}
-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<each> iterator in the process.
You can actually chomp anything that's an lvalue, including an assignment:
Chops off the last character of a string and returns the character
chopped. It is much more efficient than C<s/.$//s> 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<each> iterator in the process.
You can actually chop anything that's an lvalue, including an assignment.
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
$can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
-Portability issues: L<perlport/chmod>.
+Portability issues: L<perlport/chown>.
=item chr NUMBER
X<chr> X<character> X<ASCII> X<Unicode>
reasons, this call is restricted to the superuser. If FILENAME is
omitted, does a C<chroot> to C<$_>.
+B<NOTE:> It is good security practice to do C<chdir("/")> (to the root
+directory) immediately after a C<chroot()>.
+
Portability issues: L<perlport/chroot>.
=item close FILEHANDLE
delete() may also be used on arrays and array slices, but its behavior is less
straightforward. Although exists() will return false for deleted entries,
deleting array elements never changes indices of existing values; use shift()
-or splice() for that. However, if all deleted elements fall at the end of an
+or splice() for that. However, if any deleted elements fall at the end of an
array, the array's size shrinks to the position of the highest element that
-still tests true for exists(), or to 0 if none do.
+still tests true for exists(), or to 0 if none do. In other words, an
+array won't have trailing nonexistent elements after a delete.
-B<WARNING:> Calling delete on array values is deprecated and likely to
-be removed in a future version of Perl.
+B<WARNING:> Calling C<delete> on array values is strongly discouraged. The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
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<tied> hash
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
See L<perlsyn> for alternative strategies.
-=item do SUBROUTINE(LIST)
-X<do>
-
-This form of subroutine call is deprecated. SUBROUTINE can be a bareword,
-a scalar variable or a subroutine beginning with C<&>.
-
=item do EXPR
X<do>
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<perlvar/@INC> and L<perlvar/%INC> for
these variables. It also differs in that code evaluated with C<do FILENAME>
=item dump LABEL
X<dump> X<core> X<undump>
+=item dump EXPR
+
=item dump
=for Pod::Functions create an immediate core dump
program. When the new binary is executed it will begin by executing
a C<goto LABEL> (with all the restrictions that C<goto> suffers).
Think of it as a goto with an intervening core dump and reincarnation.
-If C<LABEL> is omitted, restarts the program from the top.
+If C<LABEL> is omitted, restarts the program from the top. The
+C<dump EXPR> form, available starting in Perl 5.18.0, allows a name to be
+computed at run time, being otherwise identical to C<dump LABEL>.
B<WARNING>: Any files opened at the time of the dump will I<not>
be open any more when the program is reincarnated, with possible
it as C<CORE::dump()>, if you don't want to be warned against a possible
typo.
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+C<dump ("foo")."bar"> will cause "bar" to be part of the argument to
+C<dump>.
+
Portability issues: L<perlport/dump>.
=item each HASH
(not the value) in a hash, or the index in an array.
Hash entries 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 in the same order as either the C<keys> or C<values>
-function would produce on the same (unmodified) hash. Since Perl
-5.8.2 the ordering can be different even between different runs of Perl
-for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+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<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> 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.
After C<each> has returned all entries from the hash or array, the next
call to C<each> returns the empty list in list context and C<undef> in
C<keys>, and C<values>. The iterator is implicitly reset when C<each> has
reached the end as just described; it can be explicitly reset by calling
C<keys> or C<values> on the hash or array. If you add or delete a hash's
-elements while iterating over it, entries may be skipped or duplicated--so
-don't do that. Exception: In the current implementation, it is always safe
-to delete the item most recently returned by C<each()>, so the following
-code works properly:
+elements while iterating over it, the effect on the iterator is
+unspecified; for example, entries may be skipped or duplicated--so don't
+do that. Exception: It is always safe to delete the item most recently
+returned by C<each()>, so the following code works properly:
while (($key, $value) = each %hash) {
print $key, "\n";
delete $hash{$key}; # This is safe
}
+Tied hashes may have a different ordering behaviour to perl's hash
+implementation.
+
This prints out your environment like the printenv(1) program,
but in a different order:
while (($key,$value) = each $hashref) { ... }
+As of Perl 5.18 you can use a bare C<each> in a C<while> loop,
+which will set C<$_> on every iteration.
+
+ while(each %ENV) {
+ print "$_=$ENV{$_}\n";
+ }
+
To avoid confusing would-be users of your code who are running earlier
versions of Perl with mysterious syntax errors, put this sort of thing at
the top of your file to signal that your code will work I<only> on Perls of
use 5.012; # so keys/values/each work on arrays
use 5.014; # so keys/values/each work on scalars (experimental)
+ use 5.018; # so each assigns to $_ in a lone while test
See also C<keys>, C<values>, and C<sort>.
=for Pod::Functions catch exceptions or compile and run code
-In the first form, the return value of EXPR is parsed and executed as if it
+In the first form, often referred to as a "string eval", the return
+value of EXPR is parsed and executed as if it
were a little Perl program. The value of the expression (which is itself
determined within scalar context) is first parsed, and if there were no
errors, executed as a block within the lexical context of the current Perl
always treats its input as a byte stream and works properly with source
filters, and the L<feature> 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<use locale>, 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<eval> itself was parsed--and executed
within the context of the current Perl program. This form is typically
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
-See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
+See L</warn>, L<perlvar>, and L<warnings>.
Note that, because C<eval> traps otherwise-fatal errors, it is useful for
determining whether a particular feature (such as C<socket> or C<symlink>)
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
-An C<eval ''> executed within the C<DB> package doesn't see the usual
+An C<eval ''> executed within a subroutine defined
+in the C<DB> 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.
exec ('foo') or print STDERR "couldn't exec foo: $!";
{ exec ('foo') }; print STDERR "couldn't exec foo: $!";
-If there is more than one argument in LIST, or if LIST is an array
-with more than one value, calls execvp(3) with the arguments in LIST.
-If there is only one scalar argument or an array with one element in it,
-the argument is checked for shell metacharacters, and if there are any,
-the entire argument is passed to the system's command shell for parsing
-(this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
-If there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp>, which is more efficient.
-Examples:
+If there is more than one argument in LIST, this calls execvp(3) with the
+arguments in LIST. If there is only one element in LIST, the argument is
+checked for shell metacharacters, and if there are any, the entire
+argument is passed to the system's command shell for parsing (this is
+C</bin/sh -c> on Unix platforms, but varies on other platforms). If
+there are no shell metacharacters in the argument, it is split into words
+and passed directly to C<execvp>, which is more efficient. Examples:
exec '/bin/echo', 'Your arguments are: ', @ARGV;
exec "sort $outfile | uniq";
If you don't really want to execute the first argument, but want to lie
to the program you are executing about its own name, you can specify
the program you actually want to run as an "indirect object" (without a
-comma) in front of the LIST. (This always forces interpretation of the
-LIST as a multivalued list, even if there is only a single scalar in
-the list.) Example:
+comma) in front of the LIST, as in C<exec PROGRAM LIST>. (This always
+forces interpretation of the LIST as a multivalued list, even if there
+is only a single scalar in the list.) Example:
$shell = '/bin/csh';
exec $shell '-sh'; # pretend it's a login shell
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<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH
-in English) or call the C<autoflush()> method of C<IO::Handle> on any
-open handles to avoid lost output.
+On Windows, only the C<exec PROGRAM LIST> indirect object syntax will
+reliably avoid using the shell; C<exec LIST>, even with more than one
+element, will fall back to the shell if the first spawn fails.
+
+Perl attempts to flush all files opened for output before the exec,
+but this may not be supported on some platforms (see L<perlport>).
+To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or
+call the C<autoflush()> method of C<IO::Handle> on any open handles
+to avoid lost output.
Note that C<exec> will not call your C<END> blocks, nor will it invoke
C<DESTROY> methods on your objects.
print "True\n" if $hash{$key};
exists may also be called on array elements, but its behavior is much less
-obvious and is strongly tied to the use of L</delete> on arrays. B<Be aware>
-that calling exists on array values is deprecated and likely to be removed in
-a future version of Perl.
+obvious and is strongly tied to the use of L</delete> on arrays.
+
+B<WARNING:> Calling C<exists> on array values is strongly discouraged. The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
print "Exists\n" if exists $array[$index];
print "Defined\n" if defined $array[$index];
If EXPR is omitted, uses C<$_>.
-This function behaves the same way under various pragma, such as in a locale,
-as L</lc> does.
+This function behaves the same way under various pragma, such as within
+S<C<"use feature 'unicode_strings">>, as L</lc> does, with the single
+exception of C<fc> of LATIN CAPITAL LETTER SHARP S (U+1E9E) within the
+scope of S<C<use locale>>. The foldcase of this character would
+normally be C<"ss">, but as explained in the L</lc> 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
C<Unicode::Casing> may be used to provide an implementation.
This keyword is available only when the C<"fc"> feature is enabled,
-or when prefixed with C<CORE::>; See L<feature>. Alternately,
+or when prefixed with C<CORE::>; See L<feature>. Alternately,
include a C<use v5.16> or later to the current scope.
=item fcntl FILEHANDLE,FUNCTION,SCALAR
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
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<perlport>). To be safe, you may need to set
C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
The C<POSIX::getattr> function can do this more portably on
systems purporting POSIX compliance. See also the C<Term::ReadKey>
-module from your nearest CPAN site; details on CPAN can be found under
-L<perlmodlib/CPAN>.
+module from your nearest L<CPAN|http://www.cpan.org> site.
=item getlogin
X<getlogin> X<login>
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<perlport/getppid>.
system C library. In list context, the return values from the
various get routines are as follows:
- ($name,$passwd,$uid,$gid,
- $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
- ($name,$passwd,$gid,$members) = getgr*
- ($name,$aliases,$addrtype,$length,@addrs) = gethost*
- ($name,$aliases,$addrtype,$net) = getnet*
- ($name,$aliases,$proto) = getproto*
- ($name,$aliases,$port,$proto) = getserv*
+ # 0 1 2 3 4
+ ( $name, $passwd, $gid, $members ) = getgr*
+ ( $name, $aliases, $addrtype, $net ) = getnet*
+ ( $name, $aliases, $port, $proto ) = getserv*
+ ( $name, $aliases, $proto ) = getproto*
+ ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
+ ( $name, $passwd, $uid, $gid, $quota,
+ $comment, $gcos, $dir, $shell, $expire ) = getpw*
+ # 5 6 7 8 9
(If the entry doesn't exist you get an empty list.)
@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<File::Glob> extension. See L<File::Glob> for details, including
C<bsd_glob> which does not treat whitespace as a pattern separator.
=for Pod::Functions create spaghetti code
-The C<goto-LABEL> form finds the statement labeled with LABEL and
+The C<goto LABEL> 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<sort>. It can be used to go almost anywhere
else within the dynamic scope, including out of subroutines, but it's
does not offer named loops combined with loop control. Perl does, and
this replaces most structured uses of C<goto> in other languages.)
-The C<goto-EXPR> form expects a label name, whose scope will be resolved
+The C<goto EXPR> form expects to evaluate C<EXPR> to a code reference or
+a label name. If it evaluates to a code reference, it will be handled
+like C<goto &NAME>, below. This is especially useful for implementing
+tail recursion via C<goto __SUB__>.
+
+If the expression evaluates to a label name, its scope will be resolved
dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
necessarily recommended if you're optimizing for maintainability:
goto ("FOO", "BAR", "GLARCH")[$i];
-As shown in this example, C<goto-EXPR> is exempt from the "looks like a
+As shown in this example, C<goto EXPR> is exempt from the "looks like a
function" rule. A pair of parentheses following it does not (necessarily)
delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
+Also, unlike most named operators, this has the same precedence as
+assignment.
-Use of C<goto-LABEL> or C<goto-EXPR> to jump into a construct is
+Use of C<goto LABEL> or C<goto EXPR> 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<foreach> loop. It also can't be used to go into a
construct that is optimized away.
-The C<goto-&NAME> form is quite different from the other forms of
+The C<goto &NAME> form is quite different from the other forms of
C<goto>. 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
This is usually something to be avoided when writing clear code.
If C<$_> is lexical in the scope where the C<grep> appears (because it has
-been declared with C<my $_>) then, in addition to being locally aliased to
+been declared with the deprecated C<my $_> 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.
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<values> or C<each>
-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<perlsec/"Algorithmic Complexity
-Attacks">).
+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<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> 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. Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
As a side effect, calling keys() resets the internal iterator of the HASH or
ARRAY (see L</each>). In particular, calling keys() in void context resets
=for Pod::Functions send a signal to a process or process group
-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;
-
-If SIGNAL is zero, no signal is sent to the process, but C<kill>
-checks whether it's I<possible> to send a signal to it (that
-means, to be brief, that the process is owned by the same user, or we are
+Sends a signal to a list of processes. Returns the number of arguments
+that were successfully used to signal (which is not necessarily the same
+as the number of processes actually killed, e.g. where a process group is
+killed).
+
+ $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<SIG> prefix, thus C<FOO> and C<SIGFOO> 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.
+
+A list of signal names supported by the current platform can be found in
+C<$Config{sig_name}>, which is provided by the C<Config> module. See L<Config>
+for more details.
+
+A negative signal name is the same as a negative signal number, killing process
+groups instead of processes. For example, C<kill '-KILL', $pgrp> and
+C<kill -9, $pgrp> will send C<SIGKILL> 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<ZERO> (or C<SIGZERO>),
+no signal is sent to
+the process, but C<kill> checks whether it's I<possible> 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<perlport> 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. A negative signal name is the
-same as a negative signal number, killing process groups instead of processes.
-For example, C<kill -KILL, $pgrp> will send C<SIGKILL> to the entire process
-group specified.
-
The behavior of kill when a I<PROCESS> number is zero or negative depends on
the operating system. For example, on POSIX-conforming systems, zero will
signal the current process group, -1 will signal all processes, and any
See L<perlipc/"Signals"> for more details.
-On some platforms such as Windows where the fork() system call is not available.
-Perl can be built to emulate fork() at the interpreter level.
+On some platforms such as Windows where the fork() system call is not
+available, Perl can be built to emulate fork() at the interpreter level.
This emulation has limitations related to kill that have to be considered,
for code running on Windows and in code intended to be portable.
=item last LABEL
X<last> X<break>
+=item last EXPR
+
=item last
=for Pod::Functions exit a block prematurely
The C<last> command is like the C<break> 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<last EXPR> form, available starting in Perl
+5.18.0, allows a label name to be computed at run time,
+and is otherwise identical to C<last LABEL>. The
C<continue> block, if any, is not executed:
LINE: while (<STDIN>) {
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> 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<last ("foo")."bar"> will cause "bar" to be part of the argument to
+C<last>.
+
=item lc EXPR
X<lc> X<lowercase>
=item If C<use bytes> is in effect:
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
+The results follow ASCII rules. Only the characters C<A-Z> change,
+to C<a-z> respectively.
-=item On ASCII platforms
+=item Otherwise, if C<use locale> for C<LC_CTYPE> is in effect:
-The results follow ASCII semantics. Only characters C<A-Z> change, to C<a-z>
-respectively.
-
-=back
-
-=item Otherwise, if C<use locale> (but not C<use locale ':not_characters'>) is in effect:
-
-Respects current LC_CTYPE locale for code points < 256; and uses Unicode
-semantics for the remaining code points (this last can only happen if
+Respects current C<LC_CTYPE> locale for code points < 256; and uses Unicode
+rules for the remaining code points (this last can only happen if
the UTF8 flag is also set). See L<perllocale>.
-A deficiency in this is that case changes that cross the 255/256
+Starting in v5.20, Perl wil use full Unicode rules if the locale is
+UTF-8. Otherwise, there is a deficiency in this scheme, which is that
+case changes that cross the 255/256
boundary are not well-defined. For example, the lower case of LATIN CAPITAL
-LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
-platforms). But under C<use locale>, the lower case of U+1E9E is
+LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
+platforms). But under C<use locale> (prior to v5.20 or not a UTF-8
+locale), the lower case of U+1E9E is
itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
current locale, and Perl has no way of knowing if that character even
exists in the locale, much less what code point it is. Perl returns
-the input character unchanged, for all instances (and there aren't
-many) where the 255/256 boundary would otherwise be crossed.
+a result that is above 255 (almost always the input character unchanged,
+for all instances (and there aren't many) where the 255/256 boundary
+would otherwise be crossed; and starting in v5.22, it raises a
+L<locale|perldiag/Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".> warning.
=item Otherwise, If EXPR has the UTF8 flag set:
-Unicode semantics are used for the case change.
+Unicode rules are used for the case change.
-=item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'>) is in effect:
+=item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'> is in effect:
-Unicode semantics are used for the case change.
+Unicode rules are used for the case change.
=item Otherwise:
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
-
-=item On ASCII platforms
-
-ASCII semantics are used for the case change. The lowercase of any character
+ASCII rules 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<lcfirst> X<lowercase>
=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<characters> of the value of EXPR. If EXPR is
omitted, returns the length of C<$_>. If EXPR is undefined, returns
the original list for which the BLOCK or EXPR evaluates to true.
If C<$_> is lexical in the scope where the C<map> appears (because it has
-been declared with C<my $_>), then, in addition to being locally aliased to
+been declared with the deprecated C<my $_> 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.
doesn't it won't realize something is wrong until it gets to the C<}> and
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:
+such as using a unary C<+> or semicolon 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 {; "\L$_" => 1 } @array # this also works
+ %hash = map { ("\L$_" => 1) } @array # as does this
+ %hash = map { lc($_) => 1 } @array # and this.
%hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
%hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
everyone happy.
To recursively create a directory structure, look at
-the C<mkpath> function of the L<File::Path> module.
+the C<make_path> function of the L<File::Path> module.
=item msgctl ID,CMD,ARG
X<msgctl>
Portability issues: L<perlport/msgsnd>.
-=item my EXPR
+=item my VARLIST
X<my>
-=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<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>. If more than one value is listed,
+enclosing block, file, or C<eval>. 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
-evolving. TYPE is currently bound to the use of the C<fields> pragma,
+evolving. TYPE may be a bareword, a constant declared
+with C<use constant>, or C<__PACKAGE__>. It is
+currently bound to the use of the C<fields> pragma,
and attributes are handled using the C<attributes> pragma, or starting
from Perl 5.8.0 also via the C<Attribute::Handlers> module. See
L<perlsub/"Private Variables via my()"> for details, and L<fields>,
L<attributes>, and L<Attribute::Handlers>.
+Note that with a parenthesised list, C<undef> can be used as a dummy
+placeholder, for example to skip assignment of initial values:
+
+ my ( undef, $min, $hour ) = localtime;
+
=item next LABEL
X<next> X<continue>
+=item next EXPR
+
=item next
=for Pod::Functions iterate a block prematurely
Note that if there were a C<continue> 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<next EXPR> form, available
+as of Perl 5.18.0, allows a label name to be computed at run time, being
+otherwise identical to C<next LABEL>.
C<next> cannot be used to exit a block which returns a value such as
C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> 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<next ("foo")."bar"> will cause "bar" to be part of the argument to
+C<next>.
+
=item no MODULE VERSION LIST
X<no declarations>
X<unimporting>
considered a symbolic reference, so C<use strict "refs"> should I<not> be
in effect.)
-If EXPR is omitted, the global (package) scalar variable of the same
-name as the FILEHANDLE contains the filename. (Note that lexical
-variables--those declared with C<my> or C<state>--will not work for this
-purpose; so if you're using C<my> or C<state>, specify EXPR in your
-call to open.)
-
If three (or more) arguments are specified, the open mode (including
optional encoding) in the second argument are distinct from the filename in
the third. If MODE is C<< < >> or nothing, the file is opened for input.
modules that can help with that problem)) always check
the return value from opening a file.
+The filehandle will be closed when its reference count reaches zero.
+If it is a lexically scoped variable declared with C<my>, that usually
+means the end of the enclosing scope. However, this automatic close
+does not check for errors, so it is better to explicitly close
+filehandles, especially those used for writing:
+
+ close($handle)
+ || warn "close failed: $!";
+
+An older style is to use a bareword as the filehandle, as
+
+ open(FH, "<", "input.txt")
+ or die "cannot open < input.txt: $!";
+
+Then you can use C<FH> as the filehandle, in C<< close FH >> and C<<
+<FH> >> and so on. Note that it's a global variable, so this form is
+not recommended in new code.
+
+As a shortcut a one-argument call takes the filename from the global
+scalar variable of the same name as the filehandle:
+
+ $ARTICLE = 100;
+ open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
+
+Here C<$ARTICLE> must be a global (package) scalar variable - not one
+declared with C<my> or C<state>.
+
As a special case the three-argument form with a read/write mode and the third
argument being C<undef>:
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<Configure -Uuseperlio>), you can
open filehandles directly to Perl scalars via:
General examples:
- $ARTICLE = 100;
- open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
- while (<ARTICLE>) {...
-
open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved)
# if the open fails, output is discarded
See L<perlipc/"Safe Pipe Opens"> 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<perlport>). To be safe, you may need
to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
seek(HANDLE, 0, 0);
print "File contains: ", <HANDLE>;
-Using the constructor from the C<IO::Handle> package (or one of its
-subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
-filehandles that have the scope of the variables used to hold them, then
-automatically (but silently) close once their reference counts become
-zero, typically at scope exit:
-
- use IO::File;
- #...
- sub read_myfile_munged {
- my $ALL = shift;
- # or just leave it undef to autoviv
- my $handle = IO::File->new;
- open($handle, "<", "myfile") or die "myfile: $!";
- $first = <$handle>
- or return (); # Automatically closed here.
- mung($first) or die "mung failed"; # Or here.
- return (first, <$handle>) if $ALL; # Or here.
- return $first; # Or here.
- }
-
-B<WARNING:> The previous example has a bug because the automatic
-close that happens when the refcount on C<handle> reaches zero does not
-properly detect and report failures. I<Always> close the handle
-yourself and inspect the return value.
-
- close($handle)
- || warn "close failed: $!";
-
See L</seek> for some details about mixing reading and writing.
Portability issues: L<perlport/open>.
For the reverse, see L</chr>.
See L<perlunicode> for more about Unicode.
-=item our EXPR
+=item our VARLIST
X<our> X<global>
-=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<our> associates a simple name with a package variable in the current
-package for use within the current scope. When C<use strict 'vars'> is in
-effect, C<our> lets you use declared global variables without qualifying
-them with package names, within the lexical scope of the C<our> declaration.
-In this way C<our> differs from C<use vars>, which is package-scoped.
+C<our> makes a lexical alias to a package (i.e. global) variable of the
+same name in the current package for use within the current lexical scope.
+
+C<our> has the same scoping rules as C<my> or C<state>, meaning that it is
+only valid within a lexical scope. Unlike C<my> and C<state>, which both
+declare new (lexical) variables, C<our> only creates an alias to an
+existing variable: a package variable of the same name.
+
+This means that when C<use strict 'vars'> is in effect, C<our> lets you use
+a package variable without qualifying it with the package name, but only within
+the lexical scope of the C<our> declaration.
+
+ package Foo;
+ use strict;
+
+ $Foo::foo = 23;
+
+ {
+ our $foo; # alias to $Foo::foo
+ print $foo; # prints 23
+ }
+
+ print $Foo::foo; # prints 23
+
+ print $foo; # ERROR: requires explicit package name
+
+This works even if the package variable has not been used before, as
+package variables spring into existence when first used.
+
+ package Foo;
+ use strict;
+
+ our $foo = 23; # just like $Foo::foo = 23
-Unlike C<my> or C<state>, which allocates storage for a variable and
-associates a simple name with that storage for use within the current
-scope, C<our> 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<our> has the same scoping rules as C<my> or C<state>, but
-does not necessarily create a variable.
+ print $Foo::foo; # prints 23
-If more than one value is listed, the list must be placed
+If more than one variable is listed, the list must be placed
in parentheses.
- our $foo;
our($bar, $baz);
-An C<our> declaration declares a global variable that will be visible
+An C<our> 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
L<perlsub/"Private Variables via my()"> for details, and L<fields>,
L<attributes>, and L<Attribute::Handlers>.
+Note that with a parenthesised list, C<undef> can be used as a dummy
+placeholder, for example to skip assignment of initial values:
+
+ our ( undef, $min, $hour ) = localtime;
+
+C<our> differs from C<use vars>, which allows use of an unqualified name
+I<only> within the affected package, but across scopes.
+
=item pack TEMPLATE,LIST
X<pack>
D A float of long-double precision in native format.
(Long doubles are available only if your system supports
long double values _and_ if Perl has been compiled to
- support those. Raises an exception otherwise.)
+ support those. Raises an exception otherwise.
+ Note that there are different long double formats.)
p A pointer to a null-terminated string.
P A pointer to a structure (fixed-length string).
! sSlLiI Forces native (short, long, int) sizes instead
of fixed (16-/32-bit) sizes.
- xX Make x and X act as alignment commands.
+ ! xX Make x and X act as alignment commands.
- nNvV Treat integers as signed instead of unsigned.
+ ! nNvV Treat integers as signed instead of unsigned.
- @. Specify position as byte offset in the internal
+ ! @. Specify position as byte offset in the internal
representation of the packed string. Efficient
but dangerous.
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
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", ".")
0x56 0x78 0x12 0x34
0x34 0x12 0x78 0x56
+These are called mid-endian, middle-endian, mixed-endian, or just weird.
+
You can determine your system endianness with this incantation:
printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
$ perl -V:byteorder
Byteorders C<"1234"> and C<"12345678"> are little-endian; C<"4321">
-and C<"87654321"> are big-endian.
+and C<"87654321"> are big-endian. Systems with multiarchitecture binaries
+will have C<"ffff">, signifying that static information doesn't work,
+one must use runtime probing.
For portably packed integers, either use the formats C<n>, C<N>, C<v>,
and C<V> or else use the C<< > >> and C<< < >> modifiers described
=item *
-Starting with Perl 5.9.2, integer and floating-point formats, along with
+Also floating point numbers have endianness. Usually (but not always)
+this agrees with the integer endianness. Even though most platforms
+these days use the IEEE 754 binary format, there are differences,
+especially if the long doubles are involved. You can see the
+C<Config> variables C<doublekind> and C<longdblkind> (also C<doublesize>,
+C<longdblsize>): the "kind" values are enums, unlike C<byteorder>.
+
+Portability-wise the best option is probably to keep to the IEEE 754
+64-bit doubles, and of agreed-upon endianness. Another possibility
+is the C<"%a">) format of C<printf>.
+
+=item *
+
+Starting with Perl 5.10.0, integer and floating-point formats, along with
the C<p> and C<P> 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
assumes additional C<""> arguments. If TEMPLATE requires fewer arguments
than given, extra arguments are ignored.
+=item *
+
+Attempting to pack the special floating point values C<Inf> and C<NaN>
+(infinity, also in negative, and not-a-number) into packed integer values
+(like C<"L">) is a fatal error. The reason for this is that there simply
+isn't any sensible mapping for these special values into integers.
+
=back
Examples:
like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables.
A package statement affects dynamic variables only, including those
-you've used C<local> on, but I<not> lexical variables, which are created
+you've used C<local> on, but I<not> lexically-scoped variables, which are created
with C<my>, C<state>, or C<our>. Typically it would be the first
declaration in a file included by C<require> or C<use>. You can switch into a
package in more than one place, since this only determines which default
=for Pod::Functions output a formatted list to a filehandle
Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
-(the output record separator) is not appended. The first argument of the
-list will be interpreted as the C<printf> 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<printf> format. This
+means that C<printf(@_)> will use C<$_[0]> as the format. See
L<sprintf|/sprintf FORMAT, LIST> 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<FH>, not an indirect one like C<$fh>. If C<use locale> (including
-C<use locale ':not_characters'>) is in effect and
+explanation of the format argument. If C<use locale> for C<LC_NUMERIC>
+Look for this throught pod
+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
+separator in formatted floating-point numbers is affected by the C<LC_NUMERIC>
locale setting. See L<perllocale> and L<POSIX>.
+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<FH>, 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<print> if you want to print the contents of $_.
+
Don't fall into the trap of using a C<printf> when a simple
C<print> would do. The C<print> is more efficient and less
error prone.
considered to be word characters.
Otherwise, Perl quotes non-ASCII characters using an adaptation from
-Unicode (see L<http://www.unicode.org/reports/tr31/>.)
+Unicode (see L<http://www.unicode.org/reports/tr31/>).
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.
@dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
closedir $dh;
-As of Perl 5.11.2 you can use a bare C<readdir> in a C<while> loop,
+As of Perl 5.12 you can use a bare C<readdir> in a C<while> loop,
which will set C<$_> on every iteration.
opendir(my $dh, $some_dir) || die;
=item redo LABEL
X<redo>
+=item redo EXPR
+
=item redo
=for Pod::Functions start this loop iteration over again
The C<redo> command restarts the loop block without evaluating the
conditional again. The C<continue> 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<redo EXPR> form, available starting in Perl 5.18.0, allows a
+label name to be computed at run time, and is otherwise identical to C<redo
+LABEL>. Programs that want to lie to themselves about what was just input
normally use this command:
# a simpleminded Pascal comment stripper
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> 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<redo ("foo")."bar"> will cause "bar" to be part of the argument to
+C<redo>.
+
=item ref EXPR
X<ref> X<reference>
=for Pod::Functions find out the type of thing being referenced
Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR
-is not specified, C<$_> will be used. The value returned depends on the
-type of thing the reference is a reference to.
+string otherwise. If EXPR is not specified, C<$_> will be used. The
+value returned depends on the type of thing the reference is a reference to.
+
Builtin types include:
SCALAR
VSTRING
Regexp
-If the referenced object has been blessed into a package, then that package
-name is returned instead. You can think of C<ref> as a C<typeof> operator.
+You can think of C<ref> as a C<typeof> operator.
if (ref($r) eq "HASH") {
print "r is a reference to a hash.\n";
The result C<Regexp> indicates that the argument is a regular expression
resulting from C<qr//>.
+If the referenced object has been blessed into a package, then that package
+name is returned instead. But don't use that, as it's now considered
+"bad practice". For one reason, an object could be using a class called
+C<Regexp> or C<IO>, or even C<HASH>. Also, C<ref> doesn't take into account
+subclasses, like C<isa> does.
+
+Instead, use C<blessed> (in the L<Scalar::Util> module) for boolean
+checks, C<isa> for specific class checks and C<reftype> (also from
+L<Scalar::Util>) for type checks. (See L<perlobj> for details and a
+C<blessed/isa> example.)
+
See also L<perlref>.
=item rename OLDNAME,NEWNAME
hasn't already been included. The file is included via the do-FILE
mechanism, which is essentially just a variety of C<eval> 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 (exists $INC{$filename}) {
- return 1 if $INC{$filename};
- die "Compilation failed in require";
- }
- my ($realfilename,$result);
- ITER: {
- foreach $prefix (@INC) {
- $realfilename = "$prefix/$filename";
- if (-f $realfilename) {
- $INC{$filename} = $realfilename;
- $result = do $realfilename;
- last ITER;
- }
- }
- die "Can't find $filename in \@INC";
- }
- if ($@) {
- $INC{$filename} = undef;
- die $@;
- } elsif (!$result) {
- delete $INC{$filename};
- die "$filename did not return true value";
- } else {
- return $result;
- }
+ 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};
+ croak "Compilation failed in require";
+ }
+
+ foreach $prefix (@INC) {
+ if (ref($prefix)) {
+ #... do other stuff - see text below ....
+ }
+ # (see text below about possible appending of .pmc
+ # suffix to $filename)
+ my $realfilename = "$prefix/$filename";
+ next if ! -e $realfilename || -d _ || -b _;
+ $INC{$filename} = $realfilename;
+ my $result = do($realfilename);
+ # but run in caller's namespace
+
+ if (!defined $result) {
+ $INC{$filename} = undef;
+ croak $@ ? "$@Compilation failed in require"
+ : "Can't locate $filename: $!\n";
+ }
+ if (!$result) {
+ delete $INC{$filename};
+ croak "$filename did not return true value";
+ }
+ $! = 0;
+ return $result;
+ }
+ croak "Can't locate $filename in \@INC ...";
}
Note that the file will not be included twice under the same specified
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<Foo/Bar.pm>"). 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
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]>.
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<return ("foo")."bar"> will
+cause "bar" to be part of the argument to C<return>.
+
=item reverse LIST
X<reverse> X<rev> X<invert>
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<EXISTS> and C<DELETE> methods.
+preserve non-existent elements whenever possible; i.e., for non-magical
+arrays or for tied arrays with C<EXISTS> and C<DELETE> 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
# 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);
# 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;
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 >> )
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
$a[$i] = $y splice(@a,$i,1,$y)
-Example, assuming array lengths are passed before arrays:
+C<splice> can be used, for example, to implement n-ary queue processing:
- sub aeq { # compare two list values
- my(@a) = splice(@_,0,shift);
- my(@b) = splice(@_,0,shift);
- return 0 unless @a == @b; # same len?
- while (@a) {
- return 0 if pop(@a) ne pop(@b);
- }
- return 1;
+ sub nary_print {
+ my $n = shift;
+ while (my @next_n = splice @_, 0, $n) {
+ say join q{ -- }, @next_n;
+ }
}
- if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
+
+ nary_print(3, qw(a b c d e f g h));
+ # prints:
+ # a -- b -- c
+ # d -- e -- f
+ # g -- h
Starting with Perl 5.14, C<splice> can take scalar EXPR, which must hold a
reference to an unblessed array. The argument will be dereferenced
I<any> 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<C</ />> instead of the string S<C<" ">>, 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<C<" ">> 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<C<" ">>.
If omitted, PATTERN defaults to a single space, S<C<" ">>, triggering
the previously described I<awk> emulation.
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
into the next argument in the parameter list
+ %a hexadecimal floating point
+ %A like %a, but using upper-case letters
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
exponent less than 100 is system-dependent: it may be three or less
(zero-padded as necessary). In other words, 1.23 times ten to the
-99th may be either "1.23e99" or "1.23e099".
+99th may be either "1.23e99" or "1.23e099". Similarly for C<%a> and C<%A>:
+the exponent or the hexadecimal digits may float: especially the
+"long doubles" Perl configuration option may cause surprises.
Between the C<%> and the format letter, you may specify several
additional attributes controlling the interpretation of the format.
printf "<%s>", "a"; # prints "<a>"
printf "<%6s>", "a"; # prints "< a>"
printf "<%*s>", 6, "a"; # prints "< a>"
- printf "<%*2$s>", "a", 6; # prints "< a>"
+ printf '<%*2$s>', "a", 6; # prints "< a>"
printf "<%2s>", "long"; # prints "<long>" (does not truncate)
If a field width obtained through C<*> is negative, it has the same
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
+ printf '<%.*2$x>', 1, 6; # INVALID, but in future will print
# "<000001>"
=item size
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
+ 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
+ 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
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
+ 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
+ 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
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:
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.
If C<use locale> (including C<use locale 'not_characters'>) 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. See L<perllocale>
+numbers is affected by the
C<LC_NUMERIC> locale. See L<perllocale>
and L<POSIX>.
=item sqrt EXPR
use 5.014; # so srand returns the seed
If C<srand()> is not called explicitly, it is called implicitly without a
-parameter at the first use of the C<rand> 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<srand>; otherwise most programs won't call
-C<srand()> at all.
-
-But there are a few situations in recent Perls where programs are likely to
+parameter at the first use of the C<rand> operator.
+However, there are a few situations where programs are likely to
want to call C<srand>. One is for generating predictable results, generally for
testing or debugging. There, you use C<srand($seed)>, with the same C<$seed>
each time. Another case is that you may want to call C<srand()>
produce the same results as C<srand(42.1)>. To be safe, always pass
C<srand> an integer.
-In versions of Perl prior to 5.004 the default seed was just the
-current C<time>. This isn't a particularly good seed, so many old
-programs supply their own seed value (often C<time ^ $$> or C<time ^
-($$ + ($$ << 15))>), but that isn't necessary any more.
-
-Frequently called programs (like CGI scripts) that simply use
-
- time ^ $$
-
-for a seed can fall prey to the mathematical property that
-
- a^b == (a+1)^(b+1)
-
-one-third of the time. So don't do that.
-
A typical use of the returned seed is for a test program which has too many
combinations to test comprehensively in the time available to it each run. It
can test a random subset each time, and should there be a failure, log the seed
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 in seconds since the epoch (*)
- 11 blksize preferred block size for file system I/O
- 12 blocks actual number of blocks allocated
+ 11 blksize preferred I/O size in bytes for interacting with the
+ file (may vary from file to file)
+ 12 blocks actual number of system-specific blocks allocated
+ on disk (often, but not always, 512 bytes each)
(The epoch was at 00:00 January 1, 1970 GMT.)
Portability issues: L<perlport/stat>.
-=item state EXPR
+=item state VARLIST
X<state>
-=item state TYPE EXPR
+=item state TYPE VARLIST
-=item state EXPR : ATTRS
+=item state VARLIST : ATTRS
-=item state TYPE EXPR : ATTRS
+=item state TYPE VARLIST : ATTRS
=for Pod::Functions +state declare and assign a persistent lexical variable
is entered.
See L<perlsub/"Persistent Private Variables"> for details.
+If more than one variable is listed, the list must be placed in
+parentheses. With a parenthesised list, C<undef> can be used as a
+dummy placeholder. However, since initialization of state variables in
+list context is currently not possible this would serve no purpose.
+
C<state> variables are enabled only when the C<use feature "state"> pragma
is in effect, unless the keyword is written as C<CORE::state>.
See also L<feature>.
=for Pod::Functions +current_sub the current subroutine, or C<undef> if not in a subroutine
-A special token that returns the a reference to the current subroutine, or
+A special token that returns a reference to the current subroutine, or
C<undef> outside of a subroutine.
+The behaviour of C<__SUB__> within a regex code block (such as C</(?{...})/>)
+is subject to change.
+
This token is only available under C<use v5.16> or the "current_sub"
feature. See L<feature>.
For historical reasons, some values work on almost every system
supported by Perl: 0 means read-only, 1 means write-only, and 2
means read/write. We know that these values do I<not> work under
-OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
+OS/390 and on the Macintosh; you probably don't want to
use them in new code.
If the file named by FILENAME does not exist and the C<open> call creates
Note that C<sysopen> depends on the fdopen() C library function.
On many Unix systems, fdopen() is known to fail when file descriptors
exceed a certain value, typically 255. If you need more file
-descriptors than that, consider rebuilding Perl to use the C<sfio>
-library, or perhaps using the POSIX::open() function.
+descriptors than that, consider using the POSIX::open() function.
See L<perlopentut> for a kinder, gentler explanation of opening files.
(this is C</bin/sh -c> on Unix platforms, but varies on other
platforms). If there are no shell metacharacters in the argument,
it is split into words and passed directly to C<execvp>, which is
-more efficient.
+more efficient. On Windows, only the C<system PROGRAM LIST> syntax will
+reliably avoid using the shell; C<system LIST>, even with more than one
+element, will fall back to the shell if the first spawn fails.
-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<perlport>). To be safe, you may need
to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
This function binds a variable to a package class that will provide the
implementation for the variable. VARIABLE is the name of the variable
to be enchanted. CLASSNAME is the name of a class implementing objects
-of correct type. Any additional arguments are passed to the C<new>
+of correct type. Any additional arguments are passed to the
+appropriate constructor
method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
or C<TIEHASH>). Typically these are arguments such as might be passed
-to the C<dbm_open()> function of C. The object returned by the C<new>
-method is also returned by the C<tie> function, which would be useful
+to the C<dbm_open()> function of C. The object returned by the
+constructor is also returned by the C<tie> function, which would be useful
if you want to access other methods in CLASSNAME.
Note that functions such as C<keys> and C<values> may return huge lists
UNSHIFT this, LIST
SPLICE this, offset, length, LIST
EXTEND this, count
+ DELETE this, key
+ EXISTS this, key
DESTROY this
UNTIE this
=for Pod::Functions transliterate a string
The transliteration operator. Same as C<y///>. See
-L<perlop/"Quote and Quote-like Operators">.
+L<perlop/"Quote-Like Operators">.
=item truncate FILEHANDLE,LENGTH
X<truncate>
BEGIN { require Module; Module->import( LIST ); }
except that Module I<must> be a bareword.
-The importation can be made conditional; see L<if>.
+The importation can be made conditional by using the L<if> module.
In the peculiar C<use VERSION> form, VERSION may be either a positive
decimal fraction such as 5.006, which will be compared to C<$]>, or a v-string
C<use>ing library modules that won't work with older versions of Perl.
(We try not to do this more than we have to.)
-C<use VERSION> also enables all features available in the requested
+C<use VERSION> also lexically enables all features available in the requested
version as defined by the C<feature> pragma, disabling any features
not in the requested version's feature bundle. See L<feature>.
Similarly, if the specified Perl version is greater than or equal to
-5.11.0, strictures are enabled lexically as
+5.12.0, strictures are enabled lexically as
with C<use strict>. Any explicit use of
C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
-before it. In both cases, the F<feature.pm> and F<strict.pm> files are
-not actually loaded.
+before it. Later use of C<use VERSION>
+will override all behavior of a previous
+C<use VERSION>, possibly removing the C<strict> and C<feature> added by
+C<use VERSION>. C<use VERSION> does not
+load the F<feature.pm> or F<strict.pm>
+files.
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
$atime = $mtime = time;
utime $atime, $mtime, @ARGV;
-Since Perl 5.7.2, if the first two elements of the list are C<undef>,
+Since Perl 5.8.0, if the first two elements of the list are C<undef>,
the utime(2) syscall from your C library is called with a null second
argument. On most systems, this will set the file's access and
modification times to the current time (i.e., equivalent to the example
an array; prior to that release, attempting to use an array argument will
produce a syntax error. In scalar context, returns the number of values.
-When called on a hash, the values 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<keys> or
-C<each> function would produce on the same (unmodified) hash. Since Perl
-5.8.1 the ordering is different even between different runs of Perl for
-security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+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<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> 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. Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
As a side effect, calling values() resets the HASH or ARRAY's internal
iterator, see L</each>. (In particular, calling values() in void context
Top of form processing is handled automatically: if there is insufficient
room on the current page for the formatted record, the page is advanced by
-writing a form feed, a special top-of-page format is used to format the new
+writing a form feed and a special top-of-page
+format is used to format the new
page header before the record is written. By default, the top-of-page
-format is the name of the filehandle with "_TOP" appended. This would be a
+format is the name of the filehandle with "_TOP" appended, or "top"
+in the current package if the former does not exist. This would be a
problem with autovivified filehandles, but it may be dynamically set to the
format of your choice by assigning the name to the C<$^> variable while
that filehandle is selected. The number of lines remaining on the current
=for Pod::Functions transliterate a string
The transliteration operator. Same as C<tr///>. See
-L<perlop/"Quote and Quote-like Operators">.
+L<perlop/"Quote-Like Operators">.
=back
=item gt
-=item if
-
=item le
=item lt
=item else
-=item elseif
-
=item elsif
=item for
=item foreach
+=item if
+
=item unless
=item until
These flow-control keywords are documented in L<perlsyn/"Compound Statements">.
+=item elseif
+
+The "else if" keyword is spelled C<elsif> in Perl. There's no C<elif>
+or C<else if> either. It does parse C<elseif>, but only to warn you
+about not using it.
+
+See the documentation for flow-control keywords in L<perlsyn/"Compound
+Statements">.
+
=back
=over
=item when
These flow-control keywords related to the experimental switch feature are
-documented in L<perlsyn/"Switch Statements"> .
+documented in L<perlsyn/"Switch Statements">.
=back
https://perl5.git.perl.org / perl5.git / blobdiff