X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=13922fecd85d7e5cae21b7c7ad8a60fb44fd3dd9;hb=38e4f4aed799ac2e3ef36186e997df88f9da92d2;hp=5e705313d5133a93b0af3fa4d45712337961b023;hpb=146174a91a192983720a158796dc066226ad0e55;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 5e70531..13922fe 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. @@ -99,7 +171,7 @@ The implicit iterator variable in the grep() and map() functions. =item * -The default place to put an input record when a CFHE> +The default place to put an input record when a C<< >> operation's result is tested by itself as the sole criterion of a C test. Outside a C test, this will not happen. @@ -111,7 +183,22 @@ test. Outside a C test, this will not happen. =over 8 -=item $EIE +=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 parentheses from the last pattern match, not counting patterns @@ -129,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 @@ -141,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 @@ -152,57 +239,82 @@ 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 @+ +=item $^N -$+[0] is the offset of the end of the last successful match. -C<$+[>IC<]> is the offset of the end of the substring matched by -I-th subpattern, or undef if the subpattern did not match. +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.) -Thus after a match against $_, $& coincides with C. Similarly, C<$>I coincides with CIC<], -$+[>IC<] - $-[>IC<]> if C<$-[>IC<]> is defined, and $+ coincides with -C. One can use C<$#+> to find the number -of subgroups in the last successful match. Contrast with -C<$#->, the last I subgroup. Compare with C<@->. +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 @+ + +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 function returns when called +on the variable that was matched against. The Ith element +of this array holds the offset of the Ith 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 and C 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 is applied on the value. + +=item HANDLE->input_line_number(EXPR) =item $INPUT_LINE_NUMBER @@ -210,20 +322,33 @@ the C and C modifiers on pattern matching. =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 CE> 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 LO Operators">. 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 @@ -245,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 @@ -257,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 @@ -276,7 +401,7 @@ non-record reads of a file. See also L. Also see C<$.>. -=item autoflush HANDLE EXPR +=item HANDLE->autoflush(EXPR) =item $OUTPUT_AUTOFLUSH @@ -294,7 +419,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 @@ -309,7 +434,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 @@ -380,7 +505,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 @@ -390,7 +515,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 @@ -401,7 +526,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 @@ -412,6 +537,8 @@ channel. 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. @@ -426,7 +553,32 @@ matched subgroup in the last successful match. Contrast with C<$#+>, the number of subgroups in the regular expression. Compare with C<@+>. -=item format_name HANDLE EXPR +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. + +After a match against some variable $var: + +=over 5 + +=item C<$`> is the same as C + +=item C<$&> is the same as C + +=item C<$'> is the same as C + +=item C<$1> is the same as C + +=item C<$2> is the same as C + +=item C<$3> is the same as C + +=back + +=item HANDLE->format_name(EXPR) =item $FORMAT_NAME @@ -436,7 +588,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 @@ -446,7 +598,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 @@ -457,7 +609,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 @@ -484,7 +636,7 @@ The status returned by the last pipe close, backtick (C<``>) command, 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 really (C<$? EE 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 and B.) @@ -505,10 +657,18 @@ 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 I to the Encode object that is used to convert +the source code to Unicode. Thanks to this variable your perl script +does not have to be written in UTF-8. Default is I. The direct +manipulation of this variable is highly discouraged. See L +for more details. + =item $OS_ERROR =item $ERRNO @@ -516,9 +676,25 @@ Also see L. =item $! If used numerically, yields the current value of the C C -variable, with all the usual caveats. (This means that you shouldn't -depend on the value of C<$!> to be anything in particular unless -you've gotten a specific error return indicating a system error.) +variable, or in other words, if a system or library call fails, it +sets this variable. This means that the value of C<$!> is meaningful +only I after a B: + + if (open(FH, $filename)) { + # Here $! is meaningless. + ... + } else { + # ONLY here is $! meaningful. + ... + # Already here $! might be meaningless. + } + # Since here we might have either success or failure, + # here $! is meaningless. + +In the above I stands for anything: zero, non-zero, +C. A successful system or library call does B set +the variable to zero. + If used an a string, yields the corresponding system error string. You can assign a number to C<$!> to set I if, for instance, you want C<"$!"> to return the string for error I, or you want @@ -527,6 +703,18 @@ went bang?) Also see L. +=item %! + +Each element of C<%!> has a true value only if C<$!> is set to that +value. For example, C<$!{ENOENT}> is true if and only if the current +value of C<$!> is C; that is, if the most recent error was +"No such file or directory" (or its moral equivalent: not all operating +systems give that exact error, and certainly not all languages). +To check if a particular key is meaningful on your system, use +C; for a list of legal keys, use C. +See L for more information, and also see above for the +validity of C<$!>. + =item $EXTENDED_OS_ERROR =item $^E @@ -560,10 +748,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__}> @@ -588,7 +776,8 @@ across fork() calls. (Mnemonic: same as shells.) =item $< The real uid of this process. (Mnemonic: it's the uid you came I, -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 @@ -601,8 +790,11 @@ The effective uid of this process. Example: $< = $>; # 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, if you're running setuid.) -C<$E> and C<$E> can be swapped only on machines +C<< $< >> and C<< $> >> can be swapped only on machines supporting setreuid(). =item $REAL_GROUP_ID @@ -621,6 +813,9 @@ However, a value assigned to C<$(> must be a single number used to set the real gid. So the value given by C<$(> should I 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 things. The real gid is the group you I, if you're running setgid.) @@ -643,10 +838,13 @@ 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 things. The effective gid is the group that's I for you, if you're running setgid.) -C<$E>, C<$E>, C<$(> and C<$)> can be set only on +C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on machines that support the corresponding I routine. C<$(> and C<$)> can be swapped only on machines supporting setregid(). @@ -660,6 +858,11 @@ program sees. This is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as B and B.) +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 @@ -672,8 +875,6 @@ As of release 5 of Perl, assignment to C<$[> is treated as a compiler 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 @@ -686,6 +887,10 @@ 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 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 @@ -713,12 +918,59 @@ descriptors are not. Also, during an open(), system file descriptors are 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 and other block -scoped compiler hints. See the documentation of C 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 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 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 @@ -737,10 +989,10 @@ Then $^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 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 long name for this variable. +feature, there is no L long name for this variable. =item $OSNAME @@ -751,6 +1003,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 @@ -784,16 +1042,37 @@ Keep info about source lines on which a subroutine is defined. Start with single-step on. +=item 0x40 + +Use subroutine address instead of name when reporting. + +=item 0x80 + +Report C 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). May be written to. +=item $EXCEPTIONS_BEING_CAUGHT + =item $^S Current state of the interpreter. Undefined if parsing of the current @@ -808,6 +1087,37 @@ 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 + +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 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; + +To convert C<$^V> into its string representation use sprintf()'s +C<"%vd"> conversion: + + printf "version is v%vd\n", $^V; # Perl's version + +See the documentation of C and C +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 @@ -816,21 +1126,61 @@ 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. -=item ${^Warnings} +=item ${^WARNING_BITS} The current set of warning checks enabled by the C pragma. See the documentation of C 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 pragma always overrides the effect of this flag in the current +lexical scope. See L. + =item $EXECUTABLE_NAME =item $^X -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. +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. Currently there is no universal solution for this, you may try +to use: + + use Config; + $current_perl_path = (-x $^X) ? $^X : $Config{perlpath}; + +The security-conscious would write: + + use Config; + use File::Spec; + $current_perl_path = (File::Spec->file_name_is_absolute($^X) && -x $^X) + ? $^X : $Config{perlpath}; + +=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 EE. +contains the name of the current file when reading from <>. =item @ARGV @@ -839,6 +1189,13 @@ the script. C<$#ARGV> is generally the number of arguments minus one, because C<$ARGV[0]> is the first argument, I 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 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. + =item @INC The array @INC contains the list of places that the C, @@ -846,13 +1203,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 @@ -867,6 +1229,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} @@ -986,9 +1354,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. @@ -1000,7 +1368,7 @@ the value of $@ is the compile error, or the argument to C (which will interpolate C<$!> and C<$?>!). (See also L, though.) -When the eval() expression above is executed, open(), C<>, +When the eval() expression above is executed, open(), C<< >>, and C 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 if one of these calls fails. @@ -1077,7 +1445,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/Devel-SawAmpersand-0.10.readme) +( http://www.cpan.org/modules/by-module/Devel/ ) for more information. Having to even think about the C<$^S> variable in your exception