X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c440faa4100163019f5b91e9c5cbea6d0077be1e;hb=4ff31b786b9f6148fc8ea695db081861576d06a2;hp=65e019bf0641a962a2f624f9d86d776651854378;hpb=bbead3ca7e50b701f65ec6cf737d745fbe719760;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 65e019b..c440faa 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -982,7 +982,7 @@ X X X X Creates a digest string exactly like the crypt(3) function in the C library (assuming that you actually have a version there that has not -been extirpated as a potential munitions). +been extirpated as a potential munition). crypt() is a one-way hash function. The PLAINTEXT and SALT is turned into a short string, called a digest, which is returned. The same @@ -1012,7 +1012,7 @@ digest matter. Traditionally the result is a string of 13 bytes: two first bytes of the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only -the first eight bytes of the digest string mattered, but alternative +the first eight bytes of PLAINTEXT mattered. But alternative hashing schemes (like MD5), higher level security schemes (like C2), and implementations on non-UNIX platforms may produce different strings. @@ -1234,6 +1234,10 @@ lookup: delete $ref->[$x][$y][$index]; delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; +The C construct can also be used to localize the deletion +of array/hash elements to the current block. +See L. + =item die LIST X X X X X<$@> X @@ -1271,14 +1275,14 @@ produce, respectively See also exit(), warn(), and the Carp module. -If LIST is empty and C<$@> already contains a value (typically from a +If the output is empty and C<$@> already contains a value (typically from a previous eval) that value is reused after appending C<"\t...propagated">. This is useful for propagating exceptions: eval { ... }; die unless $@ =~ /Expected exception/; -If LIST is empty and C<$@> contains an object reference that has a +If the output is empty and C<$@> contains an object reference that has a C method, that method will be called with additional file and line number parameters. The return value replaces the value in C<$@>. i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> @@ -2117,7 +2121,7 @@ C. X X X Returns the current priority for a process, a process group, or a user. -(See L.) Will raise a fatal exception if used on a +(See C.) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2). =item getpwnam NAME @@ -2631,11 +2635,13 @@ the super-user). This is a useful way to check that a child process is 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. (On System V, a negative I -number will also kill process groups, but that's not portable.) That -means you usually want to use positive not negative signals. You may also -use a signal name in quotes. +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. See L for more details. @@ -2734,6 +2740,10 @@ block, file, or eval. If more than one value is listed, the list must be placed in parentheses. See L for details, including issues with tied arrays and hashes. +The C construct can also be used to localize the deletion +of array/hash elements to the current block. +See L. + =item localtime EXPR X X @@ -3274,7 +3284,7 @@ See L for detailed info on PerlIO. You may also, in the Bourne shell tradition, specify an EXPR beginning with C<< '>&' >>, in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be -duped (as L) and opened. You may use C<&> after C<< > >>, +duped (as C) and opened. You may use C<&> after C<< > >>, C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents @@ -3305,7 +3315,7 @@ C using various methods: If you specify C<< '<&=X' >>, where C is a file descriptor number or a filehandle, then Perl will do an equivalent of C's C of -that file descriptor (and not call L); this is more +that file descriptor (and not call C); this is more parsimonious of file descriptors. For example: # open for input, reusing the fileno of $fd @@ -3418,7 +3428,7 @@ but will not work on a filename which happens to have a trailing space, while will have exactly the opposite restrictions. -If you want a "real" C C (see L on your system), then you +If you want a "real" C C (see C on your system), then you should use the C function, which involves no such magic (but may use subtly different filemodes than Perl open(), which is mapped to C fopen()). This is @@ -4070,10 +4080,10 @@ Examples: The same template may generally also be used in unpack(). -=item package NAMESPACE -X X X +=item package NAMESPACE VERSION +X X X X -=item package +=item package NAMESPACE Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end @@ -4091,6 +4101,11 @@ If the package name is null, the C
package as assumed. That is, C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>, still seen in older code). +If VERSION is provided, C also sets the C<$VERSION> variable in the +given namespace. VERSION must be be a numeric literal or v-string; it is +parsed exactly the same way as a VERSION argument to C. +C<$VERSION> should only be set once per package. + See L for more information about packages, modules, and classes. See L for other scoping issues. @@ -4316,6 +4331,15 @@ 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, +which will set C<$_> on every iteration. + + opendir(my $dh, $some_dir) || die; + while(readdir $dh) { + print "$some_dir/$_\n"; + } + closedir $dh; + =item readline EXPR =item readline @@ -4324,12 +4348,12 @@ X X X Reads from the filehandle whose typeglob is contained in EXPR (or from *ARGV if EXPR is not provided). In scalar context, each call reads and returns the next line, until end-of-file is reached, whereupon the -subsequent call returns undef. In list context, reads until end-of-file +subsequent call returns C. In list context, reads until end-of-file is reached and returns a list of lines. Note that the notion of "line" used here is however you may have defined it with C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L. -When C<$/> is set to C, when readline() is in scalar +When C<$/> is set to C, when C is in scalar context (i.e. file slurp mode), and when an empty file is read, it returns C<''> the first time, followed by C subsequently. @@ -4340,19 +4364,29 @@ operator is discussed in more detail in L. $line = ; $line = readline(*STDIN); # same thing -If readline encounters an operating system error, C<$!> will be set with the -corresponding error message. It can be helpful to check C<$!> when you are -reading from filehandles you don't trust, such as a tty or a socket. The -following example uses the operator form of C, and takes the necessary -steps to ensure that C was successful. +If C encounters an operating system error, C<$!> will be set +with the corresponding error message. It can be helpful to check +C<$!> when you are reading from filehandles you don't trust, such as a +tty or a socket. The following example uses the operator form of +C and dies if the result is not defined. - for (;;) { - undef $!; - unless (defined( $line = <> )) { - die $! if $!; - last; # reached EOF + while ( ! eof($fh) ) { + defined( $_ = <$fh> ) or die "readline failed: $!"; + ... + } + +Note that you have can't handle C errors that way with the +C filehandle. In that case, you have to open each element of +C<@ARGV> yourself since C handles C differently. + + foreach my $arg (@ARGV) { + open(my $fh, $arg) or warn "Can't open $arg: $!"; + + while ( ! eof($fh) ) { + defined( $_ = <$fh> ) + or die "readline failed for $arg: $!"; + ... } - # ... } =item readlink EXPR @@ -4621,7 +4655,7 @@ 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 returning 0 at "end of file". If there is a filehandle, then the subroutine will be -called to act a simple source filter, with the line as read in C<$_>. +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. @@ -4675,7 +4709,7 @@ into package C
.) Here is a typical code layout: } # In the main program - push @INC, new Foo(...); + push @INC, Foo->new(...); Note that these hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See L. @@ -5274,7 +5308,7 @@ the original quicksort was faster. 5.8 has a sort pragma for limited control of the sort. Its rather blunt control of the underlying algorithm may not persist into future Perls, but the ability to characterize the input or output in implementation -independent ways quite probably will. See L. +independent ways quite probably will. See L. Examples: @@ -5365,9 +5399,26 @@ Examples: use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; +Warning: syntactical care is required when sorting the list returned from +a function. If you want to sort the list returned by the function call +C, you can use: + + @contact = sort { $a cmp $b } find_records @key; + @contact = sort +find_records(@key); + @contact = sort &find_records(@key); + @contact = sort(find_records(@key)); + +If instead you want to sort the array @key with the comparison routine +C then you can use: + + @contact = sort { find_records() } @key; + @contact = sort find_records(@key); + @contact = sort(find_records @key); + @contact = sort(find_records (@key)); + If you're using strict, you I declare $a and $b as lexicals. They are package globals. That means -if you're in the C
package and type +that if you're in the C
package and type @articles = sort {$b <=> $a} @files; @@ -5446,9 +5497,7 @@ Splits the string EXPR into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. (If all fields are empty, they are considered to be trailing.) -In scalar context, returns the number of fields found and splits into -the C<@_> array. Use of split in scalar context is deprecated, however, -because it clobbers your subroutine arguments. +In scalar context, returns the number of fields found. If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything @@ -5561,7 +5610,7 @@ X Returns a string formatted by the usual C conventions of the C library function C. See below for more details -and see L or L on your system for an explanation of +and see C or C on your system for an explanation of the general principles. For example: @@ -6447,6 +6496,9 @@ C, as described in L. Return value of -1 indicates a failure to start the program or an error of the wait(2) system call (inspect $! for the reason). +If you'd like to make C (and many other bits of Perl) die on error, +have a look at the L pragma. + Like C, C allows you to lie to a program about its name if you use the C syntax. Again, see L. @@ -6459,8 +6511,8 @@ value. system(@args) == 0 or die "system @args failed: $?" -You can check all the failure possibilities by inspecting -C<$?> like this: +If you'd like to manually inspect C's failure, you can check all +possible failure modes by inspecting C<$?> like this: if ($? == -1) { print "failed to execute: $!\n"; @@ -6930,6 +6982,9 @@ Cing library modules that won't work with older versions of Perl. Also, if the specified perl version is greater than or equal to 5.9.5, C will also load the C pragma and enable all features available in the requested version. See L. +Similarly, if the specified perl version is greater than or equal to +5.11.0, strictures are enabled lexically as with C (except +that the F file is not actually loaded). The C forces the C and C to happen at compile time. The C makes sure the module is loaded into memory if it hasn't been @@ -7309,7 +7364,7 @@ X Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or C<-1> if there are no child processes. The status is returned in C<$?> -and C<{^CHILD_ERROR_NATIVE}>. +and C<${^CHILD_ERROR_NATIVE}>. Note that a return value of C<-1> could mean that child processes are being automatically reaped, as described in L. @@ -7319,7 +7374,7 @@ X Waits for a particular child process to terminate and returns the pid of the deceased process, or C<-1> if there is no such child process. On some systems, a value of 0 indicates that there are processes still running. -The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say +The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say use POSIX ":sys_wait_h"; #... @@ -7363,7 +7418,7 @@ Prints the value of LIST to STDERR. If the last element of LIST does not end in a newline, it appends the same file/line number text as C does. -If LIST is empty and C<$@> already contains a value (typically from a +If the output is empty and C<$@> already contains a value (typically from a previous eval) that value is used after appending C<"\t...caught"> to C<$@>. This is useful for staying almost, but not entirely similar to C.