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 @+
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 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__}>
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