NAME

GDBM - Gnu DBM binding

SYMOPSIS

use GDBM;

my $data = GDBM.new('somefile.db');

$data<foo> = 'bar';

say $data<foo>:exists;

$data.close;

# Then in some time later, possibly in another program

$data = GDBM.new('somefile.db');

say $data<foo>;

$data.close;

DESCRIPTION

The GNU DBM stores key/value pairs in a hashed database file. Its implementation allows for keys and values of arbitrary length (compared to fairly frugal limits on some earlier implementations.)

This module allows for the data to be transparently managed as if it were in an normal Associative container such as a Hash. The only limitation currently is that both key and value must be strings (or can be meaningfully stringified,) so e.g. structured data will need to be serialised to some format that can be represented as a string. However it can be used for persistence or caching if this doesn't need to be shared by processes on different machines.

METHODS

As well as the listed methods a GDBM object should support most of the methods that make sense for an Associative.

method new

multi method new(Str $filename)
    multi method new(Str :$filename!, Int :$block-size = 512, Int() :$flags = Create +| Sync +| NoMMap, Int :$mode = 0o644)
    multi method new(GDBM::File :$file)

The first form of the constructor simply takes a database filename and opens it with the default options as per the second form. The flags parameter is some combination of values of the enums GDBM::OpenMode and GDBM::OpenOptions, the default being to create the file if it doesn't exist, automatically sync the data and not use memory mapping of the data. mode is the permissions (as an octal value,) that the file will be created with after the application of the users file creation mask (umask.) The arguments to this form are identical to those of the underlying GDBM::File. The third variant allows you to provide a pre-constructed and open GDBM::File if the design of your program might require it.

method store

multi method store(Str:D $key, Str:D $value, StoreOptions $flag = Replace --> Bool)
    multi method store(Pair $p, StoreOptions $flag = Replace --> Bool)
    multi method store(*%items --> Bool)

This stores the supplied $value under $key, the default option is to replace the existing value for a given key, if GDBM::Insert is supplied for $flag then the value will only be stored if the key does not already exist in the database, if the key is already present then an exception will be thrown. If the file is opened as a Reader only then an exception will be thrown. If the storage is successful then True will be returned. The third variamt is provided for completeness allowing the pairs to be expressed like named arguments,

method fetch

method fetch(Str $key) returns Str

This returns the value associated with the supplied key, or a Str type object if it is not present in the database.

method exists

multi method exists(Str $key) returns Bool

This returns True if the key supplied exists in the database.

method delete

method delete(Str $k) returns Bool

This deletes the key (and associated value) from the database. Returning True if it exists and was successful. If the key isn't present or if the database isn't opened for writing it will return false.

method first-key

method first-key() returns Str

This returns the first key in the database or an undefined Str type object if there are no entries in the database, This is the interface provided by the gdbm library, but you probably want to use keys as provided by the Associative interface unless you have special needs. The keys aren't returned in a particular order as it is defined by the hashing algorithm,

method next-key

method next-key(Str $prev) returns Str

Returns the next available key from the database or a Str type object if there are no more entries. The argument is a defined key that was previously returned by first-key or next-key.

method reorganize

method reorganize() returns Bool

Normally gdbm will reuse the space taken up by deleted items. This can be used sparingly to reduce the size of the gdbm file by returning the space used by deleted items.

method sync

method sync()

If you didn't provide Sync in the flags to the constructor then, e.g. store and delete operations may not be completely written to disk before they return. Calling this will ensure all pending changes are flushed to disk. It does not return until the disk file is completely written.