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

    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
