NAME

CfgTie::Cfgfile -- An object to help interface to configuration files

SYNOPSIS

Helps interface to the text based configuration files commonly used in Unix

DESCRIPTION

This is a fairly generic interface to allow many configuration files to be used as hash ties. Note: This is not intended to be called by user programs, but by modules wishing to reuse a template structure!

   package mytie;
   require CfgTie::Cfgfile;

   @ISA = qw(CfgTie::Cfgfile);

The major methods:

new($filepath, @Extra stuff)

new($RCS-Object, @Extra stuff)

filepath: If defined, this is the path to the configuration file to be opened.
RCS-Object: If defined, this is an RCS object (or similar) that will control how to check in and check out the configuration file. See RCS Perl module for more details on how to create this object (do not use the same instance for each configuration file!). Files will be checked back in when the END routine is called. If a filepath is specified, it will override the one previously set with the RCS object. If no filepath is specified, but the RCS has one specified, it will be used instead.

The derived object

Your derived object may need to provide the following methods:

scan: This is called when the file is first tied in. It should scan the file, placing the associated contents into the {Contents} key.
format(key,contents): This formats a single entry to be stored in a file. This is used for when a value can be stored simply.
cfg_begin: If this method is defined, it is called just before the configuration file will be modified.
cfg_end: If this method is defined, it is called after the configuration file has changed. It can be used, for instances, to rebuild a binary database, restart a service, or email Martians.
makerewrites: This is called just before the configuration file will be rewritten. It should return a reference to a function that is used to transform the current control file into the new one. This transforming function is called for each line in the configuration file while it is being rewritten.

Object methods you can use

Comment_Add This appends the string to the list of comments that will be logged for this revision (assuming that a Revision Control object was used).

Queue_Store($key,$val) This queues (for later) the transaction that key should be associated with val. The queue is employed to synchronize all of the settings with the stored settings on disk.

Queue_Delete($key) This queues (for later) the transaction that any value associated with key should be removed.

RENAME(\%rules) This method will move through the whole table and make a series of changes. It may:

Remove some entries, based upon their keys
Rename the keys from some entries
Change the contents of the keys, possibly removing portions

\%rules is the set of rules that governs will be changed in name and what will be removed. It is an associative array (hash) of a form like:

        {
            PATTERN1 => "",
            PATTERN2 => REWRITE,
        }

PATTERN1 = Two things will happen with a rule like this:

Every key in the table that matches the pattern will be removed
Any element (of an entry) that matches the pattern will be removed

PATTERN2 = REWRITE In this case the rewrite indicates what should replace the pattern:

Every key that matches the pattern will be rewritten and replace with a new key.
Any element (of an entry) that matches the pattern will be modified to match the rewrite rule.

Caveats

Additions that do not change any previously established values are reflected immediately (and newaliases is run as appropriate). Anything which changes a previously established value, regardless of whether or not it has been committed, are queue'd for later. This queue is used to rewrite the file when END is executed.

Author

Randall Maas (mailto:randym@acm.org, http://www.hamline.edu/~rcmaas/)

C -- An object to help interface to configuration files