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

NAME

Config::Versioned - Simple, versioned access to configuration data

VERSION

Version 0.02

SYNOPSIS

use Config::Versioned;

my $cfg = Config::Versioned->new();
my $param1 = $cfg->get('subsystem1.group.param1');
my $old1 = $cfg->get('subsystem1.group.param1', $version);
my @keys = $cfg->list('subsys1.db');

my $cfg2 = Config::Versioned->new( { prefix => 'subsystem1.group' } );
my $p1 = $cfg2->get('param1');
my $p2 = $cfg2->get('param2');

DESCRIPTION

Config::Versioned allows an application to access configuration parameters not only by parameter name, but also by version number. This allows for the configuration subsystem to store previous versions of the configuration parameters. When requesting the value for a specific attribute, the programmer specifies whether to fetch the most recent value or a previous value.

This is useful for long-running tasks such as in a workflow-based application where task-specific values (e.g.: profiles) are static over the life of a workflow, while global values (e.g.: name of an LDAP server to be queried) should always be the most recent.

Config::Versioned handles the versions by storing the configuration data in an internal Git repository. Each import of configuration files into the repository is documented with a commit. When a value is fetched, it is this commit that is referenced directly when specifying the version.

The access to the individual attributes is via a named-parameter scheme, where the key is a dot-separated string.

Currently, Config::Std is used for the import of the data files into the internal Git repository. Support for other configuration modules (e.g.: Config::Any) is planned.

METHODS

init()

This is invoked automatically via import(). It is called when running the following code:

use Config::Versioned;

The init() method reads the configuration data from the configuration files and populates an internal data structure.

Optionally, parameters may be passed to init(). The following named-parameters are supported:

path

Specifies an anonymous array contianing the names of the directories to check for the configuration files.

path => qw( /etc/yourapp/etc /etc/yourapp/local/etc . ),

The default path is just the current directory.

filename

Specifies the name of the configuration file to be found in the given path.

filename => qw( yourapp.conf ),

If no filename is given, no new configuration data will be imported and the internal git repository will be used.

dbpath

The directory for the internal git repository that stores the config.

dbpath => qw( config.git ),

The default is "cfgver.git".

author_name, author_mail

The name and e-mail address to use in the internal git repository for commits.

autocreate

If no internal git repository exists, it will be created during code initialization.

autocreate => 1,

The default is "0".

Note: this option might become deprecated. I just wanted some extra "insurance" during the early stages of development.

commit_time

This sets the time to use for the commits in the internal git repository. It is used for debugging purposes only!

delimiter

Specifies the delimiter used to separate the different levels in the string used to designate the location of a configuration parameter. [Default: '.']

delimiter_regex

Specifies the delimiter used to separate the different levels in the string used to designate the location of a configuration parameter. [Default: qr/ \. /xms]

new( { PARAMS } )

This is called during init() and creates an object instance. It may also be called elsewhere and given a prefix to restrict get() requests to a specific node.

isParam( LOCATION [, VERSION ] )

Returns true if the given LOCATION contains a parameter value and false if it is a tree object containing subtrees or objects. In other words, if you get a true value on a LOCATION, you can fetch the value of the parameter. Otherwise, you should use list() to see the names of the locations subordinate to this LOCATION.

NOTE: I don't like the wording of this, but it is more a minor kludge in a proof-of-concept implementation.

get( LOCATION [, VERSION ] )

This is the accessor for fetching the value(s) of the given parameter. The value may either be zero or more elements.

In list context, the values are returned. In scalar context, undef is returned if the variable is empty. Otherwise, the first element is returned.

Optionally, a VERSION may be specified to return the value for that specific version.

kind ( LOCATION [, VERSION ] )

The get() method tries to return a scalar when the location corresponds to a single value and a list when the location has child nodes. Sometimes, however, it is helpful to have a definitive answer on what a location contains.

The kind() method returns the object type that the given location accesses. This can be one of the following values:

tree

The given location contains a tree object containing zero or more child objects. The get() method will return a list of the entry names.

blob

The data node that usually contains a scalar value, but in future implementations may contain other encoded data.

Note: As a side-effect, this can be used to test whether the given location exists at all in the configuration. If not found, undef is returned.

listattr( LOCATION [, VERSION ] )

This fetches a list of the parameters available for a given location in the configuration tree.

dumptree( [ VERSION ] )

This fetches the entire tree for the given version (default: newest version) and returns a hashref to a named-parameter list.

version

This returns the current version of the configuration database, which happens to be the SHA1 hash of the HEAD of the internal git repository.

Optionally, a version hash may be passed and version() will return a true value if it is found.

INTERNALS

_init_repo INITARGS

_import_cfg INITARGS

This wrapper calls parser() and is provided for backward compatibility.

parser INITARGS

Imports the configuration read and writes it to the internal database. If no filename is passed as an argument, then it will quietly skip the commit.

Note: if you override this method in a child class, it must create an anonymous hash tree and pass the reference to the commit() method. Here is a simple example:

sub parser {
    my $self = shift;
    my $params = shift;
    $params->{comment} = 'import from my perl hash';
    
    my $cfg = {
        group1 => {
            subgroup1 => {
                param1 => 'val1',
                param2 => 'val2',
            },
        },
        group2 => {
            subgroup1 => {
                param3 => 'val3',
                param4 => 'val4',
            },
        },
    };
    
    # pass original params, appended with a comment string for the commit
    $self->commit( $cfg, $params );
}

In the comment, you should include details on where the config came from (i.e.: the filename or directory).

commit CFGHASH, INITARGS

Import the configuration tree in the CFGHASH anonymous hash and commit the modifications to the internal git bare repository.

_mknode LOCATION

Creates a node at the given LOCATION, creating parent nodes if necessary.

A reference to the node at the LOCATION is returned.

_findobj LOCATION [, VERSION ]

Returns the Git::PurePerl object found in the file path at LOCATION.

my $ref1 = $cfg->_findnode("smartcard.ldap.uri");
my $ref2 = $cfg->_findnode("certs.signature.duration", $wfcfgver);

_get_sect_key LOCATION

Returns the section and key needed by Config::Std to access the configuration values. The given LOCATION is prepended with the current prefix, if set, and is split on the last delimiter. The resulting section and key are returned as a list.

_read_options()

Called during init(), this method reads the actual configuration values and populates the internal data structure.

_which( NAME, DIR ... )

Searches the directory list DIR, returning the full path in which the file NAME was found.

_read_config_path SELF, FILENAME, CFGREF, PATH

Searches for FILENAME in the given directories in PATH. When found, the file is parsed and a data structure is written to the location in CFGREF.

Note: this is the wrapper around the underlying libs that read the configuration data from the files.

_debugtree( OBJREF | SHA1 )

This fetches the entire tree for the given SHA1 and dumps it in a human-readable format.

hdump

Return hexdump of given data.

ACKNOWLEDGEMENTS

Based on the CPAN module App::Options.

AUTHOR

Scott T. Hardin, <mrscotty at hnsc.de>

BUGS

Please report any bugs or feature requests to bug-config-versioned at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Versioned. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::Versioned

You can also look for information at:

COPYRIGHT

Copyright 2011 Scott T. Hardin, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.