X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=c3adfa0a1008f4f8c41bbc904e797f556ac82828;hb=62aa7ed050aea99a989c95f16814568cdce5b315;hp=68c8303aea6c2b77d733d8cf4f2c850bcf69eb56;hpb=46e5f5f47696caa998bfcb1e374d29f888f44b9b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 68c8303..c3adfa0 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -124,6 +124,7 @@ arrays, then the hashes. =item $ARG =item $_ +X<$_> X<$ARG> The default input and pattern-searching space. The following pairs are equivalent: @@ -191,6 +192,7 @@ declaring C restores the global C<$_> in the current scope. =item $a =item $b +X<$a> X<$b> Special package variables when using sort(), see L. Because of this specialness $a and $b don't need to be declared @@ -203,6 +205,7 @@ able to use them in the sort() comparison block or function. =over 8 =item $> +X<$1> X<$2> X<$3> Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns @@ -213,6 +216,7 @@ scoped to the current BLOCK. =item $MATCH =item $& +X<$&> X<$MATCH> The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current @@ -222,9 +226,20 @@ 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. +See L for a replacement. + +=item ${^MATCH} +X<${^MATCH}> + +This is similar to C<$&> (C<$POSTMATCH>) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. + =item $PREMATCH =item $` +X<$`> X<$PREMATCH> The string preceding whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval @@ -234,9 +249,20 @@ 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. +See L for a replacement. + +=item ${^PREMATCH} +X<${^PREMATCH}> + +This is similar to C<$`> ($PREMATCH) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. + =item $POSTMATCH =item $' +X<$'> X<$POSTMATCH> The string following whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() @@ -252,9 +278,20 @@ 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. +See L for a replacement. + +=item ${^POSTMATCH} +X<${^POSTMATCH}> + +This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C

modifier. + =item $LAST_PAREN_MATCH =item $+ +X<$+> X<$LAST_PAREN_MATCH> 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 @@ -266,6 +303,7 @@ matched. For example: This variable is read-only and dynamically scoped to the current BLOCK. =item $^N +X<$^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 @@ -286,6 +324,7 @@ This variable is dynamically scoped to the current BLOCK. =item @LAST_MATCH_END =item @+ +X<@+> X<@LAST_MATCH_END> This array holds the offsets of the ends of the last successful submatches in the currently active dynamic scope. C<$+[0]> is @@ -298,6 +337,29 @@ 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 %+ +X<%+> + +Similar to C<@+>, the C<%+> hash allows access to the named capture +buffers, should they exist, in the last successful match in the +currently active dynamic scope. + +For example, C<$+{foo}> is equivalent to C<$1> after the following match: + + 'foo' =~ /(?foo)/; + +The keys of the C<%+> hash list only the names of buffers that have +captured (and that are thus associated to defined values). + +The underlying behaviour of C<%+> is provided by the +L module. + +B C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. + =item HANDLE->input_line_number(EXPR) =item $INPUT_LINE_NUMBER @@ -305,8 +367,9 @@ examples given for the C<@-> variable. =item $NR =item $. +X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X -Current line number for the last filehandle accessed. +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 @@ -339,6 +402,7 @@ which handle you last accessed. =item $RS =item $/ +X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> The input record separator, newline by default. This influences Perl's idea of what a "line" is. Works like B's RS @@ -391,6 +455,7 @@ See also L. Also see C<$.>. =item $OUTPUT_AUTOFLUSH =item $| +X<$|> X X X<$OUTPUT_AUTOFLUSH> If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 @@ -411,6 +476,7 @@ for that. (Mnemonic: when you want your pipes to be piping hot.) =item $OFS =item $, +X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> The output field separator for the print operator. If defined, this value is printed between each of print's arguments. Default is C. @@ -423,6 +489,7 @@ value is printed between each of print's arguments. Default is C. =item $ORS =item $\ +X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> The output record separator for the print operator. If defined, this value is printed after the last of print's arguments. Default is C. @@ -432,6 +499,7 @@ Also, it's just like C<$/>, but it's what you get "back" from Perl.) =item $LIST_SEPARATOR =item $" +X<$"> X<$LIST_SEPARATOR> This is like C<$,> except that it applies to array and slice values interpolated into a double-quoted string (or similar interpreted @@ -442,6 +510,7 @@ string). Default is a space. (Mnemonic: obvious, I think.) =item $SUBSEP =item $; +X<$;> X<$SUBSEP> X The subscript separator for multidimensional array emulation. If you refer to a hash element as @@ -474,6 +543,7 @@ in L. =item $FORMAT_PAGE_NUMBER =item $% +X<$%> X<$FORMAT_PAGE_NUMBER> The current page number of the currently selected output channel. Used with formats. @@ -484,6 +554,7 @@ Used with formats. =item $FORMAT_LINES_PER_PAGE =item $= +X<$=> X<$FORMAT_LINES_PER_PAGE> The current page length (printable lines) of the currently selected output channel. Default is 60. @@ -495,6 +566,7 @@ Used with formats. =item $FORMAT_LINES_LEFT =item $- +X<$-> X<$FORMAT_LINES_LEFT> The number of lines left on the page of the currently selected output channel. @@ -504,6 +576,7 @@ Used with formats. =item @LAST_MATCH_START =item @- +X<@-> X<@LAST_MATCH_START> $-[0] is the offset of the start of the last successful match. C<$-[>IC<]> is the offset of the start of the substring matched by @@ -542,11 +615,54 @@ After a match against some variable $var: =back +=item %- +X<%-> + +Similar to C<%+>, this variable allows access to the named capture buffers +in the last successful match in the currently active dynamic scope. To +each capture buffer name found in the regular expression, it associates a +reference to an array containing the list of values captured by all +buffers with that name (should there be several of them), in the order +where they appear. + +Here's an example: + + if ('1234' =~ /(?1)(?2)(?3)(?4)/) { + foreach my $bufname (sort keys %-) { + my $ary = $-{$bufname}; + foreach my $idx (0..$#$ary) { + print "\$-{$bufname}[$idx] : ", + (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), + "\n"; + } + } + } + +would print out: + + $-{A}[0] : '1' + $-{A}[1] : '3' + $-{B}[0] : '2' + $-{B}[1] : '4' + +The keys of the C<%-> hash correspond to all buffer names found in +the regular expression. + +The behaviour of C<%-> is implemented via the +L module. + +B C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. + =item HANDLE->format_name(EXPR) =item $FORMAT_NAME =item $~ +X<$~> X<$FORMAT_NAME> The name of the current report format for the currently selected output channel. Default is the name of the filehandle. (Mnemonic: brother to @@ -557,6 +673,7 @@ C<$^>.) =item $FORMAT_TOP_NAME =item $^ +X<$^> X<$FORMAT_TOP_NAME> The name of the current top-of-page format for the currently selected output channel. Default is the name of the filehandle with _TOP @@ -567,6 +684,7 @@ appended. (Mnemonic: points to top of page.) =item $FORMAT_LINE_BREAK_CHARACTERS =item $: +X<$:> X The current set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format. Default is @@ -578,12 +696,14 @@ poetry is a part of a line.) =item $FORMAT_FORMFEED =item $^L +X<$^L> X<$FORMAT_FORMFEED> What formats output as a form feed. Default is \f. =item $ACCUMULATOR =item $^A +X<$^A> X<$ACCUMULATOR> The current value of the write() accumulator for format() lines. A format contains formline() calls that put their result into C<$^A>. After @@ -595,6 +715,7 @@ L. =item $CHILD_ERROR =item $? +X<$?> X<$CHILD_ERROR> The status returned by the last pipe close, backtick (C<``>) command, successful call to wait() or waitpid(), or from the system() @@ -626,6 +747,7 @@ status; see L for details. Also see L. =item ${^CHILD_ERROR_NATIVE} +X<$^CHILD_ERROR_NATIVE> The native status returned by the last pipe close, backtick (C<``>) command, successful call to wait() or waitpid(), or from the system() @@ -637,6 +759,7 @@ Under VMS this reflects the actual VMS exit status; i.e. it is the same as $? when the pragma C is in effect. =item ${^ENCODING} +X<$^ENCODING> The I to the Encode object that is used to convert the source code to Unicode. Thanks to this variable your perl script @@ -649,6 +772,7 @@ for more details. =item $ERRNO =item $! +X<$!> X<$ERRNO> X<$OS_ERROR> If used numerically, yields the current value of the C C variable, or in other words, if a system or library call fails, it @@ -679,6 +803,7 @@ went bang?) Also see L. =item %! +X<%!> 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 @@ -693,6 +818,7 @@ validity of C<$!>. =item $EXTENDED_OS_ERROR =item $^E +X<$^E> X<$EXTENDED_OS_ERROR> Error information specific to the current operating system. At the moment, this differs from C<$!> under only VMS, OS/2, and Win32 @@ -722,6 +848,7 @@ Also see L. =item $EVAL_ERROR =item $@ +X<$@> X<$EVAL_ERROR> The Perl syntax error message from the last eval() operator. If $@ is the null string, the last eval() parsed and executed @@ -739,6 +866,7 @@ Also see L. =item $PID =item $$ +X<$$> X<$PID> X<$PROCESS_ID> The process number of the Perl running this script. You should consider this variable read-only, although it will be altered @@ -755,6 +883,7 @@ you may use the CPAN module C. =item $UID =item $< +X<< $< >> X<$UID> X<$REAL_USER_ID> The real uid of this process. (Mnemonic: it's the uid you came I, if you're running setuid.) You can change both the real uid and @@ -767,6 +896,7 @@ detect any possible errors. =item $EUID =item $> +X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> The effective uid of this process. Example: @@ -786,6 +916,7 @@ supporting setreuid(). =item $GID =item $( +X<$(> X<$GID> X<$REAL_GROUP_ID> The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated @@ -809,6 +940,7 @@ group you I, if you're running setgid.) =item $EGID =item $) +X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space @@ -838,6 +970,7 @@ and C<$)> can be swapped only on machines supporting setregid(). =item $PROGRAM_NAME =item $0 +X<$0> X<$PROGRAM_NAME> Contains the name of the program being executed. @@ -871,6 +1004,7 @@ the view of C<$0> the other threads have will not change since they have their own copies of it. =item $[ +X<$[> The index of the first element in an array, and of the first character in a substring. Default is 0, but you could theoretically set it @@ -889,6 +1023,7 @@ However, you can use local() on it to strictly bind its value to a lexical block. =item $] +X<$]> The version + patchlevel / 1000 of the Perl interpreter. This variable can be used to determine whether the Perl interpreter executing a @@ -907,16 +1042,18 @@ the Perl version that allows accurate string comparisons. =item $COMPILING =item $^C +X<$^C> X<$COMPILING> The current value of the flag associated with the B<-c> switch. Mainly of use with B<-MO=...> to allow code to alter its behavior when being compiled, such as for example to AUTOLOAD at compile -time rather than normal, deferred loading. See L. Setting +time rather than normal, deferred loading. Setting C<$^C = 1> is similar to calling C. =item $DEBUGGING =item $^D +X<$^D> X<$DEBUGGING> The current value of the debugging flags. (Mnemonic: value of B<-D> switch.) May be read or set. Like its command-line equivalent, you can use @@ -940,6 +1077,7 @@ Under normal situations this variable should be of no interest to you. =item $SYSTEM_FD_MAX =item $^F +X<$^F> X<$SYSTEM_FD_MAX> The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file @@ -1001,11 +1139,13 @@ useful for implementation of lexically scoped pragmas. See L. =item $INPLACE_EDIT =item $^I +X<$^I> X<$INPLACE_EDIT> The current value of the inplace-edit extension. Use C to disable inplace editing. (Mnemonic: value of B<-i> switch.) =item $^M +X<$^M> By default, running out of memory is an untrappable, fatal error. However, if suitably built, Perl can use the contents of C<$^M> @@ -1024,6 +1164,7 @@ this variable. =item $OSNAME =item $^O +X<$^O> X<$OSNAME> The name of the operating system under which this copy of Perl was built, as determined during the configuration process. The value @@ -1045,6 +1186,7 @@ part describes the output layers. =item $PERLDB =item $^P +X<$^P> X<$PERLDB> The internal variable for debugging support. The meanings of the various bits are subject to change, but currently indicate: @@ -1104,6 +1246,7 @@ run-time only. This is a new mechanism and the details may change. =item $LAST_REGEXP_CODE_RESULT =item $^R +X<$^R> X<$LAST_REGEXP_CODE_RESULT> The result of evaluation of the last successful C<(?{ code })> regular expression assertion (see L). May be written to. @@ -1111,6 +1254,7 @@ regular expression assertion (see L). May be written to. =item $EXCEPTIONS_BEING_CAUGHT =item $^S +X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> Current state of the interpreter. @@ -1125,6 +1269,7 @@ The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. =item $BASETIME =item $^T +X<$^T> X<$BASETIME> 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>, @@ -1159,12 +1304,13 @@ switch); see L for more info on this. =item $PERL_VERSION =item $^V +X<$^V> X<$PERL_VERSION> 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. +potentially be greater than 255. This variable first appeared in perl 5.6.0; earlier versions of perl will see an undefined value. @@ -1188,6 +1334,7 @@ See also C<$]> for an older representation of the Perl version. =item $WARNING =item $^W +X<$^W> X<$WARNING> The current value of the warning switch, initially true if B<-w> was used, false otherwise, but directly modifiable. (Mnemonic: @@ -1214,6 +1361,7 @@ customization. =item $EXECUTABLE_NAME =item $^X +X<$^X> X<$EXECUTABLE_NAME> The name used to execute the current copy of Perl, from C's C or (where supported) F. @@ -1263,6 +1411,7 @@ command or referenced as a file. unless $secure_perl_path =~ m/$Config{_exe}$/i;} =item ARGV +X The special filehandle that iterates over command-line filenames in C<@ARGV>. Usually written as the null filehandle in the angle operator @@ -1274,10 +1423,12 @@ may not cause your function to automatically read the contents of all the files in C<@ARGV>. =item $ARGV +X<$ARGV> contains the name of the current file when reading from <>. =item @ARGV +X<@ARGV> The array @ARGV contains the command-line arguments intended for the script. C<$#ARGV> is generally the number of arguments minus @@ -1285,6 +1436,7 @@ one, because C<$ARGV[0]> is the first argument, I the program's command name itself. See C<$0> for the command name. =item ARGVOUT +X The special filehandle that points to the currently open output file when doing edit-in-place processing with B<-i>. Useful when you have @@ -1292,6 +1444,7 @@ to do a lot of inserting and don't want to keep modifying $_. See L for the B<-i> switch. =item @F +X<@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 @@ -1299,6 +1452,7 @@ is package-specific, and must be declared or given a full package name if not in package main when running under C. =item @INC +X<@INC> The array @INC contains the list of places that the C, C, or C constructs look for their library files. It @@ -1317,12 +1471,16 @@ 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 @ARG + =item @_ +X<@_> X<@ARG> Within a subroutine the array @_ contains the parameters passed to that subroutine. See L. =item %INC +X<%INC> The hash %INC contains entries for each filename included via the C, C, or C operators. The key is the filename @@ -1340,6 +1498,7 @@ specific info. =item %ENV =item $ENV{expr} +X<%ENV> The hash %ENV contains your current environment. Setting a value in C changes the environment for any child processes @@ -1348,8 +1507,9 @@ you subsequently fork() off. =item %SIG =item $SIG{expr} +X<%SIG> -The hash %SIG contains signal handlers for signals. For example: +The hash C<%SIG> contains signal handlers for signals. For example: sub handler { # 1st argument is signal name my($sig) = @_; @@ -1388,24 +1548,29 @@ immediate (also known as "unsafe") to deferred, also known as Certain internal hooks can be also set using the %SIG hash. The routine indicated by C<$SIG{__WARN__}> is called when a warning message is about to be printed. The warning message is passed as the first -argument. The presence of a __WARN__ hook causes the ordinary printing -of warnings to STDERR to be suppressed. You can use this to save warnings +argument. The presence of a C<__WARN__> hook causes the ordinary printing +of warnings to C to be suppressed. You can use this to save warnings in a variable, or turn warnings into fatal errors, like this: local $SIG{__WARN__} = sub { die $_[0] }; eval $proggie; +As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can +disable warnings using the empty subroutine: + + local $SIG{__WARN__} = sub {}; + The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception is about to be thrown. The error message is passed as the first -argument. When a __DIE__ hook routine returns, the exception +argument. When a C<__DIE__> hook routine returns, the exception processing continues as it would have in the absence of the hook, -unless the hook routine itself exits via a C, a loop exit, or a die(). +unless the hook routine itself exits via a C, a loop exit, or a C. The C<__DIE__> handler is explicitly disabled during the call, so that you can die from a C<__DIE__> handler. Similarly for C<__WARN__>. Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called even inside an eval(). Do not use this to rewrite a pending exception -in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). +in C<$@>, or as a bizarre substitute for overriding C. This strange action at a distance may be fixed in a future release so that C<$SIG{__DIE__}> is only called if your program is about to exit, as was the original intent. Any other use is deprecated. @@ -1434,6 +1599,7 @@ L for additional information. =back =head2 Error Indicators +X X The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information about different types of error conditions that may appear during @@ -1540,7 +1706,8 @@ 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.cpan.org/modules/by-module/Devel/ ) -for more information. +for more information. Writing C +avoids the performance penalty. Having to even think about the C<$^S> variable in your exception handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented