X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/d5b4785c1592d741608f5cff697058cc284db4eb..b76dad153351f50f46ba283bb0da075b93e89838:/pod/perlvar.pod diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 61a2fdf..35351b7 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -12,31 +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 (with the literal control character -form deprecated). 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 @@ -166,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. @@ -433,6 +432,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 @@ -657,30 +695,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 @@ -1092,10 +1136,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 @@ -1626,12 +1668,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. @@ -1661,7 +1703,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<$!>. @@ -1679,7 +1721,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. @@ -1779,10 +1821,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. @@ -1824,17 +1868,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 @@ -1863,20 +1908,41 @@ 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. Setting -this variable to any other value is deprecated. +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. =item ${^GLOBAL_PHASE} X<${^GLOBAL_PHASE}> @@ -2039,7 +2105,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. @@ -2244,26 +2312,6 @@ 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