X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a5effbbc577ce192c131f5cd79c2af95064ac714..e57270be442bfaa9dc23eebd67485e5a806b44e3:/pod/perlvar.pod diff --git a/pod/perlvar.pod b/pod/perlvar.pod index add3756..09ec06d 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 @@ -165,7 +165,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 +370,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<$;>. @@ -410,14 +410,14 @@ The hash C<%ENV> contains your current environment. Setting a value in C changes the environment for any child processes you subsequently C off. -As of 5.17.3, both keys and values stored in C<%ENV> are stringified. +As of v5.18.0, both keys and values stored in C<%ENV> are stringified. my $foo = 1; $ENV{'bar'} = \$foo; if( ref $ENV{'bar'} ) { - say "Pre 5.17.3 Behaviour"; + say "Pre 5.18.0 Behaviour"; } else { - say "Post 5.17.3 Behaviour"; + say "Post 5.18.0 Behaviour"; } Previously, only child processes received stringified values: @@ -426,11 +426,51 @@ Previously, only child processes received stringified values: $ENV{'bar'} = \$foo; # Always printed 'non ref' - system($^X,'-e',q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /); + system($^X, '-e', + q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /); 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 @@ -655,30 +695,35 @@ 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. -Mnemonic: use ^V for Version Control. +Mnemonic: use ^V for a version object. =item ${^WIN32_SLOPPY_STAT} X<${^WIN32_SLOPPY_STAT}> X X @@ -800,16 +845,51 @@ we have not made another match: $1 is Mutt; $2 is Jeff $1 is Wallace; $2 is Grommit -The C and C -modules can help you find uses of these -problematic match variables in your code. +=head3 Performance issues + +Traditionally in Perl, any use of any of the three variables C<$`>, C<$&> +or C<$'> (or their C equivalents) anywhere in the code, caused +all subsequent successful pattern matches to make a copy of the matched +string, in case the code might subsequently access one of those variables. +This imposed a considerable performance penalty across the whole program, +so generally the use of these variables has been discouraged. + +In Perl 5.6.0 the C<@-> and C<@+> dynamic arrays were introduced that +supply the indices of successful matches. So you could for example do +this: + + $str =~ /pattern/; + + print $`, $&, $'; # bad: perfomance hit + + print # good: no perfomance hit + substr($str, 0, $-[0]), + substr($str, $-[0], $+[0]-$-[0]), + substr($str, $+[0]); -Since Perl v5.10.0, you can use the C

match operator flag and the -C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead -so you only suffer the performance penalties. +In Perl 5.10.0 the C

match operator flag and the C<${^PREMATCH}>, +C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed +you to suffer the penalties only on patterns marked with C

. -If you are using Perl v5.20.0 or higher, you do not need to worry about -this, as the three naughty variables are no longer naughty. +In Perl 5.18.0 onwards, perl started noting the presence of each of the +three variables separately, and only copied that part of the string +required; so in + + $`; $&; "abcdefgh" =~ /d/ + +perl would only copy the "abcd" part of the string. That could make a big +difference in something like + + $str = 'x' x 1_000_000; + $&; # whoops + $str =~ /x/g # one char copied a million times, not a million chars + +In Perl 5.20.0 a new copy-on-write system was enabled by default, which +finally fixes all performance issues with these three variables, and makes +them safe to use anywhere. + +The C and C modules can help you +find uses of these problematic match variables in your code. =over 8 @@ -833,12 +913,8 @@ The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or C enclosed by the current BLOCK). -In Perl v5.18 and earlier, the use of this variable -anywhere in a program imposes a considerable -performance penalty on all regular expression matches. To avoid this -penalty, you can extract the same substring by using L. Starting -with Perl v5.10.0, you can use the C

match flag and the C<${^MATCH}> -variable to do the same thing for particular match operations. +See L above for the serious performance implications +of using this variable (even once) in your code. This variable is read-only and dynamically-scoped. @@ -849,6 +925,9 @@ X<${^MATCH}> This is similar to C<$&> (C<$MATCH>) except that it does not incur the performance penalty associated with that variable. + +See L above. + In Perl v5.18 and earlier, it is only guaranteed to return a defined value when the pattern was compiled or executed with the C

modifier. In Perl v5.20, the C

modifier does nothing, so @@ -867,13 +946,8 @@ The string preceding whatever was matched by the last successful pattern match, not counting any matches hidden within a BLOCK or C enclosed by the current BLOCK. -In Perl v5.18 and earlier, the use of this variable -anywhere in a program imposes a considerable -performance penalty on all regular expression matches. To avoid this -penalty, you can extract the same substring by using L. Starting -with Perl v5.10.0, you can use the C

match flag and the -C<${^PREMATCH}> variable to do the same thing for particular match -operations. +See L above for the serious performance implications +of using this variable (even once) in your code. This variable is read-only and dynamically-scoped. @@ -884,12 +958,15 @@ X<$`> X<${^PREMATCH}> This is similar to C<$`> ($PREMATCH) except that it does not incur the performance penalty associated with that variable. + +See L above. + In Perl v5.18 and earlier, it is only guaranteed to return a defined value when the pattern was compiled or executed with the C

modifier. In Perl v5.20, the C

modifier does nothing, so C<${^PREMATCH}> does the same thing as C<$PREMATCH>. -This variable was added in Perl v5.10.0 +This variable was added in Perl v5.10.0. This variable is read-only and dynamically-scoped. @@ -906,13 +983,8 @@ enclosed by the current BLOCK). Example: /def/; print "$`:$&:$'\n"; # prints abc:def:ghi -In Perl v5.18 and earlier, the use of this variable -anywhere in a program imposes a considerable -performance penalty on all regular expression matches. -To avoid this penalty, you can extract the same substring by -using L. Starting with Perl v5.10.0, you can use the C

match flag -and the C<${^POSTMATCH}> variable to do the same thing for particular -match operations. +See L above for the serious performance implications +of using this variable (even once) in your code. This variable is read-only and dynamically-scoped. @@ -923,6 +995,9 @@ X<${^POSTMATCH}> X<$'> X<$POSTMATCH> This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the performance penalty associated with that variable. + +See L above. + In Perl v5.18 and earlier, it is only guaranteed to return a defined value when the pattern was compiled or executed with the C

modifier. In Perl v5.20, the C

modifier does nothing, so @@ -1060,10 +1135,8 @@ After a match against some variable C<$var>: This variable was added in Perl v5.6.0. -=item %LAST_MATCH_START - =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 @@ -1373,7 +1446,12 @@ not reading from a record-oriented file (or your OS doesn't have record-oriented files), then you'll likely get a full chunk of data with every read. If a record is larger than the record size you've set, you'll get the record back in pieces. Trying to set the record -size to zero or less will cause reading in the (rest of the) whole file. +size to zero or less is deprecated and will cause $/ to have the value +of "undef", which will cause reading in the (rest of the) whole file. + +As of 5.19.9 setting C<$/> to any other form of reference will throw a +fatal exception. This is in preparation for supporting new ways to set +C<$/> in the future. On VMS only, record reads bypass PerlIO layers and any associated buffering, so you must not mix record and non-record reads on the @@ -1589,12 +1667,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. @@ -1742,10 +1820,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. @@ -1787,17 +1867,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 @@ -1834,10 +1915,34 @@ Mnemonic: value of B<-D> switch. =item ${^ENCODING} X<${^ENCODING}> +DEPRECATED!!! + 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. +does not have to be written in UTF-8. Default is C. + +Setting this variable to any other value than C is deprecated due +to fundamental defects in its design and implementation. It is planned +to remove it from a future Perl version. Its purpose was to allow your +non-ASCII Perl scripts to not 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 causes problems, such as affecting the operation +of other modules that aren't expecting it, causing general mayhem. Its +use can lead to segfaults. + +If you need something like this functionality, you should use the +L pragma, which is also deprecated, but has fewer nasty side +effects. + +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: + + 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. @@ -2002,7 +2107,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. @@ -2078,6 +2185,14 @@ were compiled. Save source code lines into C<@{"_<$filename"}>. +=item 0x800 + +When saving source, include evals that generate no subroutines. + +=item 0x1000 + +When saving source, include source that did not compile. + =back Some bits may be relevant at compile-time only, some at @@ -2143,10 +2258,8 @@ See L for details about error messages. =over 8 -=item $OFMT - =item $# -X<$#> X<$OFMT> +X<$#> C<$#> was a variable that could be used to format printed numbers. After a deprecation cycle, its magic was removed in Perl v5.10.0 and @@ -2172,10 +2285,8 @@ Deprecated in Perl 5. Removed in Perl v5.10.0. -=item $ARRAY_BASE - =item $[ -X<$[> X<$ARRAY_BASE> +X<$[> This variable stores the index of the first element in an array, and of the first character in a substring. The default is 0, but you could @@ -2203,28 +2314,6 @@ Mnemonic: [ begins subscripts. Deprecated in Perl v5.12.0. -=item $OLD_PERL_VERSION - -=item $] -X<$]> X<$OLD_PERL_VERSION> - -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 checksumming!\n" if $] < 3.019; - -The floating point representation can sometimes lead to inaccurate -numeric comparisons. - -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