=head2 Predefined Names
The following names have special meaning to Perl. Most
-punctuation names have reasonable mnemonics, or analogues in one of
-the shells. Nevertheless, if you wish to use long variable names,
-you just need to say
+punctuation names have reasonable mnemonics, or analogs in the
+shells. Nevertheless, if you wish to use long variable names,
+you need only say
use English;
HANDLE->method(EXPR)
-Each of the methods returns the old value of the IO::Handle attribute.
+Each method returns the old value of the IO::Handle attribute.
The methods each take an optional EXPR, which if supplied specifies the
new value for the IO::Handle attribute in question. If not supplied,
-most of the methods do nothing to the current value, except for
+most methods do nothing to the current value--except for
autoflush(), which will assume a 1 for you, just to be different.
-It costs quite a bit to load in the IO::Handle class, so you should
+Because loading in the IO::Handle class is an expensive operation, you should
learn how to use the regular built-in variables.
A few of these variables are considered "read-only". This means that if
a reference, you'll raise a run-time exception.
The following list is ordered by scalar variables first, then the
-arrays, then the hashes (except $^M was added in the wrong place).
-This is somewhat obscured by the fact that %ENV and %SIG are listed as
-$ENV{expr} and $SIG{expr}.
+arrays, then the hashes.
=over 8
=item *
-The default place to put an input record when a C<E<lt>FHE<gt>>
+The default place to put an input record when a C<< <FH> >>
operation's result is tested by itself as the sole criterion of a C<while>
-test. Outside of a C<while> test, this will not happen.
+test. Outside a C<while> test, this will not happen.
=back
=over 8
-=item $E<lt>I<digits>E<gt>
+=item $<I<digits>>
Contains the subpattern from the corresponding set of capturing
parentheses from the last pattern match, not counting patterns
(Mnemonic: be positive and forward looking.)
This variable is read-only and dynamically scoped to the current BLOCK.
+=item @LAST_MATCH_END
+
=item @+
-$+[0] is the offset of the end of the last successful match.
-C<$+[>I<n>C<]> is the offset of the end of the substring matched by
-I<n>-th subpattern, or undef if the subpattern did not match.
-
-Thus after a match against $_, $& coincides with C<substr $_, $-[0],
-$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
-$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#+> to find the number
-of subgroups in the last successful match. Note the difference with
-C<$#->, which is the last I<matched> subgroup. Compare with C<@->.
+This array holds the offsets of the ends of the last successful
+submatches in the currently active dynamic scope. C<$+[0]> is
+the offset into the string of the end of the entire match. This
+is the same value as what the C<pos> function returns when called
+on the variable that was matched against. The I<n>th element
+of this array holds the offset of the I<n>th submatch, so
+C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset
+past where $2 ends, and so on. You can use C<$#+> to determine
+how many subgroups were in the last successful match. See the
+examples given for the C<@-> variable.
=item $MULTILINE_MATCHING
=item $*
-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.) This variable
-influences the interpretation of only C<^> and C<$>. A literal newline can
-be searched for even when C<$* == 0>.
+Set to a non-zero integer value to do multi-line matching within a
+string, 0 (or undefined) 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 or undefined. Default is undefined.
+(Mnemonic: * matches multiple things.) This variable 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 modern Perl, supplanted by
the C</s> and C</m> modifiers on pattern matching.
+Assigning a non-numerical value to C<$*> triggers a warning (and makes
+C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*>
+makes that an implicit C<int> is applied on the value.
+
=item input_line_number HANDLE EXPR
=item $INPUT_LINE_NUMBER
=item $.
The current input record number for the last file handle from which
-you just read() (or performed a C<seek> or C<tell> on). The value
+you just read() (or called a C<seek> or C<tell> on). The value
may be different from the actual physical line number in the file,
depending on what notion of "line" is in effect--see C<$/> on how
to change that. An explicit close on a filehandle resets the line
-number. Because C<E<lt>E<gt>> never does an explicit close, line
+number. Because C<< <> >> never does an explicit close, line
numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
Consider this variable read-only: setting it does not reposition
-the seek pointer; you'll have to do that on your own. (Mnemonic:
-many programs use "." to mean the current line number.)
+the seek pointer; you'll have to do that on your own. 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
=item $/
-The input record separator, newline by default. This is used to
-influence Perl's idea of what a "line" is. Works like B<awk>'s RS
+The input record separator, newline by default. This
+influences Perl's idea of what a "line" is. Works like B<awk>'s RS
variable, including treating empty lines as a terminator if set to
-the null string. (Note: An empty line cannot contain any spaces
-or tabs.) You may set it to a multi-character string to match a
+the null string. (An empty line cannot contain any spaces
+or tabs.) You may set it to a multi-character string to match a
multi-character terminator, or to C<undef> to read through the end
of file. Setting it to C<"\n\n"> means something slightly
different than setting to C<"">, if the file contains consecutive
empty lines. Setting to C<""> will treat two or more consecutive
empty lines as a single empty line. Setting 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
+paragraph, even if it's a newline. (Mnemonic: / delimits
line boundaries when quoting poetry.)
undef $/; # enable "slurp" mode
On VMS, record reads are done with the equivalent of C<sysread>,
so it's best not to mix record and non-record reads on the same
file. (This is unlikely to be a problem, because any file you'd
-want to read in record mode is probably usable in line mode.)
-Non-VMS systems perform normal I/O, so it's safe to mix record and
+want to read in record mode is probably unusable in line mode.)
+Non-VMS systems do normal I/O, so it's safe to mix record and
non-record reads of a file.
-Also see C<$.>.
+See also L<perlport/"Newlines">. Also see C<$.>.
=item autoflush HANDLE EXPR
If set to nonzero, forces a flush right away and after every write
or print on the currently selected output channel. Default is 0
-(regardless of whether the channel is actually buffered by the
+(regardless of whether the channel is really buffered by the
system or not; C<$|> tells you only whether you've asked Perl
explicitly to flush after each write). STDOUT will
typically be line buffered if output is to the terminal and block
The output format for printed numbers. This variable is a half-hearted
attempt to emulate B<awk>'s OFMT variable. There are times, however,
-when B<awk> and Perl have differing notions of what is in fact
+when B<awk> and Perl have differing notions of what counts as
numeric. The initial value is "%.I<n>g", where I<n> is the value
of the macro DBL_DIG from your system's F<float.h>. This is different from
B<awk>'s default OFMT setting of "%.6g", so you need to set C<$#>
Used with formats.
(Mnemonic: lines_on_page - lines_printed.)
+=item @LAST_MATCH_START
+
=item @-
$-[0] is the offset of the start of the last successful match.
$+[0] - $-[0]>. Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
C<substr $_, $-[$#-], $+[$#-]>. One can use C<$#-> to find the last
-matched subgroup in the last successful match. Note the difference with
-C<$#+>, which is the number of subgroups in the regular expression. Compare
+matched subgroup in the last successful match. Contrast with
+C<$#+>, the number of subgroups in the regular expression. Compare
with C<@+>.
+This array holds the offsets of the beginnings of the last
+successful submatches in the currently active dynamic scope.
+C<$-[0]> is the offset into the string of the beginning of the
+entire match. The I<n>th element of this array holds the offset
+of the I<n>th submatch, so C<$+[1]> is the offset where $1
+begins, C<$+[2]> the offset where $2 begins, and so on.
+You can use C<$#-> to determine how many subgroups were in the
+last successful match. Compare with the C<@+> variable.
+
+After a match against some variable $var:
+
+=over 5
+
+=item C<$`> is the same as C<substr($var, 0, $-[0])>
+
+=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>
+
+=item C<$'> is the same as C<substr($var, $+[0])>
+
+=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])>
+
+=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])>
+
+=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])>
+
+=back
+
=item format_name HANDLE EXPR
=item $FORMAT_NAME
=item $~
The name of the current report format for the currently selected output
-channel. Default is name of the filehandle. (Mnemonic: brother to
+channel. Default is the name of the filehandle. (Mnemonic: brother to
C<$^>.)
=item format_top_name HANDLE EXPR
=item $^
The name of the current top-of-page format for the currently selected
-output channel. Default is name of the filehandle with _TOP
+output channel. Default is the name of the filehandle with _TOP
appended. (Mnemonic: points to top of page.)
=item format_line_break_characters HANDLE EXPR
=item $^L
-What formats output to perform a form feed. Default is \f.
+What formats output as a form feed. Default is \f.
=item $ACCUMULATOR
The current value of the write() accumulator for format() lines. A format
contains formline() calls that put their result into C<$^A>. After
calling its format, write() prints out the contents of C<$^A> and empties.
-So you never actually see the contents of C<$^A> unless you call
+So you never really see the contents of C<$^A> unless you call
formline() yourself and then look at it. See L<perlform> and
L<perlfunc/formline()>.
successful call to wait() or waitpid(), or from the system()
operator. This is just the 16-bit status word returned by the
wait() system call (or else is made up to look like it). Thus, the
-exit value of the subprocess is actually (C<$? E<gt>E<gt> 8>), and
+exit value of the subprocess is really (C<<< $? >> 8 >>>), and
C<$? & 127> gives which signal, if any, the process died from, and
C<$? & 128> reports whether there was a core dump. (Mnemonic:
similar to B<sh> and B<ksh>.)
Additionally, if the C<h_errno> variable is supported in C, its value
-is returned via $? if any of the C<gethost*()> functions fail.
+is returned via $? if any C<gethost*()> function fails.
If you have installed a signal handler for C<SIGCHLD>, the
value of C<$?> will usually be wrong outside that handler.
=item $<
The real uid of this process. (Mnemonic: it's the uid you came I<from>,
-if you're running setuid.)
+if you're running setuid.) You can change both the real uid and
+the effective uid at the same time by using POSIX::setuid().
=item $EFFECTIVE_USER_ID
$< = $>; # set real to effective uid
($<,$>) = ($>,$<); # swap real and effective uid
+You can change both the effective uid and the real uid at the same
+time by using POSIX::setuid().
+
(Mnemonic: it's the uid you went I<to>, if you're running setuid.)
-Note: C<$E<lt>> and C<$E<gt>> can be swapped only on machines
+C<< $< >> and C<< $> >> can be swapped only on machines
supporting setreuid().
=item $REAL_GROUP_ID
set the real gid. So the value given by C<$(> should I<not> be assigned
back to C<$(> without being forced numeric, such as by adding zero.
+You can change both the real gid and the effective gid at the same
+time by using POSIX::setgid().
+
(Mnemonic: parentheses are used to I<group> things. The real gid is the
group you I<left>, if you're running setgid.)
which may be the same as the first number.
Similarly, a value assigned to C<$)> must also be a space-separated
-list of numbers. The first number is used to set the effective gid, and
+list of numbers. The first number sets the effective gid, and
the rest (if any) are passed to setgroups(). To get the effect of an
empty list for setgroups(), just repeat the new effective gid; that is,
to force an effective gid of 5 and an effectively empty setgroups()
list, say C< $) = "5 5" >.
+You can change both the effective gid and the real gid at the same
+time by using POSIX::setgid() (use only a single numeric argument).
+
(Mnemonic: parentheses are used to I<group> things. The effective gid
is the group that's I<right> for you, if you're running setgid.)
-Note: C<$E<lt>>, C<$E<gt>>, C<$(> and C<$)> can be set only on
+C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
and C<$)> can be swapped only on machines supporting setregid().
program state than it is for hiding the program you're running.
(Mnemonic: same as B<sh> and B<ksh>.)
+Note for BSD users: setting C<$0> does not completely remove "perl"
+from the ps(1) output. For example, setting C<$0> to C<"foobar"> will
+result in C<"perl: foobar (perl)">. This is an operating system
+feature.
+
=item $[
The index of the first element in an array, and of the first character
directive, and cannot influence the behavior of any other file.
Its use is highly discouraged.
-=item $PERL_VERSION
-
=item $]
The version + patchlevel / 1000 of the Perl interpreter. This variable
See also the documentation of C<use VERSION> and C<require VERSION>
for a convenient way to fail if the running Perl interpreter is too old.
+The use of this variable is deprecated. The floating point representation
+can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a
+more modern representation of the Perl version that allows accurate string
+comparisons.
+
=item $COMPILING
=item $^C
preserved even if the open() fails. (Ordinary file descriptors are
closed before the open() is attempted.) The close-on-exec
status of a file descriptor will be decided according to the value of
-C<$^F> when the open() or pipe() was called, not the time of the exec().
+C<$^F> when the corresponding file, pipe, or socket was opened, not the
+time of the exec().
=item $^H
-The current set of syntax checks enabled by C<use strict> and other block
-scoped compiler hints. See the documentation of C<strict> for more details.
+WARNING: This variable is strictly for internal use only. Its availability,
+behavior, and contents are subject to change without notice.
+
+This variable contains compile-time hints for the Perl interpreter. At the
+end of compilation of a BLOCK the value of this variable is restored to the
+value when the interpreter started to compile the BLOCK.
+
+When perl begins to parse any block construct that provides a lexical scope
+(e.g., eval body, required file, subroutine body, loop body, or conditional
+block), the existing value of $^H is saved, but its value is left unchanged.
+When the compilation of the block is completed, it regains the saved value.
+Between the points where its value is saved and restored, code that
+executes within BEGIN blocks is free to change the value of $^H.
+
+This behavior provides the semantic of lexical scoping, and is used in,
+for instance, the C<use strict> pragma.
+
+The contents should be an integer; different bits of it are used for
+different pragmatic flags. Here's an example:
+
+ sub add_100 { $^H |= 0x100 }
+
+ sub foo {
+ BEGIN { add_100() }
+ bar->baz($boon);
+ }
+
+Consider what happens during execution of the BEGIN block. At this point
+the BEGIN block has already been compiled, but the body of foo() is still
+being compiled. The new value of $^H will therefore be visible only while
+the body of foo() is being compiled.
+
+Substitution of the above BEGIN block with:
+
+ BEGIN { require strict; strict->import('vars') }
+
+demonstrates how C<use strict 'vars'> is implemented. Here's a conditional
+version of the same lexical pragma:
+
+ BEGIN { require strict; strict->import('vars') if $condition }
+
+=item %^H
+
+WARNING: This variable is strictly for internal use only. Its availability,
+behavior, and contents are subject to change without notice.
+
+The %^H hash provides the same scoping semantic as $^H. This makes it
+useful for implementation of lexically scoped pragmas.
=item $INPLACE_EDIT
$^M = 'a' x (1 << 16);
-would allocate a 64K buffer for use when in emergency. See the
+would allocate a 64K buffer for use in an emergency. See the
F<INSTALL> file in the Perl distribution for information on how to
enable this option. To discourage casual use of this advanced
-feature, there is no L<English> long name for this variable.
+feature, there is no L<English|English> long name for this variable.
=item $OSNAME
Start with single-step on.
+=item 0x40
+
+Use subroutine address instead of name when reporting.
+
+=item 0x80
+
+Report C<goto &subroutine> as well.
+
+=item 0x100
+
+Provide informative "file" names for evals based on the place they were compiled.
+
+=item 0x200
+
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
+
=back
Some bits may be relevant at compile-time only, some at
run-time only. This is a new mechanism and the details may change.
+=item $LAST_REGEXP_CODE_RESULT
+
=item $^R
The result of evaluation of the last successful C<(?{ code })>
regular expression assertion (see L<perlre>). May be written to.
+=item $EXCEPTIONS_BEING_CAUGHT
+
=item $^S
Current state of the interpreter. Undefined if parsing of the current
epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
and B<-C> filetests are based on this value.
+=item $PERL_VERSION
+
+=item $^V
+
+The revision, version, and subversion of the Perl interpreter, represented
+as a string composed of characters with those ordinals. Thus in Perl v5.6.0
+it equals C<chr(5) . chr(6) . chr(0)> and will return true for
+C<$^V eq v5.6.0>. Note that the characters in this string value can
+potentially be in Unicode range.
+
+This can be used to determine whether the Perl interpreter executing a
+script is in the right range of versions. (Mnemonic: use ^V for Version
+Control.) Example:
+
+ warn "No "our" declarations!\n" if $^V and $^V lt v5.6.0;
+
+See the documentation of C<use VERSION> and C<require VERSION>
+for a convenient way to fail if the running Perl interpreter is too old.
+
+See also C<$]> for an older representation of the Perl version.
+
=item $WARNING
=item $^W
The current value of the warning switch, initially true if B<-w>
was used, false otherwise, but directly modifiable. (Mnemonic:
-related to the B<-w> switch.) See also L<warning>.
+related to the B<-w> switch.) See also L<warnings>.
+
+=item ${^WARNING_BITS}
+
+The current set of warning checks enabled by the C<use warnings> pragma.
+See the documentation of C<warnings> for more details.
+
+=item ${^WIDE_SYSTEM_CALLS}
+
+Global flag that enables system calls made by Perl to use wide character
+APIs native to the system, if available. This is currently only implemented
+on the Windows platform.
+
+This can also be enabled from the command line using the C<-C> switch.
+
+The initial value is typically C<0> for compatibility with Perl versions
+earlier than 5.6, but may be automatically set to C<1> by Perl if the system
+provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>).
+
+The C<bytes> pragma always overrides the effect of this flag in the current
+lexical scope. See L<bytes>.
=item $EXECUTABLE_NAME
=item $ARGV
-contains the name of the current file when reading from E<lt>E<gt>.
+contains the name of the current file when reading from <>.
=item @ARGV
The array @ARGV contains the command-line arguments intended for
-the script. C<$#ARGV> is the generally number of arguments minus
+the script. C<$#ARGV> is generally the number of arguments minus
one, because C<$ARGV[0]> is the first argument, I<not> the program's
command name itself. See C<$0> for the command name.
The hash %INC contains entries for each filename included via the
C<do>, C<require>, or C<use> operators. The key is the filename
you specified (with module names converted to pathnames), and the
-value is the location of the file actually found. The C<require>
-operator uses this array to determine whether a particular file has
+value is the location of the file found. The C<require>
+operator uses this hash to determine whether a particular file has
already been included.
=item %ENV
=item $SIG{expr}
-The hash %SIG is used to set signal handlers for various
-signals. For example:
+The hash %SIG contains signal handlers for signals. For example:
sub handler { # 1st argument is signal name
my($sig) = @_;
not available.
See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
-L<warning> for additional information.
+L<warnings> for additional information.
=back
(which will interpolate C<$!> and C<$?>!). (See also L<Fatal>,
though.)
-When the eval() expression above is executed, open(), C<<PIPEE<gt>>,
+When the eval() expression above is executed, open(), C<< <PIPE> >>,
and C<close> are translated to calls in the C run-time library and
thence to the operating system kernel. C<$!> is set to the C library's
C<errno> if one of these calls fails.
Under a few operating systems, C<$^E> may contain a more verbose
error indicator, such as in this case, "CDROM tray not closed."
-Systems that do not support extended error mesages leave $C<$^E>
+Systems that do not support extended error messages leave C<$^E>
the same as C<$!>.
Finally, C<$?> may be set to non-0 value if the external program
control-C<W>. This is better than typing a literal control-C<W>
into your program.
-Finally, new in Perl 5.006, Perl variable names may be alphanumeric
+Finally, new in Perl 5.6, Perl variable names may be alphanumeric
strings that begin with control characters (or better yet, a caret).
These variables must be written in the form C<${^Foo}>; the braces
are not optional. C<${^Foo}> denotes the scalar variable whose
in the scope of C<use English>. For that reason, saying C<use
English> in libraries is strongly discouraged. See the
Devel::SawAmpersand module documentation from CPAN
-(http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme)
+(http://www.perl.com/CPAN/modules/by-module/Devel/)
for more information.
Having to even think about the C<$^S> variable in your exception
projects / p5sagit/p5-mst-13.2.git / blobdiff