you try to assign to this variable, either directly or indirectly through
a reference, you'll raise a run-time exception.
+You should be very careful when modifying the default values of most
+special variables described in this document. In most cases you want
+to localize these variables before changing them, since if you don't,
+the change may affect other modules which rely on the default values
+of the special variables that you have changed. This is one of the
+correct ways to read the whole file at once:
+
+ open my $fh, "foo" or die $!;
+ local $/; # enable localized slurp mode
+ my $content = <$fh>;
+ close $fh;
+
+But the following code is quite bad:
+
+ open my $fh, "foo" or die $!;
+ undef $/; # enable slurp mode
+ my $content = <$fh>;
+ close $fh;
+
+since some other module, may want to read data from some file in the
+default "line mode", so if the code we have just presented has been
+executed, the global value of C<$/> is now changed for any other code
+running inside the same Perl interpreter.
+
+Usually when a variable is localized you want to make sure that this
+change affects the shortest scope possible. So unless you are already
+inside some short C<{}> block, you should create one yourself. For
+example:
+
+ my $content = '';
+ open my $fh, "foo" or die $!;
+ {
+ local $/;
+ $content = <$fh>;
+ }
+ close $fh;
+
+Here is an example of how your own code can go broken:
+
+ for (1..5){
+ nasty_break();
+ print "$_ ";
+ }
+ sub nasty_break {
+ $_ = 5;
+ # do something with $_
+ }
+
+You probably expect this code to print:
+
+ 1 2 3 4 5
+
+but instead you get:
+
+ 5 5 5 5 5
+
+Why? Because nasty_break() modifies C<$_> without localizing it
+first. The fix is to add local():
+
+ local $_ = 5;
+
+It's easy to notice the problem in such a short example, but in more
+complicated code you are looking for trouble if you don't localize
+changes to the special variables.
+
The following list is ordered by scalar variables first, then the
arrays, then the hashes.
=over 8
+=item $a
+
+=item $b
+
+Special package variables when using sort(), see L<perlfunc/sort>.
+Because of this specialness $a and $b don't need to be declared
+(using local(), use vars, or our()) even when using the strict
+vars pragma. Don't lexicalize them with C<my $a> or C<my $b>
+if you want to be able to use them in the sort() comparison block
+or function.
+
+=back
+
+=over 8
+
=item $<I<digits>>
Contains the subpattern from the corresponding set of capturing
enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted
string.) Example:
- $_ = 'abcdefghi';
+ local $_ = 'abcdefghi';
/def/;
print "$`:$&:$'\n"; # prints abc:def:ghi
=item $+
-The last bracket matched by the last search pattern. This is useful if
-you don't know which one of a set of alternative patterns matched. For
-example:
+The text matched by the last bracket of the last successful search pattern.
+This is useful if you don't know which one of a set of alternative patterns
+matched. For example:
/Version: (.*)|Revision: (.*)/ && ($rev = $+);
(Mnemonic: be positive and forward looking.)
This variable is read-only and dynamically scoped to the current BLOCK.
+=item $^N
+
+The text matched by the used group most-recently closed (i.e. the group
+with the rightmost closing parenthesis) of the last successful search
+pattern. (Mnemonic: the (possibly) Nested parenthesis that most
+recently closed.)
+
+This is primarly used inside C<(?{...})> blocks for examining text
+recently matched. For example, to effectively capture text to a variable
+(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
+
+ (?:(...)(?{ $var = $^N }))
+
+By setting and then using C<$var> in this way relieves you from having to
+worry about exactly which numbered set of parentheses they are.
+
+This variable is dynamically scoped to the current BLOCK.
+
=item @LAST_MATCH_END
=item @+
=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.
-=item input_line_number HANDLE EXPR
+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 HANDLE->input_line_number(EXPR)
=item $INPUT_LINE_NUMBER
=item $.
-The current input record number for the last file handle from which
-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<< <> >> 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. 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
+Current line number for the last filehandle accessed.
+
+Each filehandle in Perl counts the number of lines that have been read
+from it. (Depending on the value of C<$/>, Perl's idea of what
+constitutes a line may not match yours.) When a line is read from a
+filehandle (via readline() or C<< <> >>), or when tell() or seek() is
+called on it, C<$.> becomes an alias to the line counter for that
+filehandle.
+
+You can adjust the counter by assigning to C<$.>, but this will not
+actually move the seek pointer. I<Localizing C<$.> will not localize
+the filehandle's line count>. Instead, it will localize perl's notion
+of which filehandle C<$.> is currently aliased to.
+
+C<$.> is reset when the filehandle is closed, but B<not> when an open
+filehandle is reopened without an intervening close(). For more
+details, see L<perlop/"I/O Operators">. Because C<< <> >> never does
+an explicit close, line numbers increase across ARGV files (but see
+examples in L<perlfunc/eof>).
+
+You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
+line counter for a given filehandle without having to worry about
+which handle you last accessed.
+
+(Mnemonic: many programs use "." to mean the current line number.)
+
+=item IO::Handle->input_record_separator(EXPR)
=item $INPUT_RECORD_SEPARATOR
paragraph, even if it's a newline. (Mnemonic: / delimits
line boundaries when quoting poetry.)
- undef $/; # enable "slurp" mode
- $_ = <FH>; # whole file now here
+ local $/; # enable "slurp" mode
+ local $_ = <FH>; # whole file now here
s/\n[ \t]+/ /g;
Remember: the value of C<$/> is a string, not a regex. B<awk> has to be
instead of lines, with the maximum record size being the referenced
integer. So this:
- $/ = \32768; # or \"32768", or \$var_containing_32768
- open(FILE, $myfile);
- $_ = <FILE>;
+ local $/ = \32768; # or \"32768", or \$var_containing_32768
+ open my $fh, $myfile or die $!;
+ local $_ = <$fh>;
will read a record of no more than 32768 bytes from FILE. If you're
not reading from a record-oriented file (or your OS doesn't have
See also L<perlport/"Newlines">. Also see C<$.>.
-=item autoflush HANDLE EXPR
+=item HANDLE->autoflush(EXPR)
=item $OUTPUT_AUTOFLUSH
happening. This has no effect on input buffering. See L<perlfunc/getc>
for that. (Mnemonic: when you want your pipes to be piping hot.)
-=item output_field_separator HANDLE EXPR
+=item IO::Handle->output_field_separator EXPR
=item $OUTPUT_FIELD_SEPARATOR
between fields. (Mnemonic: what is printed when there is a "," in
your print statement.)
-=item output_record_separator HANDLE EXPR
+=item IO::Handle->output_record_separator EXPR
=item $OUTPUT_RECORD_SEPARATOR
Use of C<$#> is deprecated.
-=item format_page_number HANDLE EXPR
+=item HANDLE->format_page_number(EXPR)
=item $FORMAT_PAGE_NUMBER
Used with formats.
(Mnemonic: % is page number in B<nroff>.)
-=item format_lines_per_page HANDLE EXPR
+=item HANDLE->format_lines_per_page(EXPR)
=item $FORMAT_LINES_PER_PAGE
Used with formats.
(Mnemonic: = has horizontal lines.)
-=item format_lines_left HANDLE EXPR
+=item HANDLE->format_lines_left(EXPR)
=item $FORMAT_LINES_LEFT
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.
+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.
After a match against some variable $var:
=back
-=item format_name HANDLE EXPR
+=item HANDLE->format_name(EXPR)
=item $FORMAT_NAME
channel. Default is the name of the filehandle. (Mnemonic: brother to
C<$^>.)
-=item format_top_name HANDLE EXPR
+=item HANDLE->format_top_name(EXPR)
=item $FORMAT_TOP_NAME
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 IO::Handle->format_line_break_characters EXPR
=item $FORMAT_LINE_BREAK_CHARACTERS
S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in
poetry is a part of a line.)
-=item format_formfeed HANDLE EXPR
+=item IO::Handle->format_formfeed EXPR
=item $FORMAT_FORMFEED
Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
actual VMS exit status, instead of the default emulation of POSIX
-status.
+status; see L<perlvms/$?> for details.
Also see L<Error Indicators>.
=item $@
-The Perl syntax error message from the last eval() operator. If null, the
-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"?)
+The Perl syntax error message from the last eval() operator.
+If $@ is the null string, the 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"?)
Warning messages are not collected in this variable. You can,
however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
=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.)
C<< $< >> and C<< $> >> can be swapped only on machines
supporting setreuid().
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.)
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.)
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
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;
+ 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.
The name that the Perl binary itself was executed as, from C's C<argv[0]>.
This may not be a full pathname, nor even necessarily in your path.
+=item ARGV
+
+The special filehandle that iterates over command-line filenames in
+C<@ARGV>. Usually written as the null filehandle in the angle operator
+C<< <> >>. Note that currently C<ARGV> only has its magical effect
+within the C<< <> >> operator; elsewhere it is just a plain filehandle
+corresponding to the last file opened by C<< <> >>. In particular,
+passing C<\*ARGV> as a parameter to a function that expects a filehandle
+may not cause your function to automatically read the contents of all the
+files in C<@ARGV>.
+
=item $ARGV
contains the name of the current file when reading from <>.
one, because C<$ARGV[0]> is the first argument, I<not> the program's
command name itself. See C<$0> for the command name.
+=item @F
+
+The array @F contains the fields of each line read in when autosplit
+mode is turned on. See L<perlrun> for the B<-a> switch. This array
+is package-specific, and must be declared or given a full package name
+if not in package main when running under C<strict 'vars'>.
+
=item @INC
The array @INC contains the list of places that the C<do EXPR>,
use lib '/mypath/libdir/';
use SomeMod;
+You can also insert hooks into the file inclusion system by putting Perl
+code directly into @INC. Those hooks may be subroutine references, array
+references or blessed objects. See L<perlfunc/require> for details.
+
=item @_
Within a subroutine the array @_ contains the parameters passed to that
operator uses this hash to determine whether a particular file has
already been included.
+If the file was loaded via a hook (e.g. a subroutine reference, see
+L<perlfunc/require> for a description of these hooks), this hook is
+by default inserted into %INC in place of a filename. Note, however,
+that the hook may have set the %INC entry by itself to provide some more
+specific info.
+
=item %ENV
=item $ENV{expr}
following Perl expression, which uses a single-quoted string:
eval q{
- open PIPE, "/cdrom/install |";
- @res = <PIPE>;
- close PIPE or die "bad pipe: $?, $!";
+ open my $pipe, "/cdrom/install |" or die $!;
+ my @res = <$pipe>;
+ close $pipe or die "bad pipe: $?, $!";
};
After execution of this statement all 4 variables may have been set.
projects / p5sagit/p5-mst-13.2.git / blobdiff