X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=15308e45aab4d907c005394eba798f3fc82af34d;hb=db22727b1cdf038cfb2d069831d76310ffc4b838;hp=9402608dafdcd59d63446547516c384b5d31da33;hpb=1e374101a32f2df640b9fad36d86b2ed88f6eaf8;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 9402608..15308e4 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -45,9 +45,7 @@ you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception. The following list is ordered by scalar variables first, then the -arrays, then the hashes (except $^M was added in the wrong place). -This is somewhat obscured because %ENV and %SIG are listed as -$ENV{expr} and $SIG{expr}. +arrays, then the hashes. =over 8 @@ -101,7 +99,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. @@ -113,7 +111,7 @@ test. Outside a C test, this will not happen. =over 8 -=item $EIE +=item $> Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns @@ -176,18 +174,20 @@ example: (Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. -=item @+ +=item @LAST_MATCH_END -$+[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. +=item @+ -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 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 @@ -217,7 +217,7 @@ 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 +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<$.> @@ -272,7 +272,7 @@ set, you'll get the record back in pieces. On VMS, record reads are done with the equivalent of C, so it's best not to mix record and non-record reads on the same file. (This is unlikely to be a problem, because any file you'd -want to read in record mode is probably usable in line mode.) +want to read in record mode is probably unusable in line mode.) Non-VMS systems do normal I/O, so it's safe to mix record and non-record reads of a file. @@ -414,6 +414,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. @@ -428,6 +430,33 @@ matched subgroup in the last successful match. Contrast with C<$#+>, the number of subgroups in the regular expression. Compare with C<@+>. +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. + +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 format_name HANDLE EXPR =item $FORMAT_NAME @@ -486,7 +515,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.) @@ -604,7 +633,7 @@ The effective uid of this process. Example: ($<,$>) = ($>,$<); # swap real and effective uid (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 @@ -648,7 +677,7 @@ list, say C< $) = "5 5" >. (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(). @@ -674,8 +703,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 @@ -688,6 +715,11 @@ 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. + =item $COMPILING =item $^C @@ -715,12 +747,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 @@ -739,7 +818,7 @@ 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. @@ -786,16 +865,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 @@ -810,13 +910,54 @@ 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 $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; + +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 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. +related to the B<-w> switch.) See also L. + +=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 @@ -827,7 +968,7 @@ This may not be a full pathname, nor even necessarily in your path. =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 @@ -861,7 +1002,7 @@ The hash %INC contains entries for each filename included via the C, C, or C operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The C -operator uses this array to determine whether a particular file has +operator uses this hash to determine whether a particular file has already been included. =item %ENV @@ -965,7 +1106,7 @@ Carp was available. The third line will be executed only if Carp was not available. See L, L, L, and -L for additional information. +L for additional information. =back @@ -997,7 +1138,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. @@ -1040,7 +1181,7 @@ C) is the scalar variable whose name is the single character control-C. This is better than typing a literal control-C into your program. -Finally, new in Perl 5.006, Perl variable names may be alphanumeric +Finally, new in Perl 5.6, Perl variable names may be alphanumeric strings that begin with control characters (or better yet, a caret). These variables must be written in the form C<${^Foo}>; the braces are not optional. C<${^Foo}> denotes the scalar variable whose @@ -1074,7 +1215,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.perl.com/CPAN/modules/by-module/Devel/) for more information. Having to even think about the C<$^S> variable in your exception