NAME
    Data::RecordStore - Simple and fast record based data store

SYNPOSIS
    use Data::RecordStore;

    my $store = Data::RecordStore->open_store( $directory );

    my $data = "TEXT DATA OR BYTES";

    my $id = $store->stow( $data, $optionalID );

    my $val = $store->fetch( $id );

    my $new_or_recycled_id = $store->next_id;

    $store->stow( "MORE DATA", $new_or_recycled_id );

    my $has_object_at_id = $store->has_id( $someid );

    $store->delete( $someid );

    $store->empty_recycler; $store->recycle( $dead_id );

DESCRIPTION
    A simple and fast way to store arbitrary text or byte data. It is
    written entirely in perl with no non-core dependencies. It is designed
    to be both easy to set up and easy to use.

LIMITATIONS
    Data::RecordStore is not meant to store huge amounts of data. It will
    fail if it tries to create a file size greater than the max allowed by
    the filesystem. This limitation may be removed in subsequent versions.
    This limitation is most important when working with sets of data that
    approach the max file size of the system in question.

    This is not written with thread safety in mind, so unexpected behavior
    can occur when multiple Data::RecordStore objects open the same
    directory. Locking coordination is currently the responsibility of the
    implementation.

METHODS
  open_store( directory )
    Takes a single argument - a directory, and constructs the data store in
    it. The directory must be writeable or creatible. If a RecordStore
    already exists there, it opens it, otherwise it creates a new one.

  stow( data, optionalID )
    This saves the text or byte data to the record store. If an id is passed
    in, this saves the data to the record for that id, overwriting what was
    there. If an id is not passed in, it creates a new record store.

    Returns the id of the record written to.

  fetch( id )
    Returns the record associated with the ID. If the ID has no record
    associated with it, undef is returned.

  entry_count
    Returns how many active ids have been assigned in this store. If an ID
    was assigned but not used, it still counts towards the number of
    entries.

  delete( id )
    Removes the entry with the given id from the store, freeing up its
    space. It does not reuse the id.

  has_id( id )
      Returns true if an object with this id exists in the record store.

  next_id
    This sets up a new empty record and returns the id for it.

  empty()
    This empties out the entire record store completely. Use only if you
    mean it.

  empty_recycler()
      Clears out all data from the recycler

  recycle( id, keep_data_flag )
      Ads the id to the recycler, so it will be returned when next_id is called.
      This removes the data occupied by the id, freeing up space unles keep_data_flag
      is set to true.

HELPER PACKAGES
    Data::RecordStore relies on two helper packages that are useful in their
    own right and are documented here.

HELPER PACKAGE
    Data::RecordStore::FixedStore

DESCRIPTION
    A fixed record store that uses perl pack and unpack templates to store
    identically sized sets of data and uses a single file to do so.

SYNOPSIS
    my $template = "LII"; # perl pack template. See perl pack/unpack.

    my $size; #required if the template does not have a definite size, like
    A*

    my $store = Data::RecordStore::FixedStore->open_fixed_store( $template,
    $filename, $size );

    my $new_id = $store->next_id;

    $store->put_record( $id, [ 321421424243, 12, 345 ] );

    my $more_data = $store->get_record( $other_id );

    my $removed_last = $store->pop;

    my $last_id = $store->push( $data_at_the_end );

    my $entries = $store->entry_count;

    if( $entries < $min ) {

        $store->_ensure_entry_count( $min );

    }

    $store->emtpy;

    $store->unlink_store;

METHODS
  open_fixed_store( template, filename, size )
    Opens or creates the file given as a fixed record length data store. If
    a size is not given, it calculates the size from the template, if it
    can. This will die if a zero byte record size is determined.

  empty
    This empties out the database, setting it to zero records.

  
    Returns the number of entries in this store. This is the same as the
    size of the file divided by the record size.

  get_record( idx )
    Returns an arrayref representing the record with the given id. The array
    in question is the unpacked template.

  next_id
    adds an empty record and returns its id, starting with 1

  pop
    Remove the last record and return it.

  last_entry
    Return the last record.

  push( data )
    Add a record to the end of this store. Returns the id assigned to that
    record. The data must be a scalar or list reference. If a list
    reference, it should conform to the pack template assigned to this
    store.

  push( idx, data )
    Saves the data to the record and the record to the filesystem. The data
    must be a scalar or list reference. If a list reference, it should
    conform to the pack template assigned to this store.

  unlink_store
    Removes the file for this record store entirely from the file system.

AUTHOR
       Eric Wolf        coyocanid@gmail.com
COPYRIGHT AND LICENSE
           Copyright (c) 2015-2017 Eric Wolf. All rights reserved.  This program is free software; you can redistribute it and/or modify it
           under the same terms as Perl itself.

VERSION
       Version 2.03  (Nov 21, 2017))