init()

 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. Note that if an import filename is specified, this automatically sets autocreate to true.

 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!

Note: this must be a DateTime object instance.

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]

log_get_callback

Specifies a callback function to be called by get() after fetching the value for the given key. The subroutine should accept the parameters LOCATION, VERSION, VALUE. The VALUE may either be a single scalar value or an array reference containing a list of values.

    sub cb_log_get {
        my $self = shift;
        my $loc = shift;
        my $ver = shift;
        my $val = shift;

        warn "Access config parameter: $loc ($ver) => ",
            ref($val) eq 'ARRAY'
                ? join(', ', @{ $val })
                : $val,
            "\n";
    }
    my $cfg = Config::Versioned->new( { log_get_callback => 'cb_log_get' } );
    

Note: if log_get_callback is a code ref, it will be called as a function. Otherwise, the log_get_callback will specify a method name that is to be called on the current object instance.

BUILD( { PARAMS } )

This is called after an object is created. When cloning, it is important that the new instance gets a reference to the same Git::PurePerl instance. This will prevent two instances from getting out of sync if modifications are made to the configuration data at runtime. To handle this, the parameter 'GITREF' must be passed when cloning.

Note 2: this should be handled automatically in the _near_ future.

    my $cv2 = $cv1->new( GITREF => $cv1->_git() );

get( LOCATION [, VERSION ] )

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 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 ] )

dumptree( [ VERSION ] )

version

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

_init_repo

If the objects directory in the "dbpath" does not exist, an "init()" on the "Git::PurePerl" class is run. Otherwise, the instance is initialized using the existing bare repository.

On error, it returns "undef" and the reason is in $@.

_get_anon_scalar

parser ARGS

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 $args = shift;
        $args->{comment} = 'import from my perl hash';
        
        my $cfg = {
            group1 => {
                subgroup1 => {
                    param1 => 'val1',
                    param2 => 'val2',
                },
            },
            group2 => {
                subgroup1 => {
                    param3 => 'val3',
                    param4 => 'val4',
                },
            },
            # This creates a symlink from 'group3.subgroup3' to 'connector1/group4'.
            # Note the use of the scalar reference using the backslash.
            group3 => {
                subgroup3 => \'connector1/group4',
            },

        };
        
        # pass original args, appended with a comment string for the commit
        $self->commit( $cfg, $args );
    }

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

commit CFGHASH[, ARGS]

ARGS is a ref to a named-parameter list (e.g. HASH) that may contain the following keys to override the instance defaults:

    author_name, author_mail, comment, commit_time

_mknode LOCATION

A reference to the node at the LOCATION is returned.

_findobjx LOCATION [, VERSION ]

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

In most cases, the "_findobj" version is sufficient. This extended version is used to look at the attribtes of the directory entry for things like whether the blob is a symlink.

_findobj LOCATION [, VERSION ]

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

_get_sect_key LOCATION

_which( NAME, DIR ... )

_read_config_path SELF, FILENAME, CFGREF, PATH

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

_debugtree( OBJREF | SHA1 )

hdump