/ 
MooseX-TrackDirty-Attributes-0.02
River stage zero No dependents
/ MooseX::TrackDirty::Attributes

NAME

MooseX::TrackDirty::Attributes - Track dirtied attributes

VERSION

Version 0.02

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

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.

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.

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 at alumni.drew.edu>

BUGS

Please report any bugs or feature requests to bug-moosex-trackdirty-attributes at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-TrackDirty::Attributes. I will be notified, and then you'llautomatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc MooseX::TrackDirty::Attributes

You can also look for information at:

COPYRIGHT & LICENSE

Copyright (c) 2009, Chris Weyl <cweyl@alumni.drew.edu>.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS OR A PARTICULAR PURPOSE.

See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the

Free Software Foundation, Inc., 
59 Temple Place, Suite 330, 
Boston, MA  02111-1307 USA