NAME

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

VERSION

version 0.1.2

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>

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.