NAME

ZConf - an interface to Zeus configuration files


SYNOPSIS

   use ZConf;

   # load a configuration file into memory

   $file = "$ENV{ZEUSHOME}/webadmin/conf/sites/server";
   $zc = new ZConf();
   $zc->load( $file );

   # Read values from the loaded configuration file

   $port = $zc->get('port');
   print "Port number is : $port\n";

   $htaccess = $zc->get('modules!htaccess!enabled');
   print "htaccess module enabled\n" if $htaccess eq 'yes';

   # Insert or change a key-value

   # add a new key/value pair
   $zc->add( 'my!new!key', '73' );
   # set the canonical hostname of this server to 'localhost'
   $zc->add( 'ip_name', 'localhost' );

   # Listing the next level of the key hierarchy
   # matching the given prefix

   @list = $zc->list('modules!mime!types');

   # Test whether a given key/branch exists
   # ( get will return "" for no value and when the key does not exist )

   $zc->exists( $key );

   # removing a key or branch

   $zc->delete( $key );

   # write the configuration file to disk

   $zc->save( $config_file );

   e.g. to add a mime type for .something files
        but only if the something module is enabled

   $zc = new ZConf;

   $zc->load( $config_file ) or die "Could not open configuration file";

   $val = $zc->get('module!something!enabled');

   if ( $val =~ /y/ ) {  # enabled
      $zc->add('modules!mime!types!something', 'application/x-something');
   }

   $val = $zc->save( $config_file );

   $zc = undef;


DESCRIPTION

This module provides an interface to easily access Zeus configuration files. i.e. those in the same format as $ZEUSHOME/webadmin/conf/sites/*

It is normally found in $ENV{ZEUSHOME}/admin/etc/ which you will need to add to your @INC array if you are not using the miniperl binary shipped with Zeus.

The Exporter module is not used so the full package names of methods should be specified.

These files consist entirely of one line, whitespace separated key-value pairs, although the value may be a null string. The keys are arranged in a hierarchy with levels separated by '!'.

e.g. modules!fastcgi!enabled no

Where the 'modules' prefix indicates that this is associated with a module. 'modules!fastcgi' indicates the FastCGI module. The complete key 'modules!fastcgi!enabled' points to 'no', the FastCGI module is not enabled.

If the first character of a line is '#' then it is treated as a comment.

When reading a value from a configuration file you must specify the filename and load that file into a ZConf object in memory. The load method will return undef if the file cannot be loaded.

Use the get method to read values specifying the full key. If the key is not present or the value is blank this will return a null string. The object is not tied to the configuration file so you will need to load the file again if the memory copy is old.

To add or modify values you must first make sure you have a fresh copy of the file loaded. No locks are held so try to minimize the time spent between loading the file and writing it back. Use the add method to add or set values. The delete method can be used to delete keys-value pairs.

Once modifications are complete overwrite the original file using the save method.


Functions

new ZConf([$filename]);

e.g. $zc = new ZConf(``$ENV{ZEUSHOME}/admin/website'');

Create a new ZConf object. Optionally set the filename of the configuration file it is associated with. This is placed in $self->{filename}. The file is not automatically loaded.

The new object will also store a copy of the configuration file in $self->{file} once it has been loaded.

$self->{file} and $self->{filename} are internal values.

$zc->load([$filename]);

Load the file specified by $filename into an internal variable. The contents of the file is also returned. If this function fails the stored value is undefined and the return value is undef. The name of the last file loaded is remembered.

$zc->get($key);

Extract the value associated with this key. If the loaded file is undefined this returns undef. If the key does not exist or has no value a null string is returned. Otherwise the value (The remainder of the line following the whitespace after the key) is returned. If duplicate keys are present only the first value is returned. Only complete key matches count. 'modules' will not match 'modules!cgi'.

$zc->exists( $key );

If the key is found exactly or as a prefix returns true. Otherwise returns false. This is used in addition to get() as get does not differentiate between a null value and a nonexistent key.

$zc->list( $prefix );

This is used to list the next level of a subtree of keys

  e.g. $zc->list( $prefix )

  will return

  access
  cgi
  dirlist ... etc

It will not return whole multilevel branches. Duplicate items will be made unique. Exact matches are not counted.

$zc->add( $key, $value );

Used to set a key value pair. If the key already exists the value is overwritten. Otherwise the pair is appended.

The changes made only affects the copy in memory. The file must be saved for the changes to be committed.

Values cannot contain the ``\n'' new line character. If required it should be encoded in some manner defined by the application using the information.

Keys may not start with a '#' as this is the comment character at the start of lines.

Only minimal changes are made to the file. It is not completely reordered and comments are not stripped.

If the key is added successfully returns true, otherwise (e.g. due to restrictions on allowable characters) returns false.

$zc->delete( $key );

Deletes all lines in a file matching the given key or key prefix.

$zc->flatten();

Returns a string containing the memory copy of the config file which the object represents.

$zc->save( $filename );

Saves the memory copy of the file to the specified location or, by default, to the previously loaded file's name.

This is done by writing a temporary file and moving it over the target file.