NAME

       Catmandu::Plugin::Versioning - Automatically adds versioning to Catmandu::Store records

SYNOPSIS

        # Using configuration files

        $ cat catmandu.yml
        ---
        store:
         test:
           package: MongoDB
           options:
             database_name: test
             bags:
               data:
                 plugins:
                   - Versioning

        # Add two version of record 001 to the store
        $ echo '{"_id":"001",hello":"world"}' | catmandu import JSON to test
        $ echo '{"_id":"001",hello":"world2"}' | catmandu import JSON to test

        # In the store we see only the latest version
        $ catmandu export test to YAML
        ---
        _id: '001'
        _version: 2
        hello: world2

        # In the '_version' store we'll find all the previous versions
        $ catmandu export test --bag data_version to YAML
        ---
        _id: '001.1'
        data:
         _id: '001'
         _version: 1
         hello: world

        # Or in your Perl program
        my $store = Catmandu->store('MongoDB',
                   database_name => 'test' ,
                   bags => {
                       data => {
                       plugins => [qw(Versioning)]
                   }
               });

        $store->bag->add({ _id => '001' , hello => 'world'});
        $store->bag->add({ _id => '001' , hello => 'world2'});

        print "Versions:\n";

        for (@{$store->bag->get_history('001')}) {
           print Dumper($_);
        }

DESCRIPTION

       The Catmandu::Plugin::Versioning plugin automatically adds a new 'version' bag to your
       Catmandu::Store containing previous versions of newly created records. The name of the
       version is created by appending '_version' to your original bag name. E.g. when add the
       Versioning plugin to a 'test' bag then 'test_version' will contain the previous version of
       all your records.

       When using Catmandu::Store-s that don't have dynamic schema's (e.g. Solr , DBI) these new
       bags need to be predefined (e.g. create new Solr cores or database tables).

CONFIGURATION

       version_compare_ignore
           By default every change to a record with trigger the creation of a new version. Use
           the version_compare_ignore option to specify fields that should be ignored when
           testing for new updates. E.g. in the example below we configured the MongoDB store to
           add versioning to the default 'data' bag. We want to ignore changes to the
           'date_updated' field when creating new version records

            # catmandu.yml
            ---
            store:
             test:
               package: MongoDB
               options:
                 database_name: test
                 bags:
                   data:
                     plugins:
                       - Versioning
                     version_compare_ignore:
                       - date_updated

            # In your perl

            # First version
            $store->bag->add({ _id => '001' , name => 'test' , date_updated => '10:00' });

            # Second version (name has changed)
            $store->bag->add({ _id => '001' , name => 'test123' , date_updated => '10:00' });

            # Second version (date_updated has changed but we ignored that in our configuration)
            $store->bag->add({ _id => '001' , name => 'test123' , date_updated => '10:15' });

       version_transfer
           This option autmatically copies the configured fields from the previous version of a
           record to the new version of the record. E.g. in the example below we will create a
           versioning on the default bag and add a rights statement that can not be deleted.

            # catmandu.yml
            ---
            store:
             test:
               package: MongoDB
               options:
                 database_name: test
                 bags:
                   data:
                     plugins:
                       - Versioning
                     version_transfer:
                       - rights:

            # In your perl

            # First version
            $store->bag->add({ _id => '001' , name => 'test' , rights => 'Acme Corp.' });

            # Second version we will try you delete rights but this is copied to the new version
            $store->bag->add({ _id => '001' , name => 'test'});

            print "Rights: %s\n" , $store->bag->get('001')->{rights}; # Rights: Acme Corp.

       version_bag
           The name of the bag that stores the versions. Default is the name of the versioned bag
           with '_version' appended.

               my $store = Catmandu::Store::MyDB->new(bags => {book => {plugins =>
                   ['Versioning'], version_bag => 'book_history'}});
               $store->bag('book')->version_bag->name # returns 'book_history'

       version_key
           Use a custom key to hold the version number in this bag. Default is '_version' unless
           the store has a custom "key_prefix". Also aliased as "version_field".

METHODS

       Every bag that is configured with the Catmandu::Plugin::Versioning plugin can use the
       following methods:

   get_version(ID,VERSION)
       Retrieve a record with identifier ID and version identifier VERSION. E.g.

           my $obj = $store->bag('test')->get_version('001',1);

   get_previous_version(ID)
       Retrieve the previous version of a record with identifier ID. E.g.

   get_history(ID)
       Returns an ARRAY reference with all the versions of the record with identifier ID.

   restore_version(ID,VERSION)
       Overwrites the current version of the stored record with identifier ID with a version with
       identifier VERSION.

   restore_previous_version(ID)
       Overwrites the current version of the stored record with identifier ID with its previous
       version.

SEE ALSO

       Catmandu::Store, Catmandu::Bag