NAME
    MooseX::TrackDirty::Attributes - Track dirtied attributes

VERSION
    This document describes version 2.002 of MooseX::TrackDirty::Attributes
    - released November 24, 2012 as part of MooseX-TrackDirty-Attributes.

SYNOPSIS
        package Foo;
        use Moose;
        use MooseX::TrackDirty::Attributes;

        # tracking accessor is not automagically applied
        has foo => (is => 'rw');

        # one_is_dirty() is generated by default
        has one => (traits => [ TrackDirty ], is => 'rw');

        # dirtyness "accessor" is generated as two_isnt_clean()
        has two      => (
            traits   => [ TrackDirty ],
            is       => 'rw',
            is_dirty => 'two_isnt_clean',
        );

        # three_is_dirty() and original_value_of_three() are generated
        has three => (
            traits         => [ TrackDirty ],
            is             => 'rw',
            original_value => 'original_value_of_three',
        );

        # ...meanwhile, at the bat-cave

        package main;
        my $foo = Foo->new();

        $foo->one_is_dirty; # false

DESCRIPTION
    MooseX::TrackDirty::Attributes does the necessary metaclass fiddling to
    track if attributes are dirty; that is, if they're set to some value and
    then set again, to another value. (The setting can be done by the
    constructor, builder, default, accessor, etc.)

    An attribute can be returned to a clean state by invoking its clearer.

CAVEAT
    Note that with one (significant) 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 if and only if the
    actual 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.

    In plainer language: we can only tell if an attribute's value is dirty
    if our accessors are used to modify its values.

    The exception to this is...

IMPLICATIONS FOR NATIVE TRAITS
    We now track when a native trait accessor is used to change the contents
    of the attribute; this is considered to make the attribute value dirty.

    This is still new and experimental, so feedback is quite welcome :)

ATTRIBUTE OPTIONS
    To track a given attribute, the trait must be applied. This package
    exports a "TrackDirty" function that returns the full (ridiculously
    long) package name of the trait.

    Once applied, we have two additional options that can be passed to the
    attribute constructor (usually via 'has'):

    is_dirty => method_name
        is_dirty controls what the name of the "is this attribute's value
        dirty?" accessor is (returning true on dirty; false otherwise):

        By default, the accessor is installed as
        "{attribute_name}_is_dirty";

        If a legal method name is passed, the accessor is installed under
        that name;

        Otherwise we blow up.

    original_value => method_name
        original_value controls what the name for the original value
        accessor is installed (returns the original value if dirty, undef
        otherwise):

        By default, we do not install an original_value accessor;

        If a legal method name is passed, the accessor is installed under
        that name;

        Otherwise we blow up.

    cleaner => method_name
        cleaner controls what the name for the cleaner accessor is installed
        (marks a dirty attribute as clean without clearing):

        By default, we do not install an original_value accessor;

        If a legal method name is passed, the accessor is installed under
        that name;

        Otherwise we blow up.

SOURCE
    The development version is on github at
    <http://github.com/RsrchBoy/moosex-trackdirty-attributes> and may be
    cloned from <git://github.com/RsrchBoy/moosex-trackdirty-attributes.git>

BUGS
    Please report any bugs or feature requests on the bugtracker website
    https://github.com/RsrchBoy/moosex-trackdirty-attributes/issues

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    Chris Weyl <cweyl@alumni.drew.edu>

CONTRIBUTOR
    Gianni Ceccarelli <gianni.ceccarelli@net-a-porter.com>

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

