=begin pod

=head1 perlvar - list of known magical variables

=head2 Often-Used Variables

# TODO: find a better heading

There are three special variables that are available in every block:

=begin table

    Variable    Meaning

    $_          topic variable
    $/          regex match
    $!          exceptions

=end table

=head3 $_

C<$_> is the topic variable. It is the default parameter for blocks that do
not have an explicit signature, so constructs like C<for @array { ... }>
and C<given $var { ... }> binds to C<$_> simply by invoking the block.

    for <a b c> { say $_ }  # sets $_ to 'a', 'b' and 'c' in turn
    say $_ for <a b c>;     # same, even though it's not a block
    given 'a'   { say $_ }  # sets $_ to 'a'
    say $_ given 'a';       # same, even though it's not a block

C<CATCH> blocks set C<$_> to the exception that was caught. The C<~~>
smart-match operator sets C<$_> on the right-hand side expression to the
value of the left-hand side.

Calling a method on C<$_> can be shortened by leaving off the variable name:

    .say;                   # same as $_.say

C<m/regex/> and C</regex/> regex matches and C<s/regex/subst/> substitutions
work on C<$_>.

=head3 $/

C<$/> is the match variable. It stores the result of each regex match, and
usually contains objects of type L<Match>.

    'abc 12' ~~ /\w+/;  # sets $/ to a Match object
    say $/.Str;         # abc

The C<Grammar.parse> method also sets the caller's C<$/> to the resulting
L<Match> object.

Other match variables are aliases to elements of C<$/>:

    $0          # same as $/[0]
    $1          # same as $/[1]
    $<named>    # same as $/<named>

=head3 $!

C<$!> is the error variable. If a C<try> block or statement prefix catches
an exception, that exception is stored in C<$!>. If no exception was caught,
C<$!> is set to the C<Any> type object.

Note that C<CATCH> blocks I<do not> set C<$!>. Rather they set C<$_> inside
the block to the caught exception.

=head2 Compile-time "constants"

    $?FILE      Which file am I in?
    $?LINE      Which line am I at?
    &?ROUTINE   Which routine am I in?
    &?BLOCK     Which block am I in?
    %?LANG      What is the current set of interwoven languages?

Other compile-time constants:

    $?KERNEL    Which kernel am I compiled for?
    $?DISTRO    Which OS distribution am I compiling under
    $?VM        Which virtual machine am I compiling under
    $?XVM       Which virtual machine am I cross-compiling for
    $?PERL      Which Perl am I compiled for?
    $?SCOPE     Which lexical scope am I in?
    $?PACKAGE   Which package am I in?
    $?MODULE    Which module am I in?
    $?CLASS     Which class am I in? (as variable)
    $?ROLE      Which role am I in? (as variable)
    $?GRAMMAR   Which grammar am I in?
    $?TABSTOP   ???
    $?USAGE
    $?ENC

=head2 Dynamic variables

    $*ARGFILES  Magic command-line input handle
    @*ARGS      Arguments from the command line
    $*IN        Standard input filehandle
    $*OUT       Standard output filehandle
    $*ERR       Standard error filehandle
    $*TZ
    $*FATAL
    $*CWD
    
=end pod
