view release on metacpan or  search on metacpan

README  view on Meta::CPAN

          my $elem = $db->shift();

    *   unshift()

        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", {});

    *   splice()

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

    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";
      }

LOCKING
    Enable or disable automatic file locking by passing a boolean value to
    the "locking" parameter when constructing your DBM::Deep object (see
    "SETUP" above).

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

    This causes DBM::Deep to "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 "flock()" does NOT work for
    files over NFS. See "DB over NFS" below for more.

  Explicit Locking
    You can explicitly lock a database, so it remains locked for multiple
    actions. This is done by calling the "lock_exclusive()" method (for when
    you want to write) or the "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();

  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.

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

  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 "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 $struct object into $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 "import()" method can be called on any database level (not
    just the base level), and works with both hash and array DB types.

    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.