X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/4a70680af1019e8cdeaf52bb506d9fbda1dd4f05..12e1284a67e5e3404c704c3f864749fd9f04c7c4:/pod/perlvar.pod diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 4b6bb74..6c54f76 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -12,30 +12,30 @@ arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence C<::> or C<'>. In this case, the part before the last C<::> or C<'> is taken to be a I; see L. - -Perl variable names may also be a sequence of digits or a single -punctuation or control character. These names are all reserved for +A Unicode letter that is not ASCII is not considered to be a letter +unless S> is in effect, and somewhat more complicated +rules apply; see L for details. + +Perl variable names may also be a sequence of digits, a single +punctuation character, or the two-character sequence: C<^> (caret or +CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>. +These names are all reserved for special uses by Perl; for example, the all-digits names are used to hold data captured by backreferences after a regular expression -match. Perl has a special syntax for the single-control-character -names: It understands C<^X> (caret C) to mean the control-C -character. For example, the notation C<$^W> (dollar-sign caret -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. - -Since Perl v5.6.0, 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 -name is a control-C followed by two C's. These variables are +match. + +Since Perl v5.6.0, Perl variable names may also be alphanumeric strings +preceded by a caret. These must all be written in the form C<${^Foo}>; +the braces are not optional. C<${^Foo}> denotes the scalar variable +whose name is considered to be a control-C followed by two C's. +These variables are reserved for future special uses by Perl, except for the ones that -begin with C<^_> (control-underscore or caret-underscore). No -control-character name that begins with C<^_> will acquire a special +begin with C<^_> (caret-underscore). No +name that begins with C<^_> will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. C<$^_> itself, however, I reserved. -Perl identifiers that begin with digits, control characters, or +Perl identifiers that begin with digits or punctuation characters are exempt from the effects of the C declaration and are always forced to be in package C
; they are also exempt from C errors. A few other names are also @@ -142,19 +142,12 @@ test. Outside a C test, this will not happen. =back -C<$_> is by default a global variable. However, as -of perl v5.10.0, you can use a lexical version of -C<$_> by declaring it in a file or in a block with C. Moreover, -declaring C restores the global C<$_> in the current scope. Though -this seemed like a good idea at the time it was introduced, lexical C<$_> -actually causes more problems than it solves. If you call a function that -expects to be passed information via C<$_>, it may or may not work, -depending on how the function is written, there not being any easy way to -solve this. Just avoid lexical C<$_>, unless you are feeling particularly -masochistic. For this reason lexical C<$_> is still experimental and will -produce a warning unless warnings have been disabled. As with other -experimental features, the behavior of lexical C<$_> is subject to change -without notice, including change into a fatal error. +C<$_> is a global variable. + +However, between perl v5.10.0 and v5.24.0, it could be used lexically by +writing C. Making C<$_> refer to the global C<$_> in the same scope +was then possible with C. This experimental feature was removed and is +now a fatal error, but you may encounter it in older code. Mnemonic: underline is understood in certain operations. @@ -165,7 +158,7 @@ X<@_> X<@ARG> Within a subroutine the array C<@_> contains the parameters passed to that subroutine. Inside a subroutine, C<@_> is the default array for -the array operators C, C, C, and C. +the array operators C and C. See L. @@ -370,19 +363,19 @@ X<$;> X<$SUBSEP> X The subscript separator for multidimensional array emulation. If you refer to a hash element as - $foo{$a,$b,$c} + $foo{$x,$y,$z} it really means - $foo{join($;, $a, $b, $c)} + $foo{join($;, $x, $y, $z)} But don't put - @foo{$a,$b,$c} # a slice--note the @ + @foo{$x,$y,$z} # a slice--note the @ which means - ($foo{$a},$foo{$b},$foo{$c}) + ($foo{$x},$foo{$y},$foo{$z}) Default is "\034", the same as SUBSEP in B. If your keys contain binary data there might not be any safe value for C<$;>. @@ -432,6 +425,45 @@ Previously, only child processes received stringified values: This happens because you can't really share arbitrary data structures with foreign processes. +=item $OLD_PERL_VERSION + +=item $] +X<$]> X<$OLD_PERL_VERSION> + +The revision, version, and subversion of the Perl interpreter, represented +as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY +is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001". + +This variable can be used to determine whether the Perl interpreter +executing a script is in the right range of versions: + + warn "No PerlIO!\n" if $] lt '5.008'; + +When comparing C<$]>, string comparison operators are B. The inherent limitations of binary floating point +representation can sometimes lead to incorrect comparisons for some +numbers on some architectures. + +See also the documentation of C and C +for a convenient way to fail if the running Perl interpreter is too old. + +See L for a representation of the Perl version as a L +object, which allows more flexible string comparisons. + +The main advantage of C<$]> over C<$^V> is that it works the same on any +version of Perl. The disadvantages are that it can't easily be compared +to versions in other formats (e.g. literal v-strings, "v1.2.3" or +version objects) and numeric comparisons can occasionally fail; it's good +for string literal version checks and bad for comparing to a variable +that hasn't been sanity-checked. + +The C<$OLD_PERL_VERSION> form was added in Perl v5.20.0 for historical +reasons but its use is discouraged. (If your reason to use C<$]> is to +run code on old perls then referring to it as C<$OLD_PERL_VERSION> would +be self-defeating.) + +Mnemonic: Is this version of perl in the right bracket? + =item $SYSTEM_FD_MAX =item $^F @@ -462,11 +494,13 @@ The array C<@INC> contains the list of places that the C, 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. ("." 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: +F. +Prior to Perl 5.26, C<.> -which represents the current directory, was included +in C<@INC>; it has been removed. This change in behavior is documented +in L|perlrun/PERL_USE_UNSAFE_INC> and it is +not recommended that C<.> be re-added to C<@INC>. +If you need to modify C<@INC> at runtime, you should use the C pragma +to get the machine-dependent library properly loaded as well: use lib '/mypath/libdir/'; use SomeMod; @@ -501,6 +535,19 @@ inplace editing. Mnemonic: value of B<-i> switch. +=item @ISA +X<@ISA> + +Each package contains a special array called C<@ISA> which contains a list +of that class's parent classes, if any. This array is simply a list of +scalars, each of which is a string that corresponds to a package name. The +array is examined when Perl does method resolution, which is covered in +L. + +To load packages while adding them to C<@ISA>, see the L pragma. The +discouraged L pragma does this as well, but should not be used except +when compatibility with the discouraged L pragma is required. + =item $^M X<$^M> @@ -607,13 +654,12 @@ 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 C. Do not use this to rewrite a pending -exception 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. +The C<$SIG{__DIE__}> hook is called even inside an C. It was +never intended to happen this way, but an implementation glitch made +this possible. This used to be deprecated, as it allowed strange action +at a distance like rewriting a pending exception in C<$@>. Plans to +rectify this have been scrapped, as users found that rewriting a +pending exception is actually a useful feature, and not a bug. C<__DIE__>/C<__WARN__> handlers are very special in one respect: they may be called to report (probable) errors found by the parser. In such @@ -656,30 +702,36 @@ and B<-C> filetests are based on this value. X<$^V> X<$PERL_VERSION> The revision, version, and subversion of the Perl interpreter, -represented as a C object. +represented as a L object. This variable first appeared in perl v5.6.0; earlier versions of perl will see an undefined value. Before perl v5.10.0 C<$^V> was represented -as a v-string. +as a v-string rather than a L object. C<$^V> can be used to determine whether the Perl interpreter executing a script is in the right range of versions. For example: warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 -To convert C<$^V> into its string representation use C's -C<"%vd"> conversion: +While version objects overload stringification, to portably convert +C<$^V> into its string representation, use C's C<"%vd"> +conversion, which works for both v-strings or version objects: 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. +See also C> for a decimal representation of the Perl version. -This variable was added in Perl v5.6.0. +The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or +later, it overloads operators, allowing easy comparison against other +version representations (e.g. decimal, literal v-string, "v1.2.3", or +objects). The disadvantage is that prior to v5.10.0, it was only a +literal v-string, which can't be easily printed or compared, whereas +the behavior of C<$]> is unchanged on all versions of Perl. -Mnemonic: use ^V for Version Control. +Mnemonic: use ^V for a version object. =item ${^WIN32_SLOPPY_STAT} X<${^WIN32_SLOPPY_STAT}> X X @@ -816,9 +868,9 @@ this: $str =~ /pattern/; - print $`, $&, $'; # bad: perfomance hit + print $`, $&, $'; # bad: performance hit - print # good: no perfomance hit + print # good: no performance hit substr($str, 0, $-[0]), substr($str, $-[0], $+[0]-$-[0]), substr($str, $+[0]); @@ -850,16 +902,44 @@ find uses of these problematic match variables in your code. =over 8 =item $> ($1, $2, ...) -X<$1> X<$2> X<$3> +X<$1> X<$2> X<$3> X<$I> Contains the subpattern from the corresponding set of capturing parentheses from the last successful pattern match, not counting patterns matched in nested blocks that have been exited already. +Note there is a distinction between a capture buffer which matches +the empty string a capture buffer which is optional. Eg, C<(x?)> and +C<(x)?> The latter may be undef, the former not. + These variables are read-only and dynamically-scoped. Mnemonic: like \digits. +=item @{^CAPTURE} +X<@{^CAPTURE}> X<@^CAPTURE> + +An array which exposes the contents of the capture buffers, if any, of +the last successful pattern match, not counting patterns matched +in nested blocks that have been exited already. + +Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index +is equivalent to $2, etc. + + if ("foal"=~/(.)(.)(.)(.)/) { + print join "-", @{^CAPTURE}; + } + +should output "f-o-a-l". + +See also L<<< /$> ($1, $2, ...) >>>, L and +L. + +Note that unlike most other regex magic variables there is no single +letter equivalent to C<@{^CAPTURE}>. + +This variable was added in 5.25.7 + =item $MATCH =item $& @@ -968,7 +1048,10 @@ This variable is read-only and dynamically-scoped. =item $+ X<$+> X<$LAST_PAREN_MATCH> -The text matched by the last bracket of the last successful search pattern. +The text matched by the highest used capture group of the last +successful search pattern. It is logically equivalent to the highest +numbered capture variable (C<$1>, C<$2>, ...) which has a defined value. + This is useful if you don't know which one of a set of alternative patterns matched. For example: @@ -985,7 +1068,15 @@ X<$^N> X<$LAST_SUBMATCH_RESULT> 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. +pattern. This is subtly different from C<$+>. For example in + + "ab" =~ /^((.)(.))$/ + +we have + + $1,$^N have the value "ab" + $2 has the value "a" + $3,$+ have the value "b" This is primarily used inside C<(?{...})> blocks for examining text recently matched. For example, to effectively capture text to a variable @@ -1018,10 +1109,12 @@ examples given for the C<@-> variable. This variable was added in Perl v5.6.0. +=item %{^CAPTURE} + =item %LAST_PAREN_MATCH =item %+ -X<%+> X<%LAST_PAREN_MATCH> +X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}> Similar to C<@+>, the C<%+> hash allows access to the named capture buffers, should they exist, in the last successful match in the @@ -1034,6 +1127,9 @@ For example, C<$+{foo}> is equivalent to C<$1> after the following match: The keys of the C<%+> hash list only the names of buffers that have captured (and that are thus associated to defined values). +If multiple distinct capture groups have the same name, then +C<$+{NAME}> will refer to the leftmost defined group in the match. + The underlying behaviour of C<%+> is provided by the L module. @@ -1043,7 +1139,8 @@ iterative access to them via C may have unpredictable results. Likewise, if the last successful match changes, then the results may be surprising. -This variable was added in Perl v5.10.0. +This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was +added in 5.25.7. This variable is read-only and dynamically-scoped. @@ -1053,7 +1150,7 @@ This variable is read-only and dynamically-scoped. X<@-> X<@LAST_MATCH_START> C<$-[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 +C<$-[I]> is the offset of the start of the substring matched by I-th subpattern, or undef if the subpattern did not match. Thus, after a match against C<$_>, C<$&> coincides with C: This variable was added in Perl v5.6.0. -=item %LAST_MATCH_START +=item %{^CAPTURE_ALL} +X<%{^CAPTURE_ALL}> =item %- -X<%-> X<%LAST_MATCH_START> +X<%-> Similar to C<%+>, this variable allows access to the named capture groups in the last successful match in the currently active dynamic scope. To @@ -1137,7 +1235,8 @@ iterative access to them via C may have unpredictable results. Likewise, if the last successful match changes, then the results may be surprising. -This variable was added in Perl v5.10.0. +This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was +added in 5.25.7. This variable is read-only and dynamically-scoped. @@ -1151,6 +1250,17 @@ regular expression assertion (see L). May be written to. This variable was added in Perl 5.005. +=item ${^RE_COMPILE_RECURSION_LIMIT} +X<${^RE_COMPILE_RECURSION_LIMIT}> + +The current value giving the maximum number of open but unclosed +parenthetical groups there may be at any point during a regular +expression compilation. The default is currently 1000 nested groups. +You may adjust it depending on your needs and the amount of memory +available. + +This variable was added in Perl v5.30.0. + =item ${^RE_DEBUG_FLAGS} X<${^RE_DEBUG_FLAGS}> @@ -1390,6 +1500,44 @@ the next paragraph, even if it's a newline. Remember: the value of C<$/> is a string, not a regex. B has to be better for something. :-) +Setting C<$/> to an empty string -- the so-called I -- merits +special attention. When C<$/> is set to C<""> and the entire file is read in +with that setting, any sequence of consecutive newlines C<"\n\n"> at the +beginning of the file is discarded. With the exception of the final record in +the file, each sequence of characters ending in two or more newlines is +treated as one record and is read in to end in exactly two newlines. If the +last record in the file ends in zero or one consecutive newlines, that record +is read in with that number of newlines. If the last record ends in two or +more consecutive newlines, it is read in with two newlines like all preceding +records. + +Suppose we wrote the following string to a file: + + my $string = "\n\n\n"; + $string .= "alpha beta\ngamma delta\n\n\n"; + $string .= "epsilon zeta eta\n\n"; + $string .= "theta\n"; + + my $file = 'simple_file.txt'; + open my $OUT, '>', $file or die; + print $OUT $string; + close $OUT or die; + +Now we read that file in paragraph mode: + + local $/ = ""; # paragraph mode + open my $IN, '<', $file or die; + my @records = <$IN>; + close $IN or die; + +C<@records> will consist of these 3 strings: + + ( + "alpha beta\ngamma delta\n\n", + "epsilon zeta eta\n\n", + "theta\n", + ) + Setting C<$/> to a reference to an integer, scalar containing an integer, or scalar that's convertible to an integer will attempt to read records instead of lines, with the maximum record size being the @@ -1625,12 +1773,12 @@ Under a few operating systems, C<$^E> may contain a more verbose error indicator, such as in this case, "CDROM tray not closed." Systems that do not support extended error messages leave C<$^E> the same as C<$!>. -Finally, C<$?> may be set to non-0 value if the external program +Finally, C<$?> may be set to a non-0 value if the external program F fails. The upper eight bits reflect specific error conditions encountered by the program (the program's C value). The lower eight bits reflect mode of failure, like signal death and core dump information. See L for details. In contrast to -C<$!> and C<$^E>, which are set only if error condition is detected, +C<$!> and C<$^E>, which are set only if an error condition is detected, the variable C<$?> is set on each C or pipe C, overwriting the old value. This is more like C<$@>, which on every C is always set on failure and cleared on success. @@ -1660,7 +1808,7 @@ This variable was added in Perl v5.10.0. 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 (and +moment, this differs from C> under only VMS, OS/2, and Win32 (and for MacPerl). On all other platforms, C<$^E> is always just the same as C<$!>. @@ -1678,7 +1826,7 @@ from within the Win32 API. Most Win32-specific code will report errors via C<$^E>. ANSI C and Unix-like calls set C and so most portable Perl code will report errors via C<$!>. -Caveats mentioned in the description of C<$!> generally apply to +Caveats mentioned in the description of C> generally apply to C<$^E>, also. This variable was added in Perl 5.003. @@ -1765,10 +1913,6 @@ It can be used immediately before invoking the C operator, to set the exit value, or to inspect the system error string corresponding to error I, or to restore C<$!> to a meaningful state. -Note that when stringified, the text is always returned as if both -S|perllocale>> and S|bytes>> are in -effect. This is likely to change in v5.22. - Mnemonic: What just went bang? =item %OS_ERROR @@ -1782,10 +1926,12 @@ 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 L. +systems give that exact error, and certainly not all languages). The +specific true value is not guaranteed, but in the past has generally +been the numeric value of C<$!>. 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 +L. This variable was added in Perl 5.005. @@ -1827,17 +1973,18 @@ Mnemonic: similar to B and B. =item $@ X<$@> X<$EVAL_ERROR> -The Perl syntax error message from the -last C operator. If C<$@> is -the null string, the last C parsed and executed correctly -(although the operations you invoked may have failed in the normal -fashion). +The Perl error from the last C operator, i.e. the last exception that +was caught. For C, this is either a runtime error message or the +string or reference C was called with. The C form also +catches syntax errors and other compile time exceptions. + +If no error occurs, C sets C<$@> to the empty string. Warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting C<$SIG{__WARN__}> as described in L. -Mnemonic: Where was the syntax error "at"? +Mnemonic: Where was the error "at"? =back @@ -1866,20 +2013,42 @@ This variable was added in Perl v5.6.0. X<$^D> X<$DEBUGGING> The current value of the debugging flags. May be read or set. Like its -command-line equivalent, you can use numeric or symbolic values, eg -C<$^D = 10> or C<$^D = "st">. +LI>, you can use numeric +or symbolic values, e.g. C<$^D = 10> or C<$^D = "st">. See +LI>. The contents of this variable also affects the +debugger operation. See L. Mnemonic: value of B<-D> switch. =item ${^ENCODING} X<${^ENCODING}> -The I to the C 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. +This variable is no longer supported. + +It used to hold the I to the C object that was +used to convert the source code to Unicode. + +Its purpose was to allow your non-ASCII Perl +scripts not to have to be written in UTF-8; this was +useful before editors that worked on UTF-8 encoded text were common, but +that was long ago. It caused problems, such as affecting the operation +of other modules that weren't expecting it, causing general mayhem. + +If you need something like this functionality, it is recommended that use +you a simple source filter, such as L. + +If you are coming here because code of yours is being adversely affected +by someone's use of this variable, you can usually work around it by +doing this: -This variable was added in Perl 5.8.2. + local ${^ENCODING}; + +near the beginning of the functions that are getting broken. This +undefines the variable during the scope of execution of the including +function. + +This variable was added in Perl 5.8.2 and removed in 5.26.0. +Setting it to anything other than C was made fatal in Perl 5.28.0. =item ${^GLOBAL_PHASE} X<${^GLOBAL_PHASE}> @@ -2042,7 +2211,9 @@ X<%^H> The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it useful for implementation of lexically scoped pragmas. See -L. +L. All the entries are stringified when accessed at +runtime, so only simple values can be accommodated. This means no +pointers to objects, for example. When putting items into C<%^H>, in order to avoid conflicting with other users of the hash there is a convention regarding which keys to use. @@ -2143,6 +2314,21 @@ This variable is read-only. This variable was added in Perl v5.8.0. +=item ${^SAFE_LOCALES} +X<${^SAFE_LOCALES}> + +Reflects if safe locale operations are available to this perl (when the +value is 1) or not (the value is 0). This variable is always 1 if the +perl has been compiled without threads. It is also 1 if this perl is +using thread-safe locale operations. Note that an individual thread may +choose to use the global locale (generally unsafe) by calling +L. This variable currently is still +set to 1 in such threads. + +This variable is read-only. + +This variable was added in Perl v5.28.0. + =item ${^UNICODE} X<${^UNICODE}> @@ -2236,37 +2422,16 @@ scopes in the same file, unlike other compile-time directives (such as L). Using local() on it would bind its value strictly to a lexical block. Now it is always lexically scoped. -As of Perl v5.16.0, it is implemented by the L module. See -L for more details on its behaviour. +As of Perl v5.16.0, it is implemented by the L module. -Under C, or C, C<$[> no longer has any -effect, and always contains 0. Assigning 0 to it is permitted, but any -other value will produce an error. +As of Perl v5.30.0, or under C, or C, +C<$[> no longer has any effect, and always contains 0. +Assigning 0 to it is permitted, but any other value will produce an error. Mnemonic: [ begins subscripts. Deprecated in Perl v5.12.0. -=item $] -X<$]> - -See L for a more modern representation of the Perl version that allows -accurate string comparisons. - -The version + patchlevel / 1000 of the Perl interpreter. This variable -can be used to determine whether the Perl interpreter executing a -script is in the right range of versions: - - warn "No PerlIO!\n" if $] lt '5.008'; - -The floating point representation can sometimes lead to inaccurate -numeric comparisons, so string comparisons are recommended. - -See also the documentation of C and C -for a convenient way to fail if the running Perl interpreter is too old. - -Mnemonic: Is this version of perl in the right bracket? - =back =cut