NAME

Data::Pensieve - Simple tool for interacting with revisioned data

SYNOPSIS

use Data::Pensieve;

my $pensieve = Data::Pensieve->new(
    revision_rs      => $c->model('DB::Revision'),
    revision_data_rs => $c->model('DB::RevisionData'),
    definitions      => {
        lolcats => [ qw/name saying picture/ ],
    },
);

$pensieve->store_revision(
    lolcats => 1,
    {
        # data
        name    => 'lazy lolcat',
        saying  => 'i cannot brian today. i have the dumb',
        picture => 'lazycat.png',
    },
    {
        # change metadata
        modified_by => 'waffle wizard',
    },
);

# oops! a typo! time to denote a change.
$pensieve->store_revision(
    lolcats => 1,
    {
        # data
        saying => 'i cannot brain today. i have the dumb',
    },
    {
        # change metadata
        modified_by => 'assistant regional manager',
    },
);

my @revisions = $pensieve->get_revisions(lolcats => 1);

my ($rev1, $rev2) = @revisions;

my $comparison = $pensieve->compare_revisions($rev1, $rev2);
# {
#   saying => [
#       'i cannot brian today. i have the dumb',
#       'i cannot brain today. i have the dumb'
#   ]
# }

DESCRIPTION

"I use the Pensieve. One simply siphons the excess thoughts from one's mind, pours them into the basin, and examines them at one's leisure. It becomes easier to spot patterns and links, you understand, when they are in this form." - Albus Dumbledore

In the world of Harry Potter, a Pensieve is a magical device that allows a wizard to store and review his or her thoughts. Data::Pensieve serves a similar purpose for Perl applications, allowing you to easily record revision histories and analyze differences between revisions.

Data::Pensieve uses a DBIx::Class backend to store revision data.

METHODS

new()

Returns a new Data::Pensieve object. Takes the following required parameters.

• definitions

  A hash reference, where the keys are the names of groups of data and the values are array references of the expected columns.

  For instance:

  # {
  #    cats       => [ qw/ name favorite_toy           / ],
  #    people     => [ qw/ name occupation             / ],
  #    food       => [ qw/ name calories               / ],
  #    japh       => [ qw/ cpan_name num_yapcs_attended /],
  # }

• revision_rs

  A DBIx::Class::ResultSet representing the revision table, which must have the following schema:

  revision_id int auto_increment primary key,
  grouping    varchar(255),
  identifier  varchar(255),
  recorded    datetime,
  metadata    blob

• revision_data_rs

  A DBIx::Class::ResultSet reprensenting the revision data table, which must have the following schema:

  revision_data_id int auto_increment primary key,
  revision_id      int,
  datum            varchar(255),
  datum_value      blob

store_revision()

Given a grouping, item, hash reference of data, and optional hash reference of metadata related to this change, stores a change.

get_revisions()

Given a grouping and item number, returns all associated revisions.

get_last_revision()

Given a grouping and item number, returns the last revision.

compare_revisions()

Given two Data::Pensieve::Revision objects, returns a hash reference, keyed by column name, containing array references of the prior and current version of all changed data between the two provided revisions.

diff_revisions()

Same as compare_revisions(), but returns a diff between the two values instead of an array reference.

SEE ALSO

Data::Pensieve is intended as a quick & dirty, plug & play way to easily manage revisioned data.

If you're looking to do something more substantial, you probably want to consider journaling your data at the database level -- check out DBIx::Class::AuditLog or DBIx::Class::Journal.

DEPENDENCIES

Carp, DateTime, DateTime::Format::MySQL, DBIx::Class, List::Util, List::MoreUtils, Moose, Storable, Text::Diff

AUTHORS

Michael Aquilina <aquilina@cpan.org>

Developed for Grant Street Group's Testafy (http://testafy.com)