=begin pod

=TITLE class Variable

=SUBTITLE Object representation of a variable for use in traits

    class Variable { ... }

Variables have a wealth of compile-time information, but at run time, accesses
to a variable usually act on the value stored inside the variable, not the
variable itself.

Class C<Variable> holds the compile-time information that traits can use to
introspect and manipulate variables.

=head1 Routines

=head2 method name

    method name(Variable:D: str)

Returns the name of the variable, including the sigil.

=head2 trait is default

    multi sub trait_mod:<is>(Variable:D, :$default!)

Sets the default value with which a variable is initialized, and to which it
is reset when Nil is assigned to it. Trait arguments are evaluated at compile
time. Closures won't do what you expect. They are stored as is and need to be
called by hand.

    my Int $x is default(42);
    say $x;     # 42
    $x = 5;
    say $x;     # 5
    # explicit reset:
    $x = Nil;
    say $x;     # 42

=head2 trait is dynamic

    multi sub trait_mod:<is>(Variable:D, :$dynamic)

Marks a variable as dynamic, that is, accessible from inner dynamic scopes
without being in an inner lexical scope.

=begin code :allow<B L>
    sub introspect() {
        say B<$CALLER::x>;
    }
    my $x B<is dynamic> = 23;
    introspect;         # 23
    {
        # not dynamic
        my $x;
        introspect()    # dies with an exception of L<type X::Caller::NotDynamic|/type/X::CallerNotDynamic>
    }
=end code

=end pod
