NAME

       Catmandu::Bag - A Catmandu::Store compartment to persist data

SYNOPSIS

           my $store = Catmandu::Store::DBI->new(data_source => 'DBI:mysql:database=test');

           my $store = Catmandu::Store::DBI->new(
                   data_source => 'DBI:mysql:database=test',
                   bags => { journals => {
                                   fix => [ ... ] ,
                                   autocommit => 1 ,
                                   plugins => [ ... ] ,
                                   id_generator => Catmandu::IdGenerator::UUID->new ,
                             }
                           },
                   bag_class => Catmandu::Bag->with_plugins('Datestamps')
                   );

           # Use the default bag...
           my $bag = $store->bag;

           # Or a named bag...
           my $bag = $store->bag('journals');

           # Every bag is an iterator...
           $bag->each(sub { ... });
           $bag->take(10)->each(sub { ... });

           $bag->add($hash);
           $bag->add_many($iterator);
           $bag->add_many([ $hash, $hash , ...]);

           # Commit changes...
           $bag->commit;

           if ($bag->exists($id)) {
               # ...
           }

           my $obj = $bag->get($id);
           $bag->delete($id);

           $bag->delete_all;

CONFIGURATION

       fix Contains an array of fixes (or Fix files) to be applied before importing data into the
           bag.

       plugins
           An array of Catmandu::Pluggable to apply to the bag items.

       autocommit
           When set to a true value an commit automatically gets executed when the bag goes out
           of scope.

       id_generator
           A Catmandu::IdGenerator or name of an IdGenerator class.  By default
           Catmandu::IdGenerator::UUID is used.

       id_key
           Use a custom key to hold id's in this bag. See Catmandu::Store for the default or
           store wide value. Also aliased as "id_field".

METHODS

   add($hash)
       Add a hash to the bag or updates an existing hash by using its '_id' key. Returns the
       stored hash on success or undef on failure.

   add_many($array)
   add_many($iterator)
       Add or update one or more items to the bag.

   get($id)
       Retrieves the item with identifier $id from the bag.

   exists($id)
       Returns 1 if the item with identifier $id exists in the bag.

   get_or_add($id, $hash)
       Retrieves the item with identifier $id from the store or adds $hash with _id $id if it's
       not found.

   delete($id)
       Deletes the item with $id from the bag.

   delete_all
       Clear the bag.

   touch($key, $format)
       Add the current datetime to each record.

           $bag->touch('date_updated', 'iso_date_time');

       See Catmandu::Util::now for possible format values.

   commit
       Commit changes.

   log
       Return the current logger.

CLASS METHODS

   with_plugins($plugin)
   with_plugins(\@plugins)
       Plugins are a kind of fixes that should be available for each bag. E.g. the Datestamps
       plugin will automatically store into each bag item the fields 'date_updated' and
       'date_created'. The with_plugins accept one or an array of plugin classnames and returns a
       subclass of the Bag with the plugin methods implemented.

SEE ALSO

       Catmandu::Iterable, Catmandu::Searchable, Catmandu::Fix, Catmandu::Pluggable