NAME

Config::XrmDatabase - Pure Perl X Resource Manager Database

VERSION

version 0.09

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.

Warning! The XrmDB refers to names and resources. These days they are more typically called keys and values. The terminology used below (and sometimes in the names of subroutines and methods) mixes these two approaches, sometimes a bit too liberally.

The XrmDB differs from typical key-value stores in that a stored key may be only partially specified, so that a single entry can provide the value for many different queries.

Keys

A key is a sequence of components (such as editor, toolbar, and foreground) separated by bindings. A binding says how the components on either side of it are related:

.

The next component must follow immediately. editor.foreground matches only editor.foreground.

*

Any number of components, including none, may come between. editor*foreground matches editor.foreground, editor.toolbar.foreground, editor.toolbar.save.foreground, and so on.

A key which begins with * may match starting at any level: *foreground matches foreground, toolbar.foreground, and editor.toolbar.save.foreground. A key which doesn't begin with a binding must match starting at the first level.

Separately from bindings, a component may be the placeholder ?, which stands for exactly one component, whatever it is. editor.?.foreground matches editor.toolbar.foreground and editor.menu.foreground, but not editor.foreground or editor.toolbar.save.foreground.

? and * are easily confused. ? is a component, and always takes the place of exactly one level. * is a binding; it sits between components and can span any number of levels, including none.

The last component of a key must be a name or class component; a key may not end in ? or in a binding. A key containing neither ? nor * is fully qualified.

(N.B., the X Window System documentation calls . a tight binding and * a loose binding.)

Names and classes

Each key that is queried has a class, a parallel key with the same number of components. Classes provide a second way of addressing a key: a stored key may refer to a level by the name's component or by the class's component. A class essentially creates a namespace, so that values can be assigned based on which namespace a key belongs to rather than on the content of the key.

Let's say that you have a number of keys that 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 give each one its own value:

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 have 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, not just those in that class.

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

Matching

"query" is given a fully qualified name and its fully qualified class, which must have the same number of components. They are compared with the stored keys one level at a time, from left to right. A stored key's component matches a level if it is the name's component, the class's component, or ?; alternatively, a * in the stored key may span the level.

More than one stored key may match a query. When that happens, precedence rules choose the one whose value is returned.

Precedence at a single level

Consider a query for the name editor.toolbar.save.foreground with the class Editor.Box.Button.Foreground. Each of the following keys matches it. They differ only in how they match the third level (name save, class Button), and are listed from highest to lowest precedence:

  1. The name, immediately following the previous level

    editor.toolbar.save.foreground
  2. The name, following a * which spans no components

    editor.toolbar*save.foreground
  3. The class, immediately following the previous level

    editor.toolbar.Button.foreground
  4. The class, following a * which spans no components

    editor.toolbar*Button.foreground
  5. ?, immediately following the previous level

    editor.toolbar.?.foreground
  6. ?, following a * which spans no components

    editor.toolbar*?.foreground
  7. The level is spanned by a *, so the key has no component there

    editor.toolbar*foreground

In other words:

  • Any component that matches the level (name, class, or ?) beats spanning the level with a *.

  • A name beats a class, and a class beats ?, regardless of the binding which precedes them.

  • Between two otherwise equal matches, a component which immediately follows the previous level (.) beats one which follows a *.

Note that a * which spans no components does not cause a level to be skipped. In rules 2, 4, and 6, the key still has a component at the third level, and it is that component which is compared.

Precedence across levels

Levels are compared from left to right, and the first level at which two keys differ decides between them; later levels matter only if all earlier ones are the same. For example, using the same query of name editor.toolbar.save.foreground with class Editor.Box.Button.Foreground:

editor*save.foreground
editor.toolbar.?.foreground

the second key wins. At the second level it matches toolbar by name (rule 1), while the first key spans that level with a * (rule 7). That the first key matches save by name at the third level, while the second key only matches it with ?, doesn't matter.

Similarly, of

Editor.toolbar.save.foreground
editor*foreground

the second key wins, even though the first is much more specific. At the first level, editor matches by name (rule 1), while Editor only matches by class (rule 3).

CLASS METHODS

new

$db = Config::XrmDatabase->new( \%args );

Construct and return a new database.

Available constructor arguments are:

query_return_value string

Set the default value for the "query" method's return_value parameter. It defaults to the string value. See "query" for more details.

query_on_failure string | coderef

Set the default value for the "query" method's on_failure parameter. It defaults to the string undef. See "query" for more details.

insert hash

Populate the database with the provided key-value pairs.

read_file

$db = Config::XrmDatabase->read_file( $file, %opts );

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

Whitespace around the key and the value is removed. Blank lines, comments, and multi-line values are not supported; an exception of class Config::XrmDatabase::Failure::file is thrown if a line can't be parsed or the file can't be read.

%opts is passed to the class constructor.

METHODS

insert

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

Insert the $key, $value pair.

$key may be partially or fully qualified (see "Keys"). If $key is already in the database, its value is replaced and its match count is reset to zero. An exception of class Config::XrmDatabase::Failure::key is thrown if $key is not valid.

query

$value = $db->query( $class, $name, %options );

Query the $class, $name pair. $class and $name must be fully qualified (see "Matching"). If no match was found, the result depends upon the on_failure option; by default undef is returned. To distinguish a stored value of undef from a failed match, use the return_value => 'reference' or return_value => 'all' options, or on_failure => 'throw'.

An exception of class Config::XrmDatabase::Failure::key is thrown if $class or $name is not fully qualified, and one of class Config::XrmDatabase::Failure::components if they don't have the same number of components.

Default values for some options can be set when the database object is constructed. See "new". The following options are recognized:

return_value string

What is returned. The following are accepted:

value

query returns the value stored in the DB. This is the default.

reference

query returns a reference to the value. This allows disambiguation between an undef returned as a value and an undef returned to indicate there was no match, e.g.,

$db->insert( 'key', undef );
$value = $db->query( 'Key', 'key', return_value => 'reference' );
die( "no match\n" ) unless defined $value;
say "defined = ", defined $$value ? 'yes' : 'no';
all

query returns a hashref with the following entries:

value

The value stored in the DB.

key

The key which matched, as an array of its components and * bindings (the internal representation). Use "name_arr_to_str" in Config::XrmDatabase::Util to convert it to a normalized string.

match_count

The number of times this key has been matched, including this query.

on_failure

The action to be taken if the query fails. The following values are accepted:

The string throw

An exception of class Config::XrmDatabase::Failure::query is thrown.

The string undef

The undefined value is returned.

A reference to a subroutine

query will return the results of calling the subroutine, e.g.

return $subref->( $name, $class );

$name and $class are passed as arrays of their components (the internal representation). Use "name_arr_to_str" in Config::XrmDatabase::Util to convert them to strings.

write_file

$db->write_file( $file );

Write a simplified form of an X Resource Manager database file. See "to_string" for the format.

to_string

$string = $db->to_string( );

Encode a simplified form of an X Resource Manager database as a string.

Each record is a single line of the form

key : value

Records are in no particular order. Multi-line values are not supported, and will create an unparseable result.

merge

$db1->merge( $db2 );

Merge another database into the existing one, and return the existing one. Entries in $db1 which are also in $db2 are replaced by those in $db2, including their match counts.

clone

$db1 = $db->clone;

Return a detached clone.

to_kv

\%hash = $db->to_kv( %opt );

Return a copy of the db as a hashref.

The optional %opt hash determines the content of the returned values. Keys are returned as normalized strings, equivalent to the form accepted by "insert".

It takes the following entries:

value string

This option determines the form and content of the returned values.

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_kv_arr

\@array = $db->to_kv_arr( %opt );

Return a copy of the db as an arrayref of key, value pairs, e.g.

@array = ( [ $key, $value ], [ $key, $value ], ... );

Keys are returned as array references whose elements are the individual components (including wildcards), e.g.

@array = ( [ [ 'a', '*', 'c' ], $value ], ... );

The optional %opt hash determines the content of the returned values. It takes the following entries:

value string

This option determines the form and content of the returned values.

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

\%hash = $db->TO_HASH;

Convert the DB object into a hashref with entries query_return_value and query_on_failure (the constructor options), and db (a copy of the internal representation of the database). 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.

components

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

file

There was an error in reading or writing a file.

internal

Something went wrong that shouldn't have

key

An illegal key was specified.

parameter

Something was wrong with a passed in parameter

query

A query failed to match, and the on_failure option was throw.

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 reads and writes a simplified file format: one key : value record per line. It doesn't support multi-line values, comments, blank lines, #include directives, or escape sequences in 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