===== esmith::DB::db =====
 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);

==== 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);

==== 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>
{{tag> neth-development sme-development }}