view release on metacpan or  search on metacpan

lib/DBM/Deep.pod  view on Meta::CPAN

Inserts one or more elements onto the beginning of the array, shifting all
existing elements over to make room. Accepts scalars, hash refs or array refs.
No return value. This method is not recommended with large arrays -- see
<Large Arrays> below for details.

  $db->unshift("foo", "bar", {});

=item * splice()
X<splice>

Performs exactly like Perl's built-in function of the same name. See
L<perlfunc/splice> for usage -- it is too complicated to document here. This
method is not recommended with large arrays -- see L</Large Arrays> below for
details.

=back

Here are some examples of using arrays:

  my $db = DBM::Deep->new(
      file => "foo.db",
      type => DBM::Deep->TYPE_ARRAY
  );

  $db->push("bar", "baz");
  $db->unshift("foo");
  $db->put(3, "buz");

  my $len = $db->length();
  print "length: $len\n"; # 4

  for (my $k=0; $k<$len; $k++) {
      print "$k: " . $db->get($k) . "\n";
  }

  $db->splice(1, 2, "biz", "baf");

  while (my $elem = shift @$db) {
      print "shifted: $elem\n";
  }

=head1 LOCKING

Enable or disable automatic file locking by passing a boolean value to the
C<locking> parameter when constructing your DBM::Deep object (see L</SETUP>
above).

  my $db = DBM::Deep->new(
      file => "foo.db",
      locking => 1
  );

This causes DBM::Deep to C<flock()> the underlying filehandle with exclusive
mode for writes, and shared mode for reads. This is required if you have
multiple processes accessing the same database file, to avoid file corruption.
Please note that C<flock()> does NOT work for files over NFS. See L</DB over
NFS> below for more.

=head2 Explicit Locking

You can explicitly lock a database, so it remains locked for multiple
actions. This is done by calling the C<lock_exclusive()> method (for when you
want to write) or the C<lock_shared()> method (for when you want to read).
This is particularly useful for things like counters, where the current value
needs to be fetched, then incremented, then stored again.

  $db->lock_exclusive();
  my $counter = $db->get("counter");
  $counter++;
  $db->put("counter", $counter);
  $db->unlock();

  # or...

  $db->lock_exclusive();
  $db->{counter}++;
  $db->unlock();

=head2 Win32/Cygwin

Due to Win32 actually enforcing the read-only status of a shared lock, all
locks on Win32 and cygwin are exclusive. This is because of how autovivification
currently works. Hopefully, this will go away in a future release.

=head1 IMPORTING/EXPORTING

You can import existing complex structures by calling the C<import()> method,
and export an entire database into an in-memory structure using the C<export()>
method. Both are examined here.

=head2 Importing

Say you have an existing hash with nested hashes/arrays inside it. Instead of
walking the structure and adding keys/elements to the database as you go,
simply pass a reference to the C<import()> method. This recursively adds
everything to an existing DBM::Deep object for you. Here is an example:

  my $struct = {
      key1 => "value1",
      key2 => "value2",
      array1 => [ "elem0", "elem1", "elem2" ],
      hash1 => {
          subkey1 => "subvalue1",
          subkey2 => "subvalue2"
      }
  };

  my $db = DBM::Deep->new( "foo.db" );
  $db->import( $struct );

  print $db->{key1} . "\n"; # prints "value1"

This recursively imports the entire C<$struct> object into C<$db>, including
all nested hashes and arrays. If the DBM::Deep object contains existing data,
keys are merged with the existing ones, replacing if they already exist.
The C<import()> method can be called on any database level (not just the base
level), and works with both hash and array DB types.

B<Note:> Make sure your existing structure has no circular references in it.
These will cause an infinite loop when importing. There are plans to fix this
in a later release.