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.foregroundmatches onlyeditor.foreground. *-
Any number of components, including none, may come between.
editor*foregroundmatcheseditor.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:
The name, immediately following the previous level
editor.toolbar.save.foregroundThe name, following a
*which spans no componentseditor.toolbar*save.foregroundThe class, immediately following the previous level
editor.toolbar.Button.foregroundThe class, following a
*which spans no componentseditor.toolbar*Button.foreground?, immediately following the previous leveleditor.toolbar.?.foreground?, following a*which spans no componentseditor.toolbar*?.foregroundThe level is spanned by a
*, so the key has no component thereeditor.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_valuestring-
Set the default value for the "query" method's
return_valueparameter. It defaults to the stringvalue. See "query" for more details. query_on_failurestring | coderef-
Set the default value for the "query" method's
on_failureparameter. It defaults to the stringundef. See "query" for more details. inserthash-
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_valuestring-
What is returned. The following are accepted:
value-
queryreturns the value stored in the DB. This is the default. reference-
queryreturns a reference to the value. This allows disambiguation between anundefreturned as a value and anundefreturned 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-
queryreturns 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
-
querywill return the results of calling the subroutine, e.g.return $subref->( $name, $class );$nameand$classare passed as arrays of their components (the internal representation). Use "name_arr_to_str" in Config::XrmDatabase::Util to convert them to strings.
- The string
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:
valuestring-
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
valueandmatch_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:
valuestring-
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
valueandmatch_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_failureoption wasthrow.
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 : valuerecord per line. It doesn't support multi-line values, comments, blank lines,#includedirectives, 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