X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=0dcb2ac3d766f791bee9fa74085dc51533e74099;hb=332ddc25e33054764b72da8fd0b572ab1c6c6e65;hp=cd610685f6ef707fc8c0a939423bd364a10fdcdd;hpb=9b0e6e7ac78a7fce8230b6418f1fbc16253fbb9b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index cd61068..0dcb2ac 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -44,6 +44,71 @@ 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. +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. @@ -111,6 +176,21 @@ test. Outside a C test, this will not happen. =over 8 +=item $a + +=item $b + +Special package variables when using sort(), see L. +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 or C +if you want to be able to use them in the sort() comparison block +or function. + +=back + +=over 8 + =item $> Contains the subpattern from the corresponding set of capturing @@ -129,7 +209,7 @@ BLOCK). (Mnemonic: like & in some editors.) This variable is read-only and dynamically scoped to the current BLOCK. The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +performance penalty on all regular expression matches. See L. =item $PREMATCH @@ -141,7 +221,7 @@ enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted string.) This variable is read-only. The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +performance penalty on all regular expression matches. See L. =item $POSTMATCH @@ -152,28 +232,46 @@ pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted string.) Example: - $_ = 'abcdefghi'; + local $_ = 'abcdefghi'; /def/; print "$`:$&:$'\n"; # prints abc:def:ghi This variable is read-only and dynamically scoped to the current BLOCK. The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. +performance penalty on all regular expression matches. See L. =item $LAST_PAREN_MATCH =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 primarily 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 @+ @@ -209,7 +307,7 @@ 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 is applied on the value. -=item input_line_number HANDLE EXPR +=item HANDLE->input_line_number(EXPR) =item $INPUT_LINE_NUMBER @@ -217,20 +315,33 @@ makes that an implicit C is applied on the value. =item $. -The current input record number for the last file handle from which -you just read() (or called a C or C 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). -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 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 when an open +filehandle is reopened without an intervening close(). For more +details, see L. Because C<< <> >> never does +an explicit close, line numbers increase across ARGV files (but see +examples in L). + +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 @@ -252,8 +363,8 @@ blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / delimits line boundaries when quoting poetry.) - undef $/; # enable "slurp" mode - $_ = ; # whole file now here + local $/; # enable "slurp" mode + local $_ = ; # whole file now here s/\n[ \t]+/ /g; Remember: the value of C<$/> is a string, not a regex. B has to be @@ -264,9 +375,9 @@ scalar that's convertible to an integer will attempt to read records instead of lines, with the maximum record size being the referenced integer. So this: - $/ = \32768; # or \"32768", or \$var_containing_32768 - open(FILE, $myfile); - $_ = ; + 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 @@ -283,7 +394,7 @@ non-record reads of a file. See also L. Also see C<$.>. -=item autoflush HANDLE EXPR +=item HANDLE->autoflush(EXPR) =item $OUTPUT_AUTOFLUSH @@ -301,7 +412,7 @@ a Perl program under B and want to see the output as it's happening. This has no effect on input buffering. See L 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 @@ -316,7 +427,7 @@ 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.) -=item output_record_separator HANDLE EXPR +=item IO::Handle->output_record_separator EXPR =item $OUTPUT_RECORD_SEPARATOR @@ -387,7 +498,7 @@ explicitly to get B's value. (Mnemonic: # is the number sign.) Use of C<$#> is deprecated. -=item format_page_number HANDLE EXPR +=item HANDLE->format_page_number(EXPR) =item $FORMAT_PAGE_NUMBER @@ -397,7 +508,7 @@ The current page number of the currently selected output channel. Used with formats. (Mnemonic: % is page number in B.) -=item format_lines_per_page HANDLE EXPR +=item HANDLE->format_lines_per_page(EXPR) =item $FORMAT_LINES_PER_PAGE @@ -408,7 +519,7 @@ output channel. Default is 60. Used with formats. (Mnemonic: = has horizontal lines.) -=item format_lines_left HANDLE EXPR +=item HANDLE->format_lines_left(EXPR) =item $FORMAT_LINES_LEFT @@ -439,10 +550,8 @@ 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 Ith element of this array holds the offset -of the Ith 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 Ith 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: @@ -462,7 +571,7 @@ After a match against some variable $var: =back -=item format_name HANDLE EXPR +=item HANDLE->format_name(EXPR) =item $FORMAT_NAME @@ -472,7 +581,7 @@ The name of the current report format for the currently selected output 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 @@ -482,7 +591,7 @@ The name of the current top-of-page format for the currently selected 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 @@ -493,7 +602,7 @@ fill continuation fields (starting with ^) in a format. Default is 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 @@ -541,10 +650,15 @@ change the exit status of your program. For example: Under VMS, the pragma C makes C<$?> reflect the actual VMS exit status, instead of the default emulation of POSIX -status. +status; see L for details. Also see L. +=item ${^ENCODING} + +The encoding used to interpret native eight-bit encodings to Unicode, +see L. An opaque C object. + =item $OS_ERROR =item $ERRNO @@ -596,10 +710,10 @@ Also see L. =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__}> @@ -735,10 +849,9 @@ of perl in the right bracket?) Example: See also the documentation of C and C 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. +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 @@ -852,6 +965,12 @@ built, as determined during the configuration process. The value is identical to C<$Config{'osname'}>. See also L and the B<-V> command-line switch documented in L. +=item ${^OPEN} + +An internal variable used by PerlIO. A string in two parts, separated +by a C<\0> byte, the first part is the input disciplines, the second +part is the output disciplines. + =item $PERLDB =item $^P @@ -930,6 +1049,11 @@ The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, and B<-C> filetests are based on this value. +=item ${^TAINT} + +Reflects if taint mode is on or off (i.e. if the program was run with +B<-T> or not). True for on, false for off. + =item $PERL_VERSION =item $^V @@ -986,6 +1110,17 @@ lexical scope. See L. The name that the Perl binary itself was executed as, from C's C. 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 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 <>. @@ -1018,6 +1153,10 @@ loaded also: 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 for details. + =item @_ Within a subroutine the array @_ contains the parameters passed to that @@ -1032,6 +1171,12 @@ value is the location of the file found. The C 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 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} @@ -1151,9 +1296,9 @@ To illustrate the differences between these variables, consider the following Perl expression, which uses a single-quoted string: eval q{ - open PIPE, "/cdrom/install |"; - @res = ; - 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. @@ -1242,7 +1387,7 @@ expression matches in a program, regardless of whether they occur in the scope of C. For that reason, saying C in libraries is strongly discouraged. See the Devel::SawAmpersand module documentation from CPAN -(http://www.perl.com/CPAN/modules/by-module/Devel/) +(http://www.cpan.org/modules/by-module/Devel/) for more information. Having to even think about the C<$^S> variable in your exception