# NAME

MooseX::Attribute::Localize - localize attribute values within a scope

# VERSION

version 0.1.1

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

# AUTHOR

Yanick Champoux <yanick@cpan.org> [![endorse](http://api.coderwall.com/yanick/endorsecount.png)](http://coderwall.com/yanick)

# COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Yanick Champoux.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
