/ 
MooseX-OmniTrigger-0.06
River stage zero No dependents
/ MooseX::OmniTrigger

NAME

MooseX::OmniTrigger -- Provide Moose attributes with recursion-proof triggers that fire on any init, set, or clear operation.

VERSION

Version 0.06

SYNOPSIS

{ package MyClass;

    use Moose;
    use MooseX::OmniTrigger;

    has foo => (is => 'rw', isa => 'Str', default => 'FRELL',                  omnitrigger => \&_callback);
    has bar => (is => 'rw', isa => 'Str',                     lazy_build => 1, omnitrigger => \&_callback);

    has baz => (is => 'rw', isa => 'Str', omnitrigger => sub { $_[0]->baz("$_[2][0]!!!") });

    sub _callback {

        my ($self, $attr_name, $new, $old) = (shift, @_);

        warn("attribute $attr_name has been ", @$new ? 'set' : 'cleared');

        warn('   oldval: ', @$old ? $old->[0] // 'UNDEF' : 'NOVAL');
        warn('   newval: ', @$new ? $new->[0] // 'UNDEF' : 'NOVAL');
    }

    sub _build_bar { 'DREN' }
}

my $obj = MyClass->new;

# attribute 'foo' has been set
#    oldval: NOVAL
#    newval: FRELL

say $obj->bar; # DREN

# attribute 'bar' has been set
#    oldval: NOVAL
#    newval: DREN

$obj->clear_bar;

# attribute 'bar' has been cleared
#    oldval: DREN
#    newval: NOVAL

$obj->baz('YOTZ');

say $obj->baz; # YOTZ!!!

DESCRIPTION

Sometimes you want to know when your attributes' values change. No matter when! No matter how!

MooseX::OmniTrigger is an effort to provide Moose attributes with triggers that may to some folks behave more DWIMmily than standard Moose triggers, working around the documented feature/bug/caveat, "Triggers will only fire when you assign to the attribute, either in the constructor, or using the writer. Default and built values will not cause the trigger to be fired."

An omnitrigger fires any time its attribute's value is initialized, set, or cleared. This includes initialization with default and built values, lazy or no, and sets via native type accessors.

The callback is given as a subref, and receives four arguments: the object, the attribute name, the new value, and the old value. The new and old values are given as array refs. An empty array indicates *no* value -- the slot is uninitialized or has been cleared. Otherwise, the value will be the first (and only) array element.

Omnitriggers are recursion-proof. Firings beyond the first of a particular omnitrigger in the same call stack are quietly prevented.

CAVEATS

MooseX::OmniTrigger currently requires Moose 2.02. Compatibility with older Mooses is TODO.

AUTHOR

Todd Lorenz <trlorenz@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Todd Lorenz.

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