This page was generated by Text::SmartLinks v0.01 at 2014-11-23 20:01:06 GMT.
(syn 9f20af7)
  [ Index of Synopses ]

TITLE

 [DRAFT] Synopsis 28 - Special Names [DRAFT]

VERSION

    Created: 23 Feb 2009, created by Tim Nelson from miscellaneous documents lying around
    Last Modified: 8 September 2014
    Version: 13

Special Variables

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.

Overview

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 $?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, $?LINE is different on every line of the program.

The $*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 $*foo notation. Most of the standard globals listed below actually live either in the PROCESS or the GLOBAL package, where PROCESS contains globals belonging to the entire process, while GLOBAL 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 PROCESS 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 PROCESS or GLOBAL package may give a false negative.

The $=foo variables are related to the $?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.

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   Str          # current class (as package or type name)
 $?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                # (or some such)
 $*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
 $*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 $*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, $PROCESS::OUT is the stdout for the entire process, but each interpreter can set its own $GLOBAL::OUT to make $*OUT mean whatever it wants independently of other interpreters. Any dynamic scope may also declare a local meaning of $*OUT that applies only to called code. Likewise each thread could log its own errors to its own $*ERR, since a thread is a dynamic scope.

The Systemic role collects a few common features of some of the special variables such as $*PERL, $?VM, $*KERNEL, etc. It in turn relies on the Universal 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
        ...
    }

Perl5 to Perl6 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               -              Just params to anonymous block
 -                   $/             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<S04>)
 $! $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 (plus stringification)
 $^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

SPECIAL VARIABLES MORE IN DEPTH

$?KERNEL / $*KERNEL

Contains a Kernel class instance that does Systemic. It further provides the following methods:

release

The release information of this kernel.

arch

Processor architecture.

bits

Number of bits used by architecture (typically 32 or 64 bits).

hardware

The processor hardware, if known.

signals

An Array of Signals that are supported by this Kernel, in which the ordinal number matches the lower level signal value.

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 Signal Enum value, or a string representing that signal, to the internal value that this Kernel uses to send to a process.

$?DISTRO / $*DISTRO

Contains a Distro class instance that does Systemic. It further provides the following methods:

release

The release information of this distribution.

is-win

True if this is a Windows-like distribution.

path-sep

The character that is used to separating paths in specifications, usually in environment variables such as PATH.

$?VM / $*VM

Contains a VM class instance that does Systemic. It further provides the following methods:

config

The configuration hash that was used to build the virtual machine.

precomp-ext

The extension used by pre-compiled module files.

precomp-target

The name of the compilation stage to produce pre-compiled module files (typically used as "--target=xxx").

$?PERL / $*PERL

Contains a Perl class instance that does Systemic. It further provides the following methods:

VMnames

A list of $?VM.name / $*VM.name values known.

DISTROnames

A list of $?DISTRO.name / $*DISTRO.name values known to have been seen with the current $?VM.name / $*VM.name.

compiler

Contains a Compiler class instance that does Systemic. It further provides the following methods:

release

The release information of this version of Perl.

build-date

The DateTime this version of Perl was built.

codename

The codename of this version of Perl.

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).

Form.pm

These go in the Perl5 to Perl6 conversion table:

 Perl6   Perl5
 -----   -----------------------------------------
 -       $%  $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

S15-unicode.pod

${^ENCODING} variable -- S32/Str.pod implies this is $?ENC $?NF -- unicode normalisation form ${^UNICODE} variable

Infectious trait spec

${^TAINT} variable, which is pending, among other things, infectious trait spec

AUTHORS

    Larry Wall <larry@wall.org>
    Tim Nelson <wayland@wayland.id.au>
    Lyle Hopkins <webmaster@cosmicperl.com>
    Carl Mäsak <cmasak@gmail.com>
[ Top ]   [ Index of Synopses ]