SYNOPSIS

        package Foo; 
    
        use Moose;
        use MooseX::Attribute::Localize;
    
        has 'bar' => (
            traits => [ 'Localize' ],
            is => 'rw',
            handles => {
                set_local_bar => 'localize'
            },
        );
    
        my $foo = Foo->new( bar => 'a' );
    
        print $foo->bar;  # 'a'
    
        { 
            my $sentinel = $foo->set_local_bar( 'b' );
            print $foo->bar;  # 'b'
    
            $foo->bar('c');
            print $foo->bar;  # 'c'
        }
    
        print $foo->bar;  # 'a'

DESCRIPTION

    Attributes that are given the trait Localize can handle a localize
    delegation, which stashes away the current value of the attribute and
    replaces it with a local value, mimicking the behavior of Perl's own
    local.

    The delegated method returns a sentinel variable. Once this variable
    gets out of scope, the attribute returns to its previous value.

    If the delegated method is called in a void context, a warning will be
    issued as the sentinel will immediately get out of scope, which turns
    the whole thing into a glorious no-op.

PROVIDED DELEGATION METHODS

 localize( $new_value )

    Localizes the attribute. If a $new_value is provided, initializes the
    newly localized value to it.

    The method returns a sentinel object that will return the attribute to
    its previous value once it gets out of scope. The method will warn if
    it is called in a void context (as the sentinel will immediately falls
    out of scope).

 localize_stack

    Returns the stack of values for the attribute, including the current
    value.

        {
            package Foo;
    
            use Moose;
            use MooseX::Attribute::Localize;
    
            has bar => (
                traits => [ 'Localize' ],
                is => 'rw',
                handles => {
                    local_bar => 'localize',
                    bar_stack => 'localize_stack',
                },
            );
        }
    
        my $foo = Foo->new( bar => 'a' );
        
        {
            my $s = $foo->local_bar('b');
            my @stack = $self->bar_stack;  # ( 'a', 'b' )
        }

ATTRIBUTE ARGUMENTS

        has bar => (
                traits => [ 'Localize' ],
                is => 'rw',
                localize_push => 'spy_on_push',
                localize_pop  => sub { 
                    my( $object, $new, $old, $attribute ) = @_;
                    ...;
                },
                handles => {
                    local_bar => 'localize',
                    bar_stack => 'localize_stack',
                },
        );
    
        sub spy_on_push {
            my( $self, $new, $old, $attribute ) = @_;
            ...;
        }

 localize_push

    If defined, will be called when a new value is pushed unto the
    attribute's stack. Can be the name of a method of the parent object, or
    a coderef.

    When called, the associated function/method will be passed the object,
    the new pushed value, the previous one, and the attribute object.

 localize_pop

    If defined, will be called when a new value is popped from the
    attribute's stack. Can be the name of a method of the parent object, or
    a coderef.

    When called, the associated function/method will be passed the object,
    the new popped value, the previous one, and the attribute object.

