''' Beginning of part 3
-''' $Header: perl.man.3,v 3.0 89/10/18 15:21:46 lwall Locked $
+''' $Header: perl.man.3,v 3.0.1.5 90/03/12 16:52:21 lwall Locked $
'''
''' $Log: perl.man.3,v $
+''' Revision 3.0.1.5 90/03/12 16:52:21 lwall
+''' patch13: documented that print $filehandle &foo is ambiguous
+''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST)
+'''
+''' Revision 3.0.1.4 90/02/28 18:00:09 lwall
+''' patch9: added pipe function
+''' patch9: documented how to handle arbitrary weird characters in filenames
+''' patch9: documented the unflushed buffers problem on piped opens
+''' patch9: documented how to force top of page
+'''
+''' Revision 3.0.1.3 89/12/21 20:10:12 lwall
+''' patch7: documented that s`pat`repl` does command substitution on replacement
+''' patch7: documented that $timeleft from select() is likely not implemented
+'''
+''' Revision 3.0.1.2 89/11/17 15:31:05 lwall
+''' patch5: fixed some manual typos and indent problems
+''' patch5: added warning about print making an array context
+'''
+''' Revision 3.0.1.1 89/11/11 04:45:06 lwall
+''' patch2: made some line breaks depend on troff vs. nroff
+'''
''' Revision 3.0 89/10/18 15:21:46 lwall
''' 3.0 baseline
'''
open article || die "Can't find article $article: $!\en";
while (<article>) {\|.\|.\|.
+.ie t \{\
open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved)
+'br\}
+.el \{\
+ open(LOG, \'>>/usr/spool/news/twitlog\'\|);
+ # (log is reserved)
+'br\}
+.ie t \{\
open(article, "caesar <$article |"\|); # decrypt article
+'br\}
+.el \{\
+ open(article, "caesar <$article |"\|);
+ # decrypt article
+'br\}
+.ie t \{\
open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process#
+'br\}
+.el \{\
+ open(extract, "|sort >/tmp/Tmp$$"\|);
+ # $$ is our process#
+'br\}
.ne 7
# process argument list of files along with any includes
print STDERR "Can't open $filename: $!\en";
return;
}
+.ie t \{\
while (<$input>) { # note the use of indirection
+'br\}
+.el \{\
+ while (<$input>) { # note use of indirection
+'br\}
if (/^#include "(.*)"/) {
do process($1, $input);
next;
with \*(L">&\*(R", 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.
Here is a script that saves, redirects, and restores
.I STDOUT
and
-.IR STDIN :
+.IR STDERR :
.nf
.ne 21
.fi
Explicitly closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in $?.
+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.
+.Sp
+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:
+.nf
+
+.ne 2
+ $file =~ s#^(\es)#./$1#;
+ open(FOO, "< $file\e0");
+
+.fi
.Ip "opendir(DIRHANDLE,EXPR)" 8 3
Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(),
rewinddir() and closedir().
$foo = pack("a14","abcdefg");
# "abcdefg\e0\e0\e0\e0\e0\e0\e0"
- $foo = pack("i9pl", gmtime());
+ $foo = pack("i9pl", gmtime);
# a real struct tm (on my system anyway)
.fi
The same template may generally also be used in the unpack function.
+.Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3
+Opens a pair of connected pipes like the corresponding system call.
+Note that if you set up a loop of piped processes, deadlock can occur
+unless you are very careful.
+In addition, note that perl's pipes use stdio buffering, so you may need
+to set $| to flush your WRITEHANDLE after each command, depending on
+the application.
+[Requires version 3.0 patchlevel 9.]
.Ip "pop(ARRAY)" 8
.Ip "pop ARRAY" 8 6
Pops and returns the last value of the array, shortening the array by 1.
Returns non-zero if successful.
FILEHANDLE may be a scalar variable name, in which case the variable contains
the name of 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
To set the default output channel to something other than
.I STDOUT
use the select operation.
+Note that, because print takes a LIST, anything in the LIST is evaluated
+in an array context, and any subroutine that you call will have one or more
+of its expressions evaluated in an array context.
+Also be careful not to follow the print keyword with a left parenthesis
+unless you want the corresponding right parenthesis to terminate the
+arguments to the print--interpose a + or put parens around all the arguments.
.Ip "printf(FILEHANDLE LIST)" 8 10
.Ip "printf(LIST)" 8
.Ip "printf FILEHANDLE LIST" 8
Returns the number of bytes actually read.
SCALAR will be grown or shrunk to the length actually read.
.Ip "readdir(DIRHANDLE)" 8 3
+.Ip "readdir DIRHANDLE" 8
Returns the next directory entry for a directory opened by opendir().
If used in an array context, returns all the rest of the entries in the
directory.
as a double-quoted string.
Any delimiter may replace the slashes; if single quotes are used, no
interpretation is done on the replacement string (the e modifier overrides
-this, however).
+this, however); if backquotes are used, the replacement string is a command
+to execute whose output will be used as the actual replacement text.
If no string is specified via the =~ or !~ operator,
the $_ string is searched and modified.
(The string specified with =~ must be a scalar variable, an array element,
or to block until something becomes ready:
+.ie t \{\
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
+'br\}
+.el \{\
+ $nfound = select($rout=$rin, $wout=$win,
+ $eout=$ein, undef);
+'br\}
.fi
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.
.Ip "setpgrp(PID,PGRP)" 8 4
Sets the current process group for the specified PID, 0 for the current
process.
# prints AbelAxedCainPunishedcatchaseddoggonetoxyz
.fi
+.Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8
+.Ip "splice(ARRAY,OFFSET,LENGTH)" 8
+.Ip "splice(ARRAY,OFFSET)" 8
+Removes the elements designated by OFFSET and LENGTH from an array, and
+replaces them with the elements of LIST, if any.
+Returns the elements removed from the array.
+The array grows or shrinks as necessary.
+If LENGTH is omitted, removes everything from OFFSET onward.
+The following equivalencies hold (assuming $[ == 0):
+.nf
+
+ push(@a,$x,$y)\h'|3.5i'splice(@a,$#x+1,0,$x,$y)
+ pop(@a)\h'|3.5i'splice(@a,-1)
+ shift(@a)\h'|3.5i'splice(@a,0,1)
+ unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y)
+ $a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y);
+
+Example, assuming array lengths are passed before arrays:
+
+ sub aeq { # compare two array values
+ local(@a) = splice(@_,0,shift);
+ local(@b) = splice(@_,0,shift);
+ return 0 unless @a == @b; # same len?
+ while (@a) {
+ return 0 if pop(@a) ne pop(@b);
+ }
+ return 1;
+ }
+ if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
+
+.fi
.Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
.Ip "split(/PATTERN/,EXPR)" 8 8
.Ip "split(/PATTERN/)" 8
.Ip "split" 8
Splits a string into an array of strings, and returns it.
(If not in an array context, returns the number of fields found and splits
-into the @_ array.)
+into the @_ array.
+(In an array context, you can force the split into @_
+by using ?? as the pattern delimiters, but it still returns the array value.))
If EXPR is omitted, splits the $_ string.
If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
Anything matching PATTERN is taken to be a delimiter separating the fields.
.fi
produces the output \*(L'h:i:t:h:e:r:e\*(R'.
-.P
-The NUM parameter can be used to partially split a line
+.Sp
+The LIMIT parameter can be used to partially split a line
.nf
($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
.fi
-(When assigning to a list, if NUM is omitted, perl supplies a NUM one
+(When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one
larger than the number of variables in the list, to avoid unnecessary work.
-For the list above NUM would have been 4 by default.
+For the list above LIMIT would have been 4 by default.
In time critical applications it behooves you not to split into
more fields than you really need.)
.Sp
.I rand
operator.
If EXPR is omitted, does srand(time).
-.Ip "stat(FILEHANDLE)" 8 6
+.Ip "stat(FILEHANDLE)" 8 8
.Ip "stat FILEHANDLE" 8
.Ip "stat(EXPR)" 8
+.Ip "stat SCALARVARIABLE" 8
Returns a 13-element array giving the statistics for a file, either the file
opened via FILEHANDLE, or named by EXPR.
Typically used as follows:
You can use the substr() function as an lvalue, in which case EXPR must
be an lvalue.
If you assign something shorter than LEN, the string will shrink, and
-if you assign something longer than LEN, the string will grow to accomodate it.
+if you assign something longer than LEN, the string will grow to accommodate it.
To keep the string the same length you may need to pad or chop your value using
sprintf().
.Ip "syscall(LIST)" 8 6
.fi
.Ip "umask(EXPR)" 8 4
.Ip "umask EXPR" 8
+.Ip "umask" 8
Sets the umask for the process and returns the old one.
If EXPR is omitted, merely returns current umask.
.Ip "undef(EXPR)" 8 6
your program, to protect older programs.
.Ip "wait" 8 6
Waits for a child process to terminate and returns the pid of the deceased
-process.
+process, or -1 if there are no child processes.
The status is returned in $?.
+If you expected a child and didn't find it, you probably had a call to
+system, a close on a pipe, or backticks between the fork and the wait.
+These constructs also do a wait and may have harvested your child process.
.Ip "wantarray" 8 4
Returns true if the context of the currently executing subroutine
is looking for an array value.
Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
.Ip "write(FILEHANDLE)" 8 6
.Ip "write(EXPR)" 8
-.Ip "write(\|)" 8
+.Ip "write" 8
Writes a formatted record (possibly multi-line) to the specified file,
using the format associated with that file.
By default the format for a file is the one having the same name is the
.Sp
Top of form processing is handled automatically:
if there is insufficient room on the current page for the formatted
-record, the page is advanced, a special top-of-page format is used
+record, the page is advanced by writing a form feed,
+a special top-of-page format is used
to format the new page header, and then the record is written.
By default the top-of-page format is \*(L"top\*(R", but it
may be set to the
format of your choice by assigning the name to the $^ variable.
+The number of lines remaining on the current page is in variable $-, which
+can be set to 0 to force a new page.
.Sp
If FILEHANDLE is unspecified, output goes to the current default output channel,
which starts out as
projects / p5sagit/p5-mst-13.2.git / blobdiff