todo item: permit extended control variables a la ${^Foo} (patch

[perl5.git] / pod / perlvar.pod

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 2dafc1c..5c851d9 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1005,3 +1005,51 @@ pipe C<close>, overwriting the old value.
 
 For more details, see the individual descriptions at L<$@>, L<$!>, L<$^E>,
 and L<$?>.
+
+
+=head2 Technical Note on the Syntax of Variable Names
+
+Variable names in Perl can have several formats.  Usually, they must
+begin with a letter or underscore, in which case they can be
+arbitrarily long (up to an internal limit of 256 characters) and may
+contain letters, digits, underscores, or the special sequence C<::>.
+In this case the part before the last C<::> is taken to be a I<package
+qualifier>; see L<perlmod>. 
+
+Perl variable names may also be a sequence of digits or a single
+punctuation or control character.  These names are all reserved for
+special uses by Perl; for example, the all-digits names are used to
+hold backreferences after a regulare expression match.  Perl has a
+special syntax for the single-control-character names: It understands
+C<^X> (caret C<X>) to mean the control-C<X> character.  For example,
+the notation C<$^W> (dollar-sign caret C<W>) is the scalar variable
+whose name is the single character control-C<W>.  This is better than
+typing a literal control-C<W> into your program.
+
+Finally, new in Perl 5.006, Perl variable names may be alphanumeric
+strings that begin with control characters.  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<F>
+followed by two C<o>'s.  These variables are reserved for future
+special uses by Perl, except for the ones that begin with C<^_>
+(control-underscore).  No control-character 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<is> reserved.
+
+All Perl variables that begin with digits, control characters, or
+punctuation characters are exempt from the effects of the C<package>
+declaration and are always forced to be in package C<main>.  A few
+other names are also exempt:
+
+       ENV             STDIN
+       INC             STDOUT
+       ARGV            STDERR
+       ARGVOUT
+       SIG
+
+In particular, the new special C<${^_XYZ}> variables are always taken
+to be in package C<main> regardless of any C<package> declarations
+presently in scope.
+
+