.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catmandu::Plugin::Versioning 3pm"
.TH Catmandu::Plugin::Versioning 3pm "2019-01-29" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catmandu::Plugin::Versioning \- Automatically adds versioning to Catmandu::Store records
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # 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 \*(Aq{"_id":"001",hello":"world"}\*(Aq | catmandu import JSON to test
\& $ echo \*(Aq{"_id":"001",hello":"world2"}\*(Aq | catmandu import JSON to test
\&
\& # In the store we see only the latest version
\& $ catmandu export test to YAML
\& \-\-\-
\& _id: \*(Aq001\*(Aq
\& _version: 2
\& hello: world2
\&
\& # In the \*(Aq_version\*(Aq store we\*(Aqll find all the previous versions
\& $ catmandu export test \-\-bag data_version to YAML
\& \-\-\-
\& _id: \*(Aq001.1\*(Aq
\& data:
\&  _id: \*(Aq001\*(Aq
\&  _version: 1
\&  hello: world
\&
\& # Or in your Perl program
\& my $store = Catmandu\->store(\*(AqMongoDB\*(Aq,
\&            database_name => \*(Aqtest\*(Aq ,
\&            bags => {
\&                data => {
\&                plugins => [qw(Versioning)]
\&            }
\&        });
\&
\& $store\->bag\->add({ _id => \*(Aq001\*(Aq , hello => \*(Aqworld\*(Aq});
\& $store\->bag\->add({ _id => \*(Aq001\*(Aq , hello => \*(Aqworld2\*(Aq});
\&
\& print "Versions:\en";
\&
\& for (@{$store\->bag\->get_history(\*(Aq001\*(Aq)}) {
\&    print Dumper($_);
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
When using Catmandu::Store\-s that don't have dynamic schema's (e.g. Solr , \s-1DBI\s0) these new bags need to be
predefined (e.g. create new Solr cores or database tables).
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.IP "version_compare_ignore" 4
.IX Item "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
.Sp
.Vb 10
\& # 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 => \*(Aq001\*(Aq , name => \*(Aqtest\*(Aq , date_updated => \*(Aq10:00\*(Aq });
\&
\& # Second version (name has changed)
\& $store\->bag\->add({ _id => \*(Aq001\*(Aq , name => \*(Aqtest123\*(Aq , date_updated => \*(Aq10:00\*(Aq });
\&
\& # Second version (date_updated has changed but we ignored that in our configuration)
\& $store\->bag\->add({ _id => \*(Aq001\*(Aq , name => \*(Aqtest123\*(Aq , date_updated => \*(Aq10:15\*(Aq });
.Ve
.IP "version_transfer" 4
.IX Item "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.
.Sp
.Vb 10
\& # 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 => \*(Aq001\*(Aq , name => \*(Aqtest\*(Aq , rights => \*(AqAcme Corp.\*(Aq });
\&
\& # Second version we will try you delete rights but this is copied to the new version
\& $store\->bag\->add({ _id => \*(Aq001\*(Aq , name => \*(Aqtest\*(Aq});
\&
\& print "Rights: %s\en" , $store\->bag\->get(\*(Aq001\*(Aq)\->{rights}; # Rights: Acme Corp.
.Ve
.IP "version_bag" 4
.IX Item "version_bag"
The name of the bag that stores the versions. Default is the name of the
versioned bag with '_version' appended.
.Sp
.Vb 3
\&    my $store = Catmandu::Store::MyDB\->new(bags => {book => {plugins =>
\&        [\*(AqVersioning\*(Aq], version_bag => \*(Aqbook_history\*(Aq}});
\&    $store\->bag(\*(Aqbook\*(Aq)\->version_bag\->name # returns \*(Aqbook_history\*(Aq
.Ve
.IP "version_key" 4
.IX Item "version_key"
Use a custom key to hold the version number in this bag. Default is '_version'
unless the store has a custom \f(CW\*(C`key_prefix\*(C'\fR. Also aliased as \f(CW\*(C`version_field\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
Every bag that is configured with the Catmandu::Plugin::Versioning plugin can use the following methods:
.SS "get_version(\s-1ID,VERSION\s0)"
.IX Subsection "get_version(ID,VERSION)"
Retrieve a record with identifier \s-1ID\s0 and version identifier \s-1VERSION. E\s0.g.
.PP
.Vb 1
\&    my $obj = $store\->bag(\*(Aqtest\*(Aq)\->get_version(\*(Aq001\*(Aq,1);
.Ve
.SS "get_previous_version(\s-1ID\s0)"
.IX Subsection "get_previous_version(ID)"
Retrieve the previous version of a record with identifier \s-1ID. E\s0.g.
.SS "get_history(\s-1ID\s0)"
.IX Subsection "get_history(ID)"
Returns an \s-1ARRAY\s0 reference with all the versions of the record with identifier \s-1ID.\s0
.SS "restore_version(\s-1ID,VERSION\s0)"
.IX Subsection "restore_version(ID,VERSION)"
Overwrites the current version of the stored record with identifier \s-1ID\s0 with a version with identifier \s-1VERSION.\s0
.SS "restore_previous_version(\s-1ID\s0)"
.IX Subsection "restore_previous_version(ID)"
Overwrites the current version of the stored record with identifier \s-1ID\s0 with its previous version.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catmandu::Store, Catmandu::Bag