Esmith::DB::db

NAME

esmith::DB::db - interface to esmith::db databases

In a root terminal you can do the command below if you want to display the up-to-date content

perldoc -U esmith::DB::db

SYNOPSIS

Works just like an esmith::DB class except where noted

DESCRIPTION

This module provides an abstracted interface to esmith::db flat-file databases. It will read from and write to esmith::db files and can be safely used right along side esmith::db. This follows the esmith::DB interface and will work as documented there unless otherwise stated.

You should use this instead of esmith::db, and replace any existing esmith::db code with this.

Note for esmith::db users the old concept of a ’type’ is now simply another property.

          my $type = $record->prop(’type’);

replaces db_get_type().

The $record returned by esmith::DB::db subclass is an esmith::DB::db::Record subclass object. See the esmith::DB::db manpage for details on how it is used.

Methods

create

Puts its error on esmith::DB::db->error

      open
      open_local
      as_hash
      reload
      file
      new_record
      get
      get_all
      get_all_by_prop

EXAMPLE

The full docs can be found in esmith::DB and esmith::DB::Record, but here’s a cheat sheet for esmith::config and esmith::db users.

opening the default config

              use esmith::config
              my %config;
              tie %config, ’esmith::config;

Now:

              use esmith::ConfigDB;
              my $config = esmith::ConfigDB->open;

opening a specific config database

              my %config;
              tie %config, ’esmith::config’, $config_file;

Now:

              my $config = esmith::ConfigDB->open($config_file);

creating a new config database

This one’s important. Before you could just tie esmith::config to any file and it would create it for you. Now you have to explicitly create it.

              my %config;
              tie %config, ’esmith::config’, $new_config_file;

Now:

              my $config = esmith::ConfigDB->create($new_config_file);

example for creating and using a custom database in one line:

my $customDB = esmith::ConfigDB->open('YOUR_DATABASE_NAME') || esmith::ConfigDB->create('YOUR_DATABASE_NAME');

checking if a record exists

              print "Yep" if exists $config{foo};

now:

              print "Yep" if $config->get(’foo’); # unless of course, ’foo’ is zero

creating a new record

Previously you could just create records on the fly:

              # single value
              $config{foo} = ’whatever’;

              # with properties
              db_set(\%config, ’whatever’, ’sometype’, { with => ’properties’ });

Now you have to explicitly create them:

              # single value
              my $foo = $config->new_record(’foo’);
              $foo->set_value(’foo’);

              # with properties
              my %defaults = ( ’type’    => ’sometype’,
                               ’linux’   => ’stable’,
                               ’windows’ => ’stable?’ );
              my $foo = $config->new_record(’foo’, \%defaults);

Note that ’type’ is now just another property.

Here’s a handy "create this if it doesn’t already exist" idiom.

              my $rec = $config->get($key) ││
                        $config->new_record($key);

for example (if it doesn't exist we create it)

    my $rec = $DB->get('roundcube') || $DB->new_record('roundcube', {type => 'service'});

getting a value

Entries in a database should no longer be thought of as values, but as records.

              my $val = $config{foo};

Now this only works with entries with single value. Things with multiple properties are dealt with differently.

              my $record = $config->get(’foo’);
              my $val = $record->value;

setting a value

              $config{foo} = ’something’;

now

              my $record = $config->get(’foo’);
              $record->set_value(’something’);

getting a property

              my $this = db_get_prop(\%config, ’foo’, ’this’);

now:

              my $foo = $config->get(’foo’);
              my $this = $foo->prop(’this’);

getting & setting properties

              my $val = db_get_prop(\%config, ’foo’, ’some prop’);
              db_set_prop(\%config, ’foo’, ’some prop’ => $new_val);

now:

              my $val = $record->prop(’some prop’);
              $record->set_prop(’some prop’ => $new_val);

get/setting the type

              my $type = db_get_type(\%config, ’foo’);
              db_set_type(\%config, ’foo’, $new_type);

type is now just a property

              my $record = $db->get(’foo’);
              my $type = $record->prop(’type’);
              $record->set_prop(’type’, $new_type);

getting all the properties

              my %props = db_get_prop(\%config, ’foo’);

now

              my %props = $record->props;

AUTHOR

      SME Server Developers <bugs@e-smith.com>