NAME

MooseX::TrackDirty::Attributes::Trait::Attribute - Track dirtied attributes

VERSION

version 0.90

SYNOPSIS

use Moose;
use MooseX::TrackDirty::Attributes;

# one_is_dirty() is generated w/lazy_build
has one => (is => 'rw', lazy_build => 1);

# dirtyness "accessor" is generated as two_isnt_clean()
has two => (is => 'rw', default => 'foo', dirty => 'two_isnt_clean');

# we do not track three's cleanliness
has three => (is => 'rw', default => 'foo', track_dirty => 0);

# ...etc

DESCRIPTION

MooseX::TrackDirty::Attributes does the necessary metaclass fiddling to track if attributes are dirty; that is, if they're set to some value not from a builder, default, or construction. An attribute can be returned to a clean state by invoking its clearer.

WARNING!

This module should be considered alpha at the moment. I'm still trying to figure out the best way to do this -- in particular, tracking attribute status with a hardcoded base class role feels, well, dirty... It seems like I should be able to use MooseX::Role::Parameterized to make this a touch more flexible.

I'll try to preserve this modules behaviour, but no promises at the moment.

CAVEAT

Note that this is fairly crude; with few exceptions we can only track dirtiness at the very first level. That is, if you have an attribute that is a HashRef, we can tell that the _attribute_ is dirty iff the actual HashRef ref changes, but not if the HashRef's keys/values change. e.g. $self->hashref({ new => 'hash' }) would render the 'hashref' attribute dirty, but $self->hashref->{foo} = 'bar' would not.

CAVEAT TO THE CAVEAT

Some attributes are designed to be used at this level; namely those that employ an attribute helper trait to interface with the lower-level bits directly. Support for tracking dirtiness at that level is in the works; right now Array and Hash trait helpers are tracked.

ATTRIBUTE OPTIONS

We install an attribute metaclass trait that provides three additional atttribute options, as well as wraps the generated clearer and writer/accessor methods of the attribute. By default, use'ing this module causes this trait to be installed for all attributes defined in the package.

track_dirty => (0|1)

If true (the default), we track this attrbutes dirtiness and wrap any generated clearer, setter or accessor methods.

dirty => Str

If set, create a "dirtiness accessor". Default is to not create one. If lazy_build is specified, a method is generated with "foo_is_dirty", where foo is the attribute name.

track_attribute_helpers_dirty => (0|1)

If true (the default), we also track any "writing" attribute helper methods installed by the native attribute traits. (e.g. Hash, Array, etc.)

Note that this goes deeper than general "dirtiness" tracking. w/o tracking attribute helpers, we only mark an attribute as dirty when a setter or accessor (used as a setter) is invoked.

AUTHOR

Chris Weyl <cweyl@alumni.drew.edu>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Chris Weyl.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999