X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=de9bd22348ddad071019a4934e973d41540f3b0f;hb=a9bc755754f0db5e848e65dfd2e63a96af50ffd4;hp=bdf24f6c896fcf026deeab37afa7a7f99ed01e46;hpb=a0d0e21ea6ea90a22318550944fe6cb09ae10cda;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index bdf24f6..de9bd22 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -7,7 +7,7 @@ perlvar - Perl predefined variables
=head2 Predefined Names
The following names have special meaning to Perl. Most of the
-punctuational names have reasonable mnemonics, or analogues in one of
+punctuation names have reasonable mnemonics, or analogues in one of
the shells. Nevertheless, if you wish to use the long variable names,
you just need to say
@@ -38,9 +38,9 @@ new value for the FileHandle attribute in question. If not supplied,
most of the methods do nothing to the current value, except for
autoflush(), which will assume a 1 for you, just to be different.
-A few of these variables are considered "read-only". This means that if you
-try to assign to this variable, either directly or indirectly through
-a reference. If you attempt to do so, you'll raise a run-time exception.
+A few of these variables are considered "read-only". This means that if
+you try to assign to this variable, either directly or indirectly through
+a reference, you'll raise a run-time exception.
=over 8
@@ -51,7 +51,7 @@ a reference. If you attempt to do so, you'll raise a run-time exception.
The default input and pattern-searching space. The following pairs are
equivalent:
- while (<>) {...} # only equivalent in while!
+ while (<>) {...} # equivalent in only while!
while ($_ = <>) {...}
/^Subject:/
@@ -63,11 +63,52 @@ equivalent:
chop
chop($_)
+Here are the places where Perl will assume $_ even if you
+don't use it:
+
+=over 3
+
+=item *
+
+Various unary functions, including functions like ord() and int(), as well
+as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to
+STDIN.
+
+=item *
+
+Various list functions like print() and unlink().
+
+=item *
+
+The pattern matching operations C, C, and C
when used
+without an C<=~> operator.
+
+=item *
+
+The default iterator variable in a C loop if no other
+variable is supplied.
+
+=item *
+
+The implicit iterator variable in the grep() and map() functions.
+
+=item *
+
+The default place to put an input record when a CFHE>
+operation's result is tested by itself as the sole criterion of a C
+test. Note that outside of a C test, this will not happen.
+
+=back
+
(Mnemonic: underline is understood in certain operations.)
-=item $>
+=back
-Contains the subpattern from the corresponding set of parentheses in
+=over 8
+
+=item $EIE
+
+Contains the sub-pattern from the corresponding set of parentheses in
the last pattern matched, not counting patterns matched in nested
blocks that have been exited already. (Mnemonic: like \digit.)
These variables are all read-only.
@@ -86,7 +127,7 @@ BLOCK). (Mnemonic: like & in some editors.) This variable is read-only.
The string preceding whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or eval
-enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted
+enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted
string.) This variable is read-only.
=item $POSTMATCH
@@ -95,7 +136,7 @@ string.) This variable is read-only.
The string following whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or eval()
-enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted
+enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted
string.) Example:
$_ = 'abcdefghi';
@@ -121,15 +162,15 @@ This variable is read-only.
=item $*
-Set to 1 to do multiline matching within a string, 0 to tell Perl
+Set to 1 to do multi-line matching within a string, 0 to tell Perl
that it can assume that strings contain a single line, for the purpose
of optimizing pattern matches. Pattern matches on strings containing
multiple newlines can produce confusing results when "C<$*>" is 0. Default
is 0. (Mnemonic: * matches multiple things.) Note that this variable
-only influences the interpretation of "C<^>" and "C<$>". A literal newline can
+influences the interpretation of only "C<^>" and "C<$>". A literal newline can
be searched for even when C<$* == 0>.
-Use of "C<$*>" is deprecated in Perl 5.
+Use of "C<$*>" is deprecated in modern perls.
=item input_line_number HANDLE EXPR
@@ -139,12 +180,14 @@ Use of "C<$*>" is deprecated in Perl 5.
=item $.
-The current input line number of the last filehandle that was read.
-This variable should be considered read-only.
-Remember that only an explicit close on the filehandle
-resets the line number. Since "CE>" never does an explicit close, line
-numbers increase across ARGV files (but see examples under eof()).
-(Mnemonic: many programs use "." to mean the current line number.)
+The current input line number for the last file handle from
+which you read (or performed a C or C on). An
+explicit close on a filehandle resets the line number. Because
+"CE>" never does an explicit close, line numbers increase
+across ARGV files (but see examples under eof()). Localizing C<$.> has
+the effect of also localizing Perl's notion of "the last read
+filehandle". (Mnemonic: many programs use "." to mean the current line
+number.)
=item input_record_separator HANDLE EXPR
@@ -155,14 +198,15 @@ numbers increase across ARGV files (but see examples under eof()).
=item $/
The input record separator, newline by default. Works like B's RS
-variable, including treating blank lines as delimiters if set to the
-null string. You may set it to a multicharacter string to match a
+variable, including treating empty lines as delimiters if set to the
+null string. (Note: An empty line cannot contain any spaces or
+tabs.) You may set it to a multicharacter string to match a
multi-character delimiter. Note that setting it to C<"\n\n"> means
something slightly different than setting it to C<"">, if the file
-contains consecutive blank lines. Setting it to C<""> will treat two or
-more consecutive blank lines as a single blank line. Setting it to
-C<"\n\n"> will blindly assume that the next input character belongs to the
-next paragraph, even if it's a newline. (Mnemonic: / is used to
+contains consecutive empty lines. Setting it to C<""> will treat two
+or more consecutive empty lines as a single empty line. Setting it to
+C<"\n\n"> will blindly assume that the next input character belongs to
+the next paragraph, even if it's a newline. (Mnemonic: / is used to
delimit line boundaries when quoting poetry.)
undef $/;
@@ -176,12 +220,15 @@ delimit line boundaries when quoting poetry.)
=item $|
If set to nonzero, forces a flush after every write or print on the
-currently selected output channel. Default is 0. Note that STDOUT
-will typically be line buffered if output is to the terminal and block
-buffered otherwise. Setting this variable is useful primarily when you
-are outputting to a pipe, such as when you are running a Perl script
-under rsh and want to see the output as it's happening. (Mnemonic:
-when you want your pipes to be piping hot.)
+currently selected output channel. Default is 0 (regardless of whether
+the channel is actually buffered by the system or not; C<$|> tells you
+only whether you've asked Perl explicitly to flush after each write).
+Note that STDOUT will typically be line buffered if output is to the
+terminal and block buffered otherwise. Setting this variable is useful
+primarily when you are outputting to a pipe, such as when you are running
+a Perl script under rsh and want to see the output as it's happening. This
+has no effect on input buffering.
+(Mnemonic: when you want your pipes to be piping hot.)
=item output_field_separator HANDLE EXPR
@@ -192,8 +239,8 @@ when you want your pipes to be piping hot.)
=item $,
The output field separator for the print operator. Ordinarily the
-print operator simply prints out the comma separated fields you
-specify. In order to get behavior more like B, set this variable
+print operator simply prints out the comma-separated fields you
+specify. To get behavior more like B, set this variable
as you would set B's OFS variable to specify what is printed
between fields. (Mnemonic: what is printed when there is a , in your
print statement.)
@@ -207,12 +254,12 @@ print statement.)
=item $\
The output record separator for the print operator. Ordinarily the
-print operator simply prints out the comma separated fields you
-specify, with no trailing newline or record separator assumed. In
-order to get behavior more like B, set this variable as you would
+print operator simply prints out the comma-separated fields you
+specify, with no trailing newline or record separator assumed.
+To get behavior more like B, set this variable as you would
set B's ORS variable to specify what is printed at the end of the
print. (Mnemonic: you set "C<$\>" instead of adding \n at the end of the
-print. Also, it's just like /, but it's what you get "back" from
+print. Also, it's just like C<$/>, but it's what you get "back" from
Perl.)
=item $LIST_SEPARATOR
@@ -252,7 +299,7 @@ keys contain binary data there might not be any safe value for "C<$;>".
semi-semicolon. Yeah, I know, it's pretty lame, but "C<$,>" is already
taken for something more important.)
-Consider using "real" multi-dimensional arrays in Perl 5.
+Consider using "real" multi-dimensional arrays.
=item $OFMT
@@ -261,11 +308,12 @@ Consider using "real" multi-dimensional arrays in Perl 5.
The output format for printed numbers. This variable is a half-hearted
attempt to emulate B's OFMT variable. There are times, however,
when B and Perl have differing notions of what is in fact
-numeric. Also, the initial value is %.20g rather than %.6g, so you
-need to set "C<$#>" explicitly to get B's value. (Mnemonic: # is the
-number sign.)
+numeric. The initial value is %.Ig, where I is the value
+of the macro DBL_DIG from your system's F. This is different from
+B's default OFMT setting of %.6g, so you need to set "C<$#>"
+explicitly to get B's value. (Mnemonic: # is the number sign.)
-Use of "C<$#>" is deprecated in Perl 5.
+Use of "C<$#>" is deprecated.
=item format_page_number HANDLE EXPR
@@ -331,7 +379,7 @@ poetry is a part of a line.)
=item $^L
-What formats output to perform a formfeed. Default is \f.
+What formats output to perform a form feed. Default is \f.
=item $ACCUMULATOR
@@ -348,13 +396,17 @@ L.
=item $?
-The status returned by the last pipe close, backtick (C<``>) command,
+The status returned by the last pipe close, back-tick (C<``>) command,
or system() operator. Note that this is the status word returned by
the wait() system call, so the exit value of the subprocess is actually
(C<$? EE 8>). Thus on many systems, C<$? & 255> gives which signal,
if any, the process died from, and whether there was a core dump.
(Mnemonic: similar to B and B.)
+Inside an C subroutine C<$?> contains the value that is going to be
+given to C. You can modify C<$?> in an C subroutine to
+change the exit status of the script.
+
=item $OS_ERROR
=item $ERRNO
@@ -366,10 +418,26 @@ all the usual caveats. (This means that you shouldn't depend on the
value of "C<$!>" to be anything in particular unless you've gotten a
specific error return indicating a system error.) If used in a string
context, yields the corresponding system error string. You can assign
-to "C<$!>" in order to set I if, for instance, you want "C<$!>" to return the
+to "C<$!>" to set I if, for instance, you want "C<$!>" to return the
string for error I, or you want to set the exit value for the die()
operator. (Mnemonic: What just went bang?)
+=item $EXTENDED_OS_ERROR
+
+=item $^E
+
+More specific information about the last system error than that
+provided by C<$!>, if available. (If not, it's just C<$!> again, except under
+OS/2.)
+At the moment, this differs from C<$!> under only VMS and OS/2, where it
+provides the VMS status value from the last system error, and OS/2 error
+code of the last call to OS/2 API which was not directed via CRT. The
+caveats mentioned in the description of C<$!> apply here, too.
+(Mnemonic: Extra error explanation.)
+
+Note that under OS/2 C<$!> and C<$^E> do not track each other, so if an
+OS/2-specific call is performed, you may need to check both.
+
=item $EVAL_ERROR
=item $@
@@ -379,6 +447,10 @@ last eval() parsed and executed correctly (although the operations you
invoked may have failed in the normal fashion). (Mnemonic: Where was
the syntax error "at"?)
+Note that warning messages are not collected in this variable. You can,
+however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
+below.
+
=item $PROCESS_ID
=item $PID
@@ -409,7 +481,7 @@ The effective uid of this process. Example:
($<,$>) = ($>,$<); # swap real and effective uid
(Mnemonic: it's the uid you went I, if you're running setuid.) Note:
-"C<$E>" and "C<$E>" can only be swapped on machines supporting setreuid().
+"C<$E>" and "C<$E>" can be swapped on only machines supporting setreuid().
=item $REAL_GROUP_ID
@@ -438,9 +510,11 @@ which may be the same as the first number. (Mnemonic: parentheses are
used to I things. The effective gid is the group that's I for
you, if you're running setgid.)
-Note: "C<$E>", "C<$E>", "C<$(>" and "C<$)>" can only be set on machines
-that support the corresponding I routine. "C<$(>" and "C<$)>"
-can only be swapped on machines supporting setregid().
+Note: "C<$E>", "C<$E>", "C<$(>" and "C<$)>" can be set only on
+machines that support the corresponding I routine. "C<$(>"
+and "C<$)>" can be swapped on only machines supporting setregid(). Because
+Perl doesn't currently use initgroups(), you can't set your group vector to
+multiple groups.
=item $PROGRAM_NAME
@@ -468,7 +542,9 @@ discouraged.
=item $]
-The string printed out when you say C. It can be used to
+The string printed out when you say C.
+(This is currently I).
+It can be used to
determine at the beginning of a script whether the perl interpreter
executing the script is in the right range of versions. If used in a
numeric context, returns the version + patchlevel / 1000. Example:
@@ -504,6 +580,11 @@ closed before the open() is attempted.) Note that the close-on-exec
status of a file descriptor will be decided according to the value of
C<$^F> at the time of the open, not the time of the exec.
+=item $^H
+
+The current set of syntax checks enabled by C