/ 
Config-XrmDatabase-0.02
River stage zero No dependents
/ Config::XrmDatabase

NAME

Config::XrmDatabase - Pure Perl X Resource Manager Database

VERSION

version 0.02

SYNOPSIS

$db = Config::XrmDatabase->new;
$db->insert( '*b.c.d', 'v1' );
$db->query( 'A.B.C.D', 'a.b.c.d' );

DESCRIPTION

This is a Pure Perl implementation of the X Window Resource Manager Database (XrmDB). It allows creation and manipulation of Xrm compliant databases.

Why another configuration database?

The XrmDB differs from typical key-value stores by allowing stored keys to be either fully or partially qualified. For example, the partially qualified key

*.c.d

will match a query for the keys a.c.d, a.b.c.d. Keys are composed of multiple components separated by the . character. If the component is ? it will match any single component; a component of * matches any number (including none).

Matching

Matching a search key against the database is a component by component operation, starting with the leftmost component. The component in the search key is checked against the same level component in the database keys. First the keys with non-wildcard components are compared; if there is an exact match, the search moves on to the next component in the matching database key.

At this point, XrmDB adds another dimension to the search. Keys belong to a class, which has the same number of components as the key. When an exact match against the search key component is not found, the database is searched for an exact match for the same level component in the class.

Only after that fails does the algorithm switch to database keys with wildcard components. The same order of comparison is performed; first against the component in the search key, and if that fails, to the component in the class.

For example, given a search key of

xmh.toc.messagefunctions.incorporate.activeForeground'

with a class of

Xmh.Paned.Box.Command.Foreground

the database is first searched for keys which begin with xmh. If that fails, the database is searched for keys which begin with Xmh. If that fails, keys which start with a ? wildcard are searched, and then those which start with *. The * components can match an arbitrary number of components in the search key and class.

If a match is found, the search moves on to the next unmatched component and the algorithm is repeated.

Classes

Why the extra class?

Assigning keys to a class provides an ability to distinguish between two similarly structured keys. It essentially creates namespaces for keys so that values can be created based on which namespace a key belongs to, rather than the content of the key.

Let's say that you have a bunch of keys which end in Foreground:

a.b.c.Foreground
d.e.f.Foreground
x.y.z.Foreground

and you want to set a value for any keys which end in Foreground:

*.Foreground : 'yellow'

To specify a separate value for each one could set

a.b.c.Foreground : 'red'
d.e.f.Foreground : 'blue'
x.y.z.Foreground : 'green'

Let's say that a.b.c.Foreground and d.e.f.Foreground are in the same class, U.V.W.Foreground, and all keys in that class should have the same value:

U.V.W.Foreground : 'red'
x.y.z.Foreground : 'green'

At some point, a new hierarchy of keys that begin with g is added to that class, but they should has a different value:

g.V.W.Foreground : 'magenta'

You could try this:

g.?.?.Foreground : 'magenta'

But that would affect all keys that begin with g but aren't in that class.

Classes help bring some order, but this system can become very confusing if some discipline isn't maintained.

CLASS METHODS

new

$db = Config::XrmDatabase->new;

Construct an empty database.

read_file

$db = read_file( $class, $file );

Create a database from a simplified version of the X Resource Manager database file. Each record is a single line of the form

key : value

Multiline values are not parsed.

METHODS

insert

$db->insert( $key, $value );

Insert the $key, $value pair.

$match may be partially or fully qualified (see "Match Keys" );

query

$db->query( $class, $name );

Query the $key, $name pair.

$class and $name must be fully qualified (see "Matching" ).

An exception object in class Config::XrmDatabase::Failure::illegal::resource::name

write_file

$db->write_file( $file );

Write a simplified form of an X Resource Manager database file.

Each record is a single line of the form

key : value

Multiline values are not supported, and will create an unparseable file.

merge

$db1->merge( $db2);

Merge another database into the existing one. Common entries are overwritten.

clone

$db1 = $db->clone;

Return a detached clone.

to_kv

$hash = $db=>to_kv( ?$meta };

Return a copy of the db in key, value form. The optional $meta parameter determines what values are returned in $hash.

value

The value stored when the DB entry was created.. This is the default.

match_count

The number of times the key was successfully matched by queries against the database.

all

A hash containing all of the data associated with the key. Currently this includes value, and match_count

TO_HASH

$db->TO_HASH;

Convert the DB into a hash. This replicates the internal DB structure. Useful? Who knows?

See "to_kv" for a perhaps more useful output.

EXCEPTIONS

Exception objects which are thrown are in the Config::XrmDatabase::Failure namespace.

They stringify to a detailed message, which is also available via the msg method.

key

An illegal key was specified.

components

There is a mismatch in components between a key and its class.

file

There was an error in reading or writing a file.

INCOMPATIBILITIES

    * This module does not interface with the X Window system.

    * This module has a different API.

    * This module doesn't assign a locale to a database.

    * This module doesn't associate types with values.

    * This module can't read or write config files with multi-line values

SUPPORT

Bugs

Please report any bugs or feature requests to bug-config-xrmdatabase@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Config-XrmDatabase

Source

Source is available at

https://gitlab.com/djerius/config-xrmdatabase

and may be cloned from

https://gitlab.com/djerius/config-xrmdatabase.git

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2021 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007