=encoding utf8 =head1 TITLE [DRAFT] Synopsis 28 - Special Names [DRAFT] =head1 VERSION Created: 23 Feb 2009, created by Tim Nelson from miscellaneous documents lying around Last Modified: 8 September 2014 Version: 13 =head1 Special Variables =head2 Introduction This document serves as a collection point for what is known about special variables in Perl 6 and correlates them with the changes from Perl 5. If you are trying to find the Perl 6 equivalent of a Perl 5 special variable you know, try searching this file for the Perl 5 version. Each main entry is followed by a note containing the corresponding Perl 5 variable(s). The list of main entries is also followed by a table showing the 5 and 6 variables side-by-side. =head2 Overview =head3 Secondary Sigils (also known as "twigils") A quick reminder of the relevant twigils from S02: $?foo # Compiler constants (fixed at compile time) $*foo # Context variable, default global (run time) $=foo # File-scoped Pod data The various C<$?foo> variables are determined at compile time, and are not modifiable at run time. This does not mean that the variable has the same value everywhere; for instance, C<$?LINE> is different on every line of the program. The C<$*foo> variables function both as dynamically scoped variables and as globals. Globalness is relative, in other words. Any dynamic scope may modify the set of globals visible via the C<$*foo> notation. Most of the standard globals listed below actually live either in the C or the C package, where C contains globals belonging to the entire process, while C contains the globals belonging to the current interpreter, since a process may be running more than one interpreter. Unless otherwise indicated below, the outermost definition of these variables are kept in the C package. Please note that an implementation may decide to populate these variables lazily on the first access to <$*foo>. So checking for existence of these variables in the C or C package may give a false negative. The C<$=foo> variables are related to the C<$?foo> variables insofar as the text of the program is known at compile time, so the values are static. However, the different twigil indicates that the variable contains Pod data, which is primarily under user control rather than compiler control. The structure of these variables will be fleshed out in S26. =head3 Named variables Variable Spec Type Description -------- ---- ---- ----------- @_ # ??? (FIX) $! S04 # Current Exception object $/ S05 Match # Last match $0, $1, $2 S05 Str # First captured value from match: $/[0] @*ARGS S06 Array of Str # command-line arguments $*ARGFILES S02 IO::Handle # The magic command-line input handle &?BLOCK S06 Block # current block (itself) ::?CLASS S12 Class # current class $?CLASS S02 Class # current class @=COMMENT (S26) # All the comment blocks in the file %?CONFIG Hash of XXX # configuration hash XXX What does this do? $*CWD S16 IO::Path # current working directory $=data (S26) IO # data block handle (=begin data ... =end) %?DEEPMAGIC S13 Hash of XXX # Controls the mappings of magical names to sub definitions $?DISTRO S02 Systemic # Which OS distribution am I compiling under $*DISTRO S02 Systemic # Which OS distribution am I running under $*EGROUP +Int,~Str # effective $*GROUP %*ENV S02 Hash of Str # system environment variables $*ERR S16 IO::Handle # Standard error handle $*EUSER +Int,~Str # effective $*USER $?COMPILER IO::Path # location of the compiler executable $*SHEBANG IO::Path # location of the interpreter executable (usually eqv $?COMPILER) $?FILE S02 Str # current filename of source file $?GRAMMAR S02 Grammar # current grammar $*GROUP +Int,~Str # group id (numeric) or name (string) $*IN S16 IO::Handle # Standard input handle; is an IO object @?INC S11 # where to search for user modules (but not std lib!) %?LANG S02 Hash of Grammar # What is the current set of interwoven languages? $*LANG S02 Str # LANG variable from %*ENV that defines what human language is used $?LINE S02 Int # current line number in source file %*META-ARGS S19 Hash of XXX # Meta-arguments $?MODULE S02 Module # current module %*OPTS S19 Hash of XXX # Options from command line %*OPT... S19 Hash of XXX # Options from command line to be passed down $?KERNEL Systemic # operating system compiled for $*KERNEL Systemic # operating system running under $*OUT S16 IO::Handle # Standard output handle $?PACKAGE S02 Package # current package $?PERL S02 Systemic # Which Perl am I compiled for? $*PERL S02 Systemic # perl version running under $*PID Int # system process id $=pod S02 # POD6 data $*PROGRAM S19 IO::Path # location of the Perl program being executed %*PROTOCOLS S16 Hash of Method # Stores the methods needed for the uri() function ::?ROLE Str # current role (as package or type name) $?ROLE S02 Role # current role &?ROUTINE S06 Routine # current sub or method (itself) $?SCOPE S02 # Current "my" scope (XXX unnecessary?) $*TMPDIR S16 IO::Path # system temporary directory $*TZ S32 # Local time zone $?USAGE S06 Str # Default usage message generated at compile time (EDIT: was renamed to $*USAGE) $*USER +Int,~Str # user id (numeric) or name (string) $?VM S02 Systemic # Which virtual machine am I compiling under $?XVM S02 Systemic # Which virtual machine am I cross-compiling for Note that dynamic variables such as C<$*OUT> may have more than one current definition in the outer dynamic context, in which case the innermost dynamic scope in which it is defined determines the meaning. For instance, C<$PROCESS::OUT> is the stdout for the entire process, but each interpreter can set its own C<$GLOBAL::OUT> to make C<$*OUT> mean whatever it wants independently of other interpreters. Any dynamic scope may also declare a local meaning of C<$*OUT> that applies only to called code. Likewise each thread could log its own errors to its own C<$*ERR>, since a thread is a dynamic scope. The C role collects a few common features of some of the special variables such as C<$*PERL>, C<$?VM>, C<$*KERNEL>, etc. It in turn relies on the C role that all cosmically unique entities must support in order to have a unique name. role Universal { has Str $.name; has Str $.auth; has Version $.version; has Blob $.signature; # optional? } role Systemic does Universal { has $.desc; # uname-ish version-like information goes here ... } =head3 Perl 5 to Perl 6 special variable translation If a column has a "-" in it, it means that item is unavailable in that version of Perl. Perl 5 Perl 6 Comment ----------- ----------- ----------------------- STDIN $*IN See S16; actual variable is $PROCESS::IN STDOUT $*OUT See S16; actual variable is $PROCESS::OUT STDERR $*ERR See S16; actual variable is $PROCESS::ERR $_ $ARG $_ More lexically aware $_[1],$_[2].. $^a,$^b.. $a,$b - No special meaning whatsoever - $/ Object with results of last regex match $1,$2,$3... $0,$1,$2... Match capture variables start at 0 $& $MATCH ~$/ $` $PREMATCH substr based on $/.from $' $POSTMATCH substr based on $/.to $+ - But info can now be retrieved from $/ $^N $*MOST_RECENT_CAPTURED_MATCH ...or some such. or $/[*-$n] ...or omit @- $1.from, etc @+ $1.to, etc. %! - $[ - This feature has been removed $* - Deprecated long ago $# - Deprecated long ago $^H - These were only ever internal anyway %^H - - $! Current exception (see L) $! $ERRNO $OS_ERROR - Use shiny new $! $? $CHILD_ERROR - Use shiny new $! $@ $EVAL_ERROR - Use shiny new $! $^E - Use shiny new $! $^S - $. $NR $*IN.ins() $/ $RS $*IN.input-line-separator() $| $*OUT.autoflush() $, $OFS $*OUT.output-field-separator() $\ $*OUT.output-record-separator() $" $LIST_SEPARATOR - $; $SUBSEP - $$ $PID $*PID $< $UID $*UID Real UID (User ID) $( $GID $*GID Real GID (Group ID) $> $EUID $*EUID Effective UID $) $EGID $*EGID Effective GID $0 $PROGRAM_NAME $*PROGRAM-NAME $^C $COMPILING $*COMPILING $^D $DEBUGGING $*DEBUGGING $^F $SYS_FD_MAX $*SYS_FD_MAX ...or some such $^I $INPLACE_EDIT $*INPLACE_EDIT ...or some such $^M $*EMERGENCY_MEMORY ...or some such (or omit) $^O $OSNAME $*KERNEL.name (or $*DISTRO.name or $*VM.name) $^P $PERLDB $*PERLDB ...or some such $^R $*LAST_REGEXP_CODE_RESULT ...or some such. Or omit. $^T $BASETIME $*INITTIME A Temporal::Instant object $^V $] $?PERL.version $^W $*WARNINGS (if any dynamic control needed) ${^WARNING_BITS} $?WARNINGS $^X $?COMPILER or $*SHEBANG (plus stringification) ARGV $*ARGFILES Note the P6 idiom for this handle: for lines() { # each time through loop # proc a line from files named in ARGS } @ARGV @*ARGS ARGVOUT TBD $ARGV TBD @F @_ %ENV %*ENV @INC @?INC (but not for std library modules) %INC no equivalent, encapsulated in CompUnitRepo object %SIG event filters plus exception translation $SIG{__WARN__} $*ON_WARN $SIG{__DIE__} $*ON_DIE ${^OPEN} - This was internal; forget it =head2 SPECIAL VARIABLES MORE IN DEPTH =head3 $?KERNEL / $*KERNEL Contains a C class instance that does C. It further provides the following methods: =over =item release The release information of this kernel. =item arch Processor architecture. =item bits Number of bits used by architecture (typically 32 or 64 bits). =item hardware The processor hardware, if known. =item signals An C of Cs that are supported by this C, in which the ordinal number matches the lower level signal value. =item signal my $int = $*KERNEL.signal(SIGHUP); my $int = $*KERNEL.signal("HUP"); # or "SIGHUP" my $int = $*KERNEL.signal(1); # just pass through for bare Ints Convert the given C Enum value, or a string representing that signal, to the internal value that this C uses to send to a process. =back =head3 $?DISTRO / $*DISTRO Contains a C class instance that does C. It further provides the following methods: =over =item release The release information of this distribution. =item is-win True if this is a Windows-like distribution. =item path-sep The character that is used to separating paths in specifications, usually in environment variables such as C. =back =head3 $?VM / $*VM Contains a C class instance that does C. It further provides the following methods: =over =item config The configuration hash that was used to build the virtual machine. =item precomp-ext The extension used by pre-compiled module files. =item precomp-target The name of the compilation stage to produce pre-compiled module files (typically used as "--target=xxx"). =back =head3 $?PERL / $*PERL Contains a C class instance that does C. It further provides the following methods: =over =item VMnames A list of C<$?VM.name> / C<$*VM.name> values known. =item DISTROnames A list of C<$?DISTRO.name> / C<$*DISTRO.name> values known to have been seen with the current C<$?VM.name> / C<$*VM.name>. =item compiler Contains a C class instance that does C. It further provides the following methods: =over =item release The release information of this version of Perl. =item build-date The C this version of Perl was built. =item codename The codename of this version of Perl. =back =back =head2 NOT YET DEFINED The following items are not yet defined, but will need to be defined. XXX Don't remove this line until this section is completely blank. The $?LANG and $*LANG variables are also confusing (both in S02). =head3 Form.pm These go in the Perl 5 to Perl 6 conversion table: Perl 6 Perl 5 ------ ----------------------------------------- - $% $FORMAT_PAGE_NUMBER - HANDLE->format_page_number(EXPR) - $= $FORMAT_LINES_PER_PAGE - HANDLE->format_lines_per_page(EXPR) - $- $FORMAT_LINES_LEFT - HANDLE->format_lines_left(EXPR) - $~ $FORMAT_NAME - HANDLE->format_name(EXPR) - $^ $FORMAT_TOP_NAME - HANDLE->format_top_name(EXPR) - $: $FORMAT_LINE_BREAK_CHARACTERS - IO::Handle->format_line_break_characters - $^L $FORMAT_FORMFEED - IO::Handle->format_formfeed - $^A $ACCUMULATOR =head3 S15-unicode.pod ${^ENCODING} variable -- S32/Str.pod implies this is $?ENC $?NF -- Unicode normalization form ${^UNICODE} variable =head3 Infectious trait spec ${^TAINT} variable, which is pending, among other things, infectious trait spec =head1 AUTHORS Larry Wall Tim Nelson Lyle Hopkins Carl Mäsak =for vim:set expandtab sw=4: