X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=a6af80aa78eeed769418df06c680d926b359034c;hb=a2bdc9a53b6d7221bdf979c28003d54de36d16e5;hp=2cc480cfe8137540432595e4e3992210c4de65a0;hpb=4633a7c4bad06b471d9310620b7fe8ddd158cccd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 2cc480c..a6af80a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -54,9 +54,9 @@ null list. Remember the following rule: -=over 5 +=over 8 -=item * +=item I @@ -70,6 +70,135 @@ last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. +=head2 Perl Functions by Category + +Here are Perl's functions (including things that look like +functions, like some of the keywords and named operators) +arranged by category. Some functions appear in more +than one place. + +=over + +=item Functions for SCALARs or strings + +chomp, chop, chr, crypt, hex, index, lc, lcfirst, length, +oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex, +sprintf, substr, tr///, uc, ucfirst, y/// + +=item Regular expressions and pattern matching + +m//, pos, quotemeta, s///, split, study + +=item Numeric functions + +abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, +srand + +=item Functions for real @ARRAYs + +pop, push, shift, splice, unshift + +=item Functions for list data + +grep, join, map, qw/STRING/, reverse, sort, unpack + +=item Functions for real %HASHes + +delete, each, exists, keys, values + +=item Input and output functions + +binmode, close, closedir, dbmclose, dbmopen, die, eof, +fileno, flock, format, getc, print, printf, read, readdir, +rewinddir, seek, seekdir, select, syscall, sysread, +syswrite, tell, telldir, truncate, warn, write + +=item Functions for fixed length data or records + +pack, read, syscall, sysread, syswrite, unpack, vec + +=item Functions for filehandles, files, or directories + +I<-X>, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link, +lstat, mkdir, open, opendir, readlink, rename, rmdir, +stat, symlink, umask, unlink, utime + +=item Keywords related to the control flow of your perl program + +caller, continue, die, do, dump, eval, exit, goto, last, +next, redo, return, sub, wantarray + +=item Keywords related to scoping + +caller, import, local, my, package, use + +=item Miscellaneous functions + +defined, dump, eval, formline, local, my, reset, scalar, +undef, wantarray + +=item Functions for processes and process groups + +alarm, exec, fork, getpgrp, getppid, getpriority, kill, +pipe, qx/STRING/, setpgrp, setpriority, sleep, system, +times, wait, waitpid + +=item Keywords related to perl modules + +do, import, no, package, require, use + +=item Keywords related to classes and object-orientedness + +bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use + +=item Low-level socket functions + +accept, bind, connect, getpeername, getsockname, +getsockopt, listen, recv, send, setsockopt, shutdown, +socket, socketpair + +=item System V interprocess communication functions + +msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop, +shmctl, shmget, shmread, shmwrite + +=item Fetching user and group info + +endgrent, endhostent, endnetent, endpwent, getgrent, +getgrgid, getgrnam, getlogin, getpwent, getpwnam, +getpwuid, setgrent, setpwent + +=item Fetching network info + +endprotoent, endservent, gethostbyaddr, gethostbyname, +gethostent, getnetbyaddr, getnetbyname, getnetent, +getprotobyname, getprotobynumber, getprotoent, +getservbyname, getservbyport, getservent, sethostent, +setnetent, setprotoent, setservent + +=item Time-related functions + +gmtime, localtime, time, times + +=item Functions new in perl5 + +abs, bless, chomp, chr, exists, formline, glob, import, lc, +lcfirst, map, my, no, prototype, qx, qw, readline, readpipe, +ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use + +* - C was a keyword in perl4, but in perl5 it is an +operator which can be used in expressions. + +=item Functions obsoleted in perl5 + +dbmclose, dbmopen + + +=back + +=head2 Alphabetical Listing of Perl Functions + + =over 8 =item -X FILEHANDLE @@ -212,13 +341,17 @@ L. =item binmode FILEHANDLE -Arranges for the file to be read or written in "binary" mode in -operating systems that distinguish between binary and text files. -Files that are not in binary mode have CR LF sequences translated to LF -on input and LF translated to CR LF on output. Binmode has no effect -under Unix; in DOS, it may be imperative--otherwise your DOS C library -may mangle your file. If FILEHANDLE is an expression, -the value is taken as the name of the filehandle. +Arranges for the file to be read or written in "binary" mode in operating +systems that distinguish between binary and text files. Files that are +not in binary mode have CR LF sequences translated to LF on input and LF +translated to CR LF on output. Binmode has no effect under Unix; in DOS +and similarly archaic systems, it may be imperative--otherwise your +DOS-damaged C library may mangle your file. The key distinction between +systems that need binmode and those that don't is their text file +formats. Systems like Unix and Plan9 that delimit lines with a single +character, and that encode that character in C as '\n', do not need +C. The rest need it. If FILEHANDLE is an expression, the value +is taken as the name of the filehandle. =item bless REF,CLASSNAME @@ -398,6 +531,16 @@ does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in L. +=item continue BLOCK + +Actually a flow control statement rather than a function. If there is a +C BLOCK attached to a BLOCK (typically in a C or +C), it is always executed just before the conditional is about to +be evaluated again, just like the third part of a C loop in C. Thus +it can be used to increment a loop variable, even when the loop has been +continued via the C statement (which is similar to the C C +statement). + =item cos EXPR Returns the cosine of EXPR (expressed in radians). If EXPR is omitted @@ -442,16 +585,16 @@ Breaks the binding between a DBM file and an associative array. [This function has been superseded by the tie() function.] -This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an associative array. ASSOC is the -name of the associative array. (Unlike normal open, the first argument -is I a filehandle, even though it looks like one). DBNAME is the -name of the database (without the F<.dir> or F<.pag> extension if any). If the -database does not exist, it is created with protection specified by -MODE (as modified by the umask()). If your system only supports the -older DBM functions, you may perform only one dbmopen() in your program. -In order versions of Perl, -if your system had neither DBM nor ndbm, calling dbmopen() produced a -fatal error; it now falls back to sdbm(3). +This binds a dbm(3), ndbm(3), sdbm(3), gdbm(), or Berkeley DB file to an +associative array. ASSOC is the name of the associative array. (Unlike +normal open, the first argument is I a filehandle, even though it +looks like one). DBNAME is the name of the database (without the F<.dir> +or F<.pag> extension if any). If the database does not exist, it is +created with protection specified by MODE (as modified by the umask()). +If your system only supports the older DBM functions, you may perform only +one dbmopen() in your program. In older versions of Perl, if your system +had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now +falls back to sdbm(3). If you don't have write access to the DBM file, you can only read associative array variables, not set them. If you want to test whether @@ -469,11 +612,13 @@ function to iterate over large DBM files. Example: } dbmclose(%HIST); -See also L for many other interesting possibilities. +See also L for a more general description of the pros and +cons of the various dbm apparoches, as well as L for a particularly +rich implementation. =item defined EXPR -Returns a boolean value saying whether the lvalue EXPR has a real value +Returns a boolean value saying whether EXPR has a real value or not. Many operations return the undefined value under exceptional conditions, such as end of file, uninitialized variable, system error and such. This function allows you to distinguish between an undefined @@ -497,6 +642,21 @@ Examples: See also undef(). +Note: many folks tend to overuse defined(), and then are surprised to +discover that the number 0 and the null string are, in fact, defined +concepts. For example, if you say + + "ab" =~ /a(.*)b/; + +the pattern match succeeds, and $1 is defined, despite the fact that it +matched "nothing". But it didn't really match nothing--rather, it +matched something that happened to be 0 characters long. This is all +very above-board and honest. When a function returns an undefined value, +it's an admission that it couldn't give you an honest answer. So +you should only use defined() when you're questioning the integrity +of what you're trying to do. At other times, a simple comparison to +0 or "" is what you want. + =item delete EXPR Deletes the specified value from its hash array. Returns the deleted @@ -616,11 +776,14 @@ Example: =item each ASSOC_ARRAY -Returns a 2-element array consisting of the key and value for the next -value of an associative array, so that you can iterate over it. +When called in a list context, returns a 2-element array consisting +of the key and value for the next element of an associative array, +so that you can iterate over it. When called in a scalar context, +returns the key only for the next element in the associative array. Entries are returned in an apparently random order. When the array is -entirely read, a null array is returned (which when assigned produces a -FALSE (0) value). The next call to each() after that will start +entirely read, a null array is returned in list context (which when +assigned produces a FALSE (0) value), and C is returned in a +scalar context. The next call to each() after that will start iterating again. The iterator can be reset only by reading all the elements from the array. You should not add elements to an array while you're iterating over it. There is a single iterator for each @@ -651,9 +814,9 @@ as terminals may lose the end-of-file condition if you do. An C without an argument uses the last file read as argument. Empty parentheses () may be used to indicate the pseudofile formed of the files listed on the command line, i.e. -C is reasonable to use inside a while (<>) loop to detect the end +C is reasonable to use inside a while (EE) loop to detect the end of only the last file. Use C or eof without the parentheses to -test I file in a while (<>) loop. Examples: +test I file in a while (EE) loop. Examples: # reset line numbering on each input file while (<>) { @@ -672,7 +835,7 @@ test I file in a while (<>) loop. Examples: } Practical hint: you almost never need to use C in Perl, because the -input operators return undef when they run out of data. Testing C +input operators return undef when they run out of data. =item eval EXPR @@ -730,7 +893,7 @@ reader wonder what else might be happening (nothing is).) Cases 3 and 4 likewise behave in the same way: they run the code <$x>, which does nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5 is a place where normally you I like to use double quotes, except -in that particular situation, you can just use symbolic references +that in that particular situation, you can just use symbolic references instead, as in case 6. =item exec LIST @@ -744,7 +907,7 @@ there is only one scalar argument, the argument is checked for shell metacharacters. If there are any, the entire argument is passed to C for parsing. If there are none, the argument is split into words and passed directly to execvp(), which is more efficient. -Note: exec() (and system(0) do not flush your output buffer, so you may +Note: exec() and system() do not flush your output buffer, so you may need to set C<$|> to avoid lost output. Examples: exec '/bin/echo', 'Your arguments are: ', @ARGV; @@ -823,7 +986,11 @@ value is taken as the name of the filehandle. Calls flock(2) on FILEHANDLE. See L for definition of OPERATION. Returns TRUE for success, FALSE on failure. Will produce a fatal error if used on a machine that doesn't implement either flock(2) or -fcntl(2). (fcntl(2) will be automatically used if flock(2) is missing.) +fcntl(2). The fcntl(2) system call will be automatically used if flock(2) +is missing from your system. This makes flock() the portable file locking +strategy, although it will only lock entire files, not records. Note also +that some versions of flock() cannot lock things over the network; you +would need to use the more system-specific fcntl() for that. Here's a mailbox appender for BSD systems. @@ -850,8 +1017,7 @@ Here's a mailbox appender for BSD systems. print MBOX $msg,"\n\n"; unlock(); -Note that many versions of flock() cannot lock things over the network. -You need to do locking with fcntl() for that. +See also L for other flock() examples. =item fork @@ -881,6 +1047,26 @@ fork() returns omitted); } waitpid($pid,0); +See also L for more examples of forking and reaping +moribund children. + +=item format + +Declare a picture format with use by the write() function. For +example: + + format Something = + Test: @<<<<<<<< @||||| @>>>>> + $str, $%, '$' . int($num) + . + + $str = "widget"; + $num = $cost/$quantiy; + $~ = 'Something'; + write; + +See L for many details and examples. + =item formline PICTURE, LIST @@ -908,14 +1094,13 @@ formline() always returns TRUE. See L for other examples. Returns the next character from the input file attached to FILEHANDLE, or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN. This is not particularly efficient. It cannot be used to get unbuffered -single-character +single-characters, however. For that, try something more like: if ($BSD_STYLE) { system "stty cbreak /dev/tty 2>&1"; } else { - system "stty", '-icanon', - system "stty", 'eol', "\001"; + system "stty", '-icanon', 'eol', "\001"; } $key = getc(STDIN); @@ -924,13 +1109,15 @@ single-character system "stty -cbreak /dev/tty 2>&1"; } else { - system "stty", 'icanon'; - system "stty", 'eol', '^@'; # ascii null + system "stty", 'icanon', 'eol', '^@'; # ascii null } print "\n"; Determination of whether to whether $BSD_STYLE should be set -is left as an exercise to the reader. +is left as an exercise to the reader. + +See also the C module from your nearest CPAN site; +details on CPAN can be found on L =item getlogin @@ -939,7 +1126,7 @@ getpwuid(). $login = getlogin || (getpwuid($<))[0] || "Kilroy"; -Do not consider getlogin() for authorentication: it is not as +Do not consider getlogin() for authentication: it is not as secure as getpwuid(). =item getpeername SOCKET @@ -1252,7 +1439,7 @@ or how about sorted by key: } To sort an array by value, you'll need to use a C -function. Here's a descending numeric sort by value: +function. Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) { printf "%4d %s\n", $hash{$key}, $key; @@ -1271,7 +1458,7 @@ Unlike in the shell, in Perl if the I 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. See the L man page for details. +use a signal name in quotes. See L for details. =item last LABEL @@ -1316,73 +1503,14 @@ it succeeded, FALSE otherwise. See example in L for tips for +dealing with this. The key distinction between systems that need binmode +and those that don't is their text file formats. Systems like Unix and +Plan9 that delimit lines with a single character, and that encode that +character in C as '\n', do not need C. The rest need it. + +Examples: $ARTICLE = 100; open ARTICLE or die "Can't find article $ARTICLE: $!\n"; @@ -1664,6 +1687,8 @@ subprocess. Examples: open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) + open(DBASE, '+/tmp/Tmp$$"); # $$ is our process id @@ -1696,6 +1721,8 @@ with ">&", in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) which is to be duped and opened. You may use & after >, >>, <, +>, +>> and +<. The mode you specify should match the mode of the original filehandle. +(Duping a filehandle does not take into acount any existing contents of +stdio buffers.) Here is a script that saves, redirects, and restores STDOUT and STDERR: @@ -1755,13 +1782,45 @@ Note: on any operation which may do a fork, unflushed buffers remain unflushed in both processes, which means you may need to set $| to avoid duplicate output. +Using the FileHandle constructor from the FileHandle package, +you can generate anonymous filehandles which have the scope of whatever +variables hold references to them, and automatically close whenever +and however you leave that scope: + + use FileHandle; + ... + sub read_myfile_munged { + my $ALL = shift; + my $handle = new FileHandle; + 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. + $first; # Or here. + } + The filename that is passed to open will have leading and trailing whitespace deleted. In order to open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace thusly: - $file =~ s#^(\s)#./$1#; - open(FOO, "< $file\0"); + $file =~ s#^(\s)#./$1#; + open(FOO, "< $file\0"); + +If you want a "real" C open() (see L on your system), then +you should use the sysopen() function. This is another way to +protect your filenames from interpretation. For example: + + use FileHandle; + sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700) + or die "sysopen $path: $!"; + HANDLE->autoflush(1); + HANDLE->print("stuff $$\n"); + seek(HANDLE, 0, 0); + print "File contains: ", ; + +See L for some details about mixing reading and writing. =item opendir DIRHANDLE,EXPR @@ -1866,6 +1925,25 @@ Examples: The same template may generally also be used in the unpack function. +=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 of +the enclosing block (the same scope as the local() operator). All further +unqualified dynamic identifiers will be in this namespace. A package +statement only affects dynamic variables--including those you've used +local() on--but I lexical variables created with my(). Typically it +would be the first declaration in a file to be included by the C +or C operator. You can switch into a package in more than one place; +it merely influences which symbol table is used by the compiler for the +rest of that block. You can refer to variables and filehandles in other +packages by prefixing the identifier with the package name and a double +colon: C<$Package::Variable>. If the package name is null, the C
+package as assumed. That is, C<$::sail> is equivalent to C<$main::sail>. + +See L for more information about packages, modules, +and classes. See L for other scoping issues. + =item pipe READHANDLE,WRITEHANDLE Opens a pair of connected pipes like the corresponding system call. @@ -1885,6 +1963,9 @@ Pops and returns the last value of the array, shortening the array by $tmp = $ARRAY[$#ARRAY--]; If there are no elements in the array, returns the undefined value. +If ARRAY is omitted, pops the +@ARGV array in the main program, and the @_ array in subroutines, just +like shift(). =item pos SCALAR @@ -1897,14 +1978,14 @@ in question. May be modified to change that offset. =item print -Prints a string or a comma-separated list of strings. Returns non-zero +Prints a string or a comma-separated list of strings. Returns TRUE if successful. FILEHANDLE may be a scalar variable name, in which case -the variable contains the name of the filehandle, thus introducing one +the variable contains the name of or a reference to the filehandle, thus introducing one level of indirection. (NOTE: If FILEHANDLE is a variable and the next token is a term, it may be misinterpreted as an operator unless you interpose a + or put parens around the arguments.) If FILEHANDLE is omitted, prints by default to standard output (or to the last selected -output channel--see select()). If LIST is also omitted, prints $_ to +output channel--see L). If LIST is also omitted, prints $_ to STDOUT. To set the default output channel to something other than STDOUT use the select operation. Note that, because print takes a LIST, anything in the LIST is evaluated in a list context, and any @@ -1915,7 +1996,7 @@ parenthesis to terminate the arguments to the print--interpose a + or put parens around all the arguments. Note that if you're storing FILEHANDLES in an array or other expression, -you will have to use a block returning its value instead +you will have to use a block returning its value instead: print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n"; @@ -1927,6 +2008,12 @@ you will have to use a block returning its value instead Equivalent to a "print FILEHANDLE sprintf(LIST)". The first argument of the list will be interpreted as the printf format. +=item prototype FUNCTION + +Returns the prototype of a function as a string (or C if the +function has no prototype). FUNCTION is a reference to the the +function whose prototype you want to retrieve. + =item push ARRAY,LIST Treats ARRAY as a stack, and pushes the values of LIST @@ -1990,6 +2077,14 @@ If used in a list context, returns all the rest of the entries in the directory. If there are no more entries, returns an undefined value in a scalar context or a null list in a list context. +If you're planning to filetest the return values out of a readdir(), you'd +better prepend the directory in question. Otherwise, since we didn't +chdir() there, it would have been testing the wrong file. + + opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!"; + @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); + closedir DIR; + =item readlink EXPR Returns the value of a symbolic link, if symbolic links are @@ -2104,11 +2199,12 @@ end such a file with "1;" unless you're sure it'll return TRUE otherwise. But it's better just to put the "C<1;>", in case you add more statements. -If EXPR is a bare word, the require assumes a "F<.pm>" extension for you, +If EXPR is a bare word, the require assumes a "F<.pm>" extension and +replaces "F<::>" with "F" in the filename for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace. -For a yet-more-powerful import facility, see the L and +For a yet-more-powerful import facility, see L and L. =item reset EXPR @@ -2131,7 +2227,7 @@ resets variables or searches in the current package. Always returns Resetting "A-Z" is not recommended since you'll wipe out your ARGV and ENV arrays. Only resets package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, -so anymore you probably want to use them instead. See L. +so you'll probably want to use them instead. See L. =item return LIST @@ -2177,7 +2273,15 @@ The substitution operator. See L. =item scalar EXPR Forces EXPR to be interpreted in a scalar context and returns the value -of EXPR. +of EXPR. + + @counts = ( scalar @a, scalar @b, scalar @c ); + +There is no equivalent operator to force an expression to +be interpolated in a list context because it's in practice never +needed. If you really wanted to do so, however, you could use +the construction C<@{[ (some expression) ]}>, but usually a simple +C<(some expression)> suffices. =item seek FILEHANDLE,POSITION,WHENCE @@ -2188,6 +2292,31 @@ POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for this from POSIX module. Returns 1 upon success, 0 otherwise. +On some systems you have to do a seek whenever you switch between reading +and writing. Amongst other things, this may have the effect of calling +stdio's clearerr(3). A "whence" of 1 (SEEK_CUR) is useful for not moving +the file pointer: + + seek(TEST,0,1); + +This is also useful for applications emulating C. Once you hit +EOF on your read, and then sleep for a while, you might have to stick in a +seek() to reset things. First the simple trick listed above to clear the +filepointer. The seek() doesn't change the current position, but it +I clear the end-of-file condition on the handle, so that the next +CFILEE> makes Perl try again to read something. Hopefully. + +If that doesn't work (some stdios are particularly cantankerous), then +you may need something more like this: + + for (;;) { + for ($curpos = tell(FILE); $_ = ; $curpos = tell(FILE)) { + # search for some stuff and put it into files + } + sleep($for_a_while); + seek(FILE, $curpos, 0); + } + =item seekdir DIRHANDLE,POS Sets the current position for the readdir() routine on DIRHANDLE. POS @@ -2251,19 +2380,24 @@ The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); -or to block until something becomes ready: +or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); +Most systems do not both to return anything useful in $timeleft, so +calling select() in a scalar context just returns $nfound. + Any of the bitmasks can also be undef. The timeout, if specified, is in seconds, which may be fractional. Note: not all implementations are capable of returning the $timeleft. If not, they always return $timeleft equal to the supplied $timeout. -You can effect a 250-microsecond sleep this way: +You can effect a 250-millisecond sleep this way: select(undef, undef, undef, 0.25); +B: Do not attempt to mix buffered I/O (like read() or ) +with select(). You have to use sysread() instead. =item semctl ID,SEMNUM,CMD,ARG @@ -2380,6 +2514,10 @@ On some older systems, it may sleep up to a full second less than what you requested, depending on how it counts seconds. Most modern systems always sleep the full amount. +For delays of finer granularity than one second, you may use Perl's +syscall() interface to access setitimer(2) if your system supports it, +or else see L below. + =item socket SOCKET,DOMAIN,TYPE,PROTOCOL Opens a socket of the specified kind and attaches it to filehandle @@ -2411,11 +2549,12 @@ value provides the name of the subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. -In the interests of efficiency the normal calling code for subroutines -is bypassed, with the following effects: the subroutine may not be a -recursive subroutine, and the two elements to be compared are passed -into the subroutine not via @_ but as $a and $b (see example below). -They are passed by reference, so don't modify $a and $b. +In the interests of efficiency the normal calling code for subroutines is +bypassed, with the following effects: the subroutine may not be a +recursive subroutine, and the two elements to be compared are passed into +the subroutine not via @_ but as the package global variables $a and +$b (see example below). They are passed by reference, so don't +modify $a and $b. And don't try to declare them as lexicals either. Examples: @@ -2425,6 +2564,9 @@ Examples: # same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files; + # now case-insensitively + @articles = sort { uc($a) cmp uc($b)} @files; + # same thing in reversed order @articles = sort {$b cmp $a} @files; @@ -2440,6 +2582,10 @@ Examples: } @sortedclass = sort byage @class; + # this sorts the %age associative arrays by value + # instead of key using an inline function + @eldest = sort { $age{$b} <=> $age{$a} } keys %age; + sub backwards { $b cmp $a; } @harry = ('dog','cat','x','Cain','Abel'); @george = ('gone','chased','yz','Punished','Axed'); @@ -2450,6 +2596,53 @@ Examples: print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz + # inefficiently sort by descending numeric compare using + # the first integer after the first = sign, or the + # whole record case-insensitively otherwise + + @new = sort { + ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0] + || + uc($a) cmp uc($b) + } @old; + + # same thing, but much more efficiently; + # we'll build auxiliary indices instead + # for speed + @nums = @caps = (); + for (@old) { + push @nums, /=(\d+)/; + push @caps, uc($_); + } + + @new = @old[ sort { + $nums[$b] <=> $nums[$a] + || + $caps[$a] cmp $caps[$b] + } 0..$#old + ]; + + # same thing using a Schwartzian Transform (no temps) + @new = map { $_->[0] } + sort { $b->[1] <=> $a->[1] + || + $a->[2] cmp $b->[2] + } map { [$_, /=(\d+)/, uc($_)] } @old; + +If you're and using strict, you I declare $a +and $b as lexicals. They are package globals. That means +if you're in the C
package, it's + + @articles = sort {$main::b <=> $main::a} @files; + +or just + + @articles = sort {$::b <=> $::a} @files; + +but if you're in the C package, it's + + @articles = sort {$FooPack::b <=> $FooPack::a} @files; + =item splice ARRAY,OFFSET,LENGTH,LIST =item splice ARRAY,OFFSET,LENGTH @@ -2528,7 +2721,7 @@ into more fields than you really need. If the PATTERN contains parentheses, additional array elements are created from each matching substring in the delimiter. - split(/([,-])/, "1-10,20"); + split(/([,-])/, "1-10,20", 3); produces the list value @@ -2567,10 +2760,11 @@ L, and L.) =item sprintf FORMAT,LIST Returns a string formatted by the usual printf conventions of the C -language. (The * character for an indirectly specified length is not +language. See L or L on your system for details. +(The * character for an indirectly specified length is not supported, but you can get the same effect by interpolating a variable -into the pattern.) Some C libraries' implementations of sprintf() can dump core -when fed ludiocrous arguments. +into the pattern.) Some C libraries' implementations of sprintf() can +dump core when fed ludicrous arguments. =item sqrt EXPR @@ -2579,12 +2773,13 @@ root of $_. =item srand EXPR -Sets the random number seed for the C operator. If EXPR is -omitted, does C. Of course, you'd need something much more -random than that for cryptographic purposes, since it's easy to guess -the current time. Checksumming the compressed output of rapidly -changing operating system status programs is the usual method. -Examples are posted regularly to comp.security.unix. +Sets the random number seed for the C operator. If EXPR is omitted, +uses a semirandom value based on the current time and process ID, among +other things. Of course, you'd need something much more random than that for +cryptographic purposes, since it's easy to guess the current time. +Checksumming the compressed output of rapidly changing operating system +status programs is the usual method. Examples are posted regularly to +the comp.security.unix newsgroup. =item stat FILEHANDLE @@ -2598,6 +2793,25 @@ the stat fails. Typically used as follows: $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename); +Not all fields are supported on all filesystem types. Here are the +meaning of the fields: + + dev device number of filesystem + ino inode number + mode file mode (type and permissions) + nlink number of (hard) links to the file + uid numeric user ID of file's owner + gid numer group ID of file's owner + rdev the device identifier (special files only) + size total size of file, in bytes + atime last access time since the epoch + mtime last modify time since the epoch + ctime inode change time (NOT creation type!) since the epoch + blksize preferred blocksize for file system I/O + blocks actual number of blocks allocated + +(The epoch was at 00:00 January 1, 1970 GMT.) + If stat is passed the special filehandle consisting of an underline, no stat is done, but the current contents of the stat structure from the last stat or filetest are returned. Example: @@ -2667,6 +2881,18 @@ out the names of those files that contain a match: print $file, "\n"; } +=item sub BLOCK + +=item sub NAME + +=item sub NAME BLOCK + +This is subroutine definition, not a real function I. With just a +NAME (and possibly prototypes), it's just a forward declaration. Without +a NAME, it's an anonymous function declaration, and does actually return a +value: the CODE ref of the closure you just created. See L and +L for details. + =item substr EXPR,OFFSET,LEN =item substr EXPR,OFFSET @@ -2712,6 +2938,27 @@ like numbers. Note that Perl only supports passing of up to 14 arguments to your system call, which in practice should usually suffice. +=item sysopen FILEHANDLE,FILENAME,MODE + +=item sysopen FILEHANDLE,FILENAME,MODE,PERMS + +Opens the file whose filename is given by FILENAME, and associates it +with FILEHANDLE. If FILEHANDLE is an expression, its value is used as +the name of the real filehandle wanted. This function calls the +underlying operating system's C function with the parameters +FILENAME, MODE, PERMS. + +The possible values and flag bits of the MODE parameter are +system-dependent; they are available via the standard module C. +However, for historical reasons, some values are universal: zero means +read-only, one means write-only, and two means read/write. + +If the file named by FILENAME does not exist and the C call +creates it (typically because MODE includes the O_CREAT flag), then +the value of PERMS specifies the permissions of the newly created +file. If PERMS is omitted, the default value is 0666, which allows +read and write for all. This default is reasonable: see C. + =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET =item sysread FILEHANDLE,SCALAR,LENGTH @@ -2731,7 +2978,9 @@ first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. The return value is the exit status of the program as returned by the wait() call. To get the actual exit value divide by -256. See also L. +256. See also L. This is I what you want to use to capture +the output from a command, for that you should merely use backticks, as +described in L. =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET @@ -2741,7 +2990,7 @@ Attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE, using the system call write(2). It bypasses stdio, so mixing this with prints may cause confusion. Returns the number of bytes actually written, or undef if there was an error. An -OFFSET may be specified to place the read data at some other place than +OFFSET may be specified to get the write data from some other place than the beginning of the string. =item tell FILEHANDLE @@ -2767,8 +3016,8 @@ to be enchanted. CLASSNAME is the name of a class implementing objects of correct type. Any additional arguments are passed to the "new" method of the class (meaning TIESCALAR, TIEARRAY, or TIEHASH). Typically these are arguments such as might be passed to the dbm_open() -function of C. The object returned by the "new" method +is also -returned by the tie() function, which would be useful if you +want to +function of C. The object returned by the "new" method is also +returned by the tie() function, which would be useful if you want to access other methods in CLASSNAME. Note that functions such as keys() and values() may return huge array @@ -2777,7 +3026,7 @@ use the each() function to iterate over such. Example: # print out history file offsets use NDBM_File; - tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0); + tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } @@ -2814,10 +3063,19 @@ Unlike dbmopen(), the tie() function will not use or require a module for you--you need to do that explicitly yourself. See L or the F module for interesting tie() implementations. +=item tied VARIABLE + +Returns a reference to the object underlying VARIABLE (the same value +that was originally returned by the tie() call which bound the variable +to a package.) Returns the undefined value if VARIABLE isn't tied to a +package. + =item time -Returns the number of non-leap seconds since 00:00:00 UTC, January 1, -1970. Suitable for feeding to gmtime() and localtime(). +Returns the number of non-leap seconds since whatever time the system +considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS, +and 00:00:00 UTC, January 1, 1970 for most other systems). +Suitable for feeding to gmtime() and localtime(). =item times @@ -2941,13 +3199,25 @@ reverse. =item use Module +=item use Module VERSION LIST + +=item use VERSION + Imports some semantics into the current package from the named module, generally by aliasing certain subroutine or variable names into your package. It is exactly equivalent to BEGIN { require Module; import Module LIST; } -If you don't want your namespace altered, use require instead. +except that Module I be a bare word. + +If the first argument to C is a number, it is treated as a version +number instead of a module name. If the version of the Perl interpreter +is less than VERSION, then an error message is printed and Perl exits +immediately. This is often useful if you need to check the current +Perl version before Cing library modules which have changed in +incompatible ways from older versions of Perl. (We try not to do +this more than we have to.) The BEGIN forces the require and import to happen at compile time. The require makes sure the module is loaded into memory if it hasn't been @@ -2956,7 +3226,19 @@ call into the "Module" package to tell the module to import the list of features back into the current package. The module can implement its import method any way it likes, though most modules just choose to derive their import method via inheritance from the Exporter class that -is defined in the Exporter module. +is defined in the Exporter module. See L. + +If you don't want your namespace altered, explicitly supply an empty list: + + use Module (); + +That is exactly equivalent to + + BEGIN { require Module; } + +If the VERSION argument is present between Module and LIST, then the +C will fail if the C<$VERSION> variable in package Module is +less than VERSION. Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are: @@ -2972,7 +3254,7 @@ ordinary modules, which import symbols into the current package (which are effective through the end of the file). There's a corresponding "no" command that unimports meanings imported -by use. +by use, i.e. it calls C instead of C. no integer; no strict 'refs'; @@ -2997,13 +3279,18 @@ Returns a normal array consisting of all the values of the named associative array. (In a scalar context, returns the number of values.) The values are returned in an apparently random order, but it is the same order as either the keys() or each() function would produce -on the same array. See also keys() and each(). +on the same array. See also keys(), each(), and sort(). =item vec EXPR,OFFSET,BITS -Treats a string as a vector of unsigned integers, and returns the value -of the bitfield specified. May also be assigned to. BITS must be a -power of two from 1 to 32. +Treats the string in EXPR as a vector of unsigned integers, and +returns the value of the bitfield specified by OFFSET. BITS specifies +the number of bits that are reserved for each entry in the bit +vector. This must be a power of two from 1 to 32. vec() may also be +assigned to, in which case parens are needed to give the expression +the correct precedence as in + + vec($image, $max_x * $x + $y, 8) = 3; Vectors created with vec() can also be manipulated with the logical operators |, & and ^, which will assume a bit vector operation is @@ -3084,6 +3371,6 @@ Note that write is I the opposite of read. Unfortunately. =item y/// -The translation operator. See L. +The translation operator. See L. =back