X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=ac4ebf828aeeac47fab13a0b54e0875ef0981f39;hb=a1ce9542567c946a9e13885800d99a27d4b700db;hp=3f4c2f525533d3c3fab0e9723553dd1b491cd56f;hpb=fcc7d9162bf1fd237414451c224b7d78e0ae1e60;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 3f4c2f5..ac4ebf8 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -13,14 +13,20 @@ you need only say use English; -at the top of your program. This will alias all the short names to the -long names in the current package. Some even have medium names, -generally borrowed from B. +at the top of your program. This aliases all the short names to the long +names in the current package. Some even have medium names, generally +borrowed from B. In general, it's best to use the -If you don't mind the performance hit, variables that depend on the -currently selected filehandle may instead be set by calling an -appropriate object method on the IO::Handle object. (Summary lines -below for this contain the word HANDLE.) First you must say + use English '-no_match_vars'; + +invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids +a certain performance hit with the use of regular expressions. See +L. + +Variables that depend on the currently selected filehandle may be set by +calling an appropriate object method on the IO::Handle object, although +this is less efficient than using the regular built-in variables. (Summary +lines below for this contain the word HANDLE.) First you must say use IO::Handle; @@ -33,10 +39,11 @@ or more safely, HANDLE->method(EXPR) Each method returns the old value of the IO::Handle attribute. -The methods each take an optional EXPR, which if supplied specifies the +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 methods do nothing to the current value--except for autoflush(), which will assume a 1 for you, just to be different. + Because loading in the IO::Handle class is an expensive operation, you should learn how to use the regular built-in variables. @@ -44,6 +51,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. @@ -144,7 +216,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 @@ -156,7 +228,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 @@ -167,14 +239,14 @@ 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 @@ -196,7 +268,7 @@ 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 +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 @@ -266,7 +338,7 @@ 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 +details, see LO Operators">. Because C<< <> >> never does an explicit close, line numbers increase across ARGV files (but see examples in L). @@ -298,8 +370,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 @@ -310,9 +382,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 @@ -589,6 +661,11 @@ 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 @@ -779,10 +856,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 @@ -896,6 +972,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 @@ -974,6 +1056,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 @@ -1030,6 +1117,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 <>. @@ -1055,13 +1153,18 @@ C, or C constructs look for their library files. It initially consists of the arguments to any B<-I> command-line switches, followed by the default Perl library, probably F, followed by ".", to represent the current -directory. If you need to modify this at runtime, you should use +directory. ("." will not be appended if taint checks are enabled, either by +C<-T> or by C<-t>.) If you need to modify this at runtime, you should use the C pragma to get the machine-dependent library properly 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 @@ -1076,6 +1179,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} @@ -1195,9 +1304,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. @@ -1286,7 +1395,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