NAME

    Class::Accessor::TrackDirty - Define simple entities stored in some
    places.

SYNOPSIS

        package UserInfo;
        use Class::Accessor::TrackDirty;
        Class::Accessor::TrackDirty->mk_new_and_tracked_accessors("name", "password");
        Class::Accessor::TrackDirty->mk_accessors("modified");
    
        package main;
        my $user = UserInfo->new({name => 'honma', password => 'F!aS3l'});
        store_into_someplace($user->to_hash) if $user->is_dirty;
        # ...
        $user = UserInfo->from_hash(restore_from_someplace());
        $user->name('hiratara');
        $user->revert; # but decided not to
        $user->name('honma');
        $user->name('hiratara');
        $user->name('honma'); # I can't make up my mind...
        # ... blabla ...
    
        # Check the status of fields if needed
        $user->is_dirty('name') and warn "Did you change name?";
        my @dirty_fields = $user->dirty_fields;
    
        # Store it only if $user was really modified.
        store_into_someplace($user->to_hash) if $user->is_dirty;

DESCRIPTION

    Class::Accessor::TrackDirty defines simple entities stored in files,
    RDBMS, KVS, and so on. It tracks dirty columns and you can store it
    only when the instance was really modified.

INTERFACE

 Functions

  Class::Accessor::TrackDirty->mk_new;

    Create the <new> methods in your class. You can pass a hash-ref or
    hash-like list to <new> method.

    my $object = YourClass->new({name1 => "value1", ...});

      The instance created by <new> is regarded as `dirty' if it has some
      nonempty fields. It's because it hasn't been stored yet.

  Class::Accessor::TrackDirty->mk_tracked_accessors("name1", "name2", ...);

    Create accessor methods and helper methods in your class. Following
    helper methods will be created automatically.

    $your_object->is_dirty; =item $your_object->is_dirty("field_name");

      Check that the instance is modified. If it's true, you should store
      this instance into some place through using <to_hash> method.

      When you pass the name of a field, you can know if the field contains
      the same value as the stored object.

    my @fields = $your_object->dirty_fields;

      Gets the name of all dirty fields of $your_object.

    $your_object->is_new;

      Checks if the instance might be in a storage. Returns false value
      when the instance comes from from_hash method, or after you call
      to_hash method.

    my $hash_ref = $your_object->to_hash;

      Eject data from this instance as plain hash-ref format.
      <$your_object> is regarded as `clean' after calling this method.

      You'd better store <$hash_ref> into some place ASAP. It's up to you
      how <$hash_ref> should be serialized.

    $your_object->raw;

      Retrieves the row data from the instance. The return value is the
      same as to_hash method, but this method doesn't change the state of
      the instance.

    my $object = YourClass->from_hash({name1 => "value1", ...});

      Rebuild the instance from a hash-ref ejected by <to_hash> method. The
      instance constructed by <from_hash> is regarded as `clean'.

    $your_object->revert;

      Revert all `dirty' changes. Fields created by <mk_tracked_accessors>
      returns to the point where you call <new>, <to_hash>, or <from_hash>.

      The volatile fields will be never reverted.

    You'd better *NOT* store references in tracked fields. Though following
    codes work well, to make revert work well, we'll have to copy
    references deeply when you call getter.

      my $your_object = YourClass->new(some_refs => {key => 'value'});
      # some_refs are copyied deeply :(
      $your_object->some_refs->{key} = '<censored>';
    
      $your_object->revert;
      print $your_object->some_refs, "\n"; # printed "value"

  Class::Accessor::TrackDirty->mk_accessors("name1", "name2", ...);

    Define the field which isn't tracked. You can freely change these
    fields, and it will never be marked as `dirty'.

  Class::Accessor::TrackDirty->mk_new_and_tracked_accessors("name1",
  "name2", ...);

    This method is a combination of <mk_tracked_accessors> and <mk_new>.

SEE ALSO

    Class::Accessor, Class::Accessor::Lite, MooseX::TrackDirty::Attributes,
    Hash::Dirty

AUTHOR

    Masahiro Honma <hiratara@cpan.org>

LICENSE AND COPYRIGHT

    Copyright (c) 2013, Masahiro Honma. All rights reserved.

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