NAME

Pitonyak::ConfigFileParser - Handle a configuration file.


SYNOPSIS

use Pitonyak::ConfigFileParser;

my $cfg = new Pitonyak::ConfigFileParser();
$cfg->read_config_file('./modules/sample.cfg');
print 'keys = ('.join(', ', $cfg->get_keys()).")\n";


DESCRIPTION

One might argue that this is nothing more than a light wrapper to read a configuration file into a hash. The read_config_file method() is pretty smart at processing the file to increase ease of use.

The configuration/properties file contains lines of the form:

<left hand side> = <right hand side>

The following parsing rules are used:

Blank lines are ignored.
# is a comment character.
Replace ${key} with the key value in the hash.
The equal sign separates the keys from the values.
leading and trailing space is removed.
space around the equal sign is removed.
Use a backslash as the escape character.

Use the escape character to insert special characters such as the comment, $, character, equal sign, leading or trailing space, or an escape character. Escaping characters with no special meaning, such as an 'a', evaluates to the character 'a'.

You can prevent substitution of ${key} text by using \${key}. Substitution is done before escape characters are removed. So,the sequence ${\key} looks to see if there is a key named '\key' for replacement.

Consider the following configuration:

file_base = ./files/
partner = john
${partner}.loc = ${file_base}${partner}/

This is equivalent to

file_base = ./files/
partner = john
john.loc = ./files/john/


Copyright

Copyright 1998-2009 by Andrew Pitonyak

More reworked code from Andrew's library. As with most of my code libraries, the code is free as free can be.

clear

$cfg->clear()

Clear the entire configuration hash.

clear_key_value

$cfg->clear_key_value('key_text')

Clear the specified key so that it is no longer in the configuration hash.

config_name

The config_name is the name of the configuration file with the file extension. The full file name is built by concatenating config_path() and config_name(). The extension is not assumed because it might be '.cfg' or '.properties'.

config_name()

Return the default file name with file extension.

$cfg->config_name()

Return the base configuration file name.

$cfg->config_name(file_name)

Set the file name with extension, used for the next read.

config_path

The config_path identifies the directory containing the file. The full file name is built by concatinating config_path() and config_name().

config_path()

Return the default path during initialization, which is './'.

$cfg->config_path()

Return the the path to the next configuration file to read. Reading a configuration file with a fully specified file name does not cause the path or the file name to be set.

$cfg->config_path(path)

Set the path for the configuration file, which will be used for the next read operation if the file name is not specified. If the provided path does not contain '/' or '\', then '/' is appended to to the path. The path itself is not checked for validity.

If the provided path is an empty string, then the path is set to the default value.

copy

copy($config_object)

Make a copy of one ConfigFileParser into another

$obj1-copy($obj2)> is the same as $obj1 = $obj2. The receiving ConfigFileParser is closed first.

contains_key

$cfg->contains_key(key_name)

Return 1 if the hash contains the key name and 0 otherwise.

get_class_attribute

The get_class_attribute method utilizes the fact that $obj->method(@parms) is the same as method($obj, @parms). This method does not perform type checking to verify that this is true.

The get_class_attribute method is rarely called directly.

Pitonyak::ConfigFileParser::get_class_attribute($attribute_name)

With only one paramter, the first parameter is assumed to be an attribute name and the default attribute value is returned.

$obj->get_class_attribute($attribute_name)

With two arguments, the first is assumed to be a ConfigFileParser object and the second is assumed to be an attribute name. The attribute value for the object is returned.

$obj->get_class_attribute($attribute_value, $attribute_name)

With three arguments, the first is assumed to be the object, the second is a new attribute value, and the third is the attribute name to set. Although the order seems odd, this is intentional.

Consider the method is_ok defined as return get_class_attribute( @_, 'is_ok' );

Remember that @_ refers to the argument list passed to the method. In all cases, the last argument passed to get_class_attribute is the attribute name. If the method is called directly, this is the only argument.

get_config_full_name

$cfg->get_config_full_name()

Build and return the full path to the configuration file. Remember that $cfg->config_path() returns a string with a trailing '/', so the value returned is equivalent to:

$cfg->config_path().$cfg->config_name()

get_hash_ref

$cfg->get_hash_ref()

Return a reference to the hash containing the properties. For example, to obtain the value for the key 'peter', you can use $cfg->get_hash_ref()->{'peter'} or $cfg->get_value('peter').

get_keys

$cfg->get_keys()

Return the keys in the hash as an array. This is equivalent to keys(%{$cfg->get_hash_ref()}).

get_value

$cfg->get_value('key')

Return the property value for the specified key. To obtain the value for the key 'peter', you can use $cfg->get_hash_ref()->{'peter'} or $cfg->get_value('peter').

get_value_default

$cfg->get_value_default('key')

This version is identical to $cfg->get_value_default('key'), except that it returns an empty string if the key does not exist.

$cfg->get_value_default('key', 'default')

If the property exists, return the value. If the property does not exist, return the specified default value.

get_delimited_values

$cfg->get_delimited_values('key')

Omitting the delimiter is the same as calling $cfg->get_delimited_values('key', ',').

$cfg->get_delimited_values('key', 'delimiter')

Extract the specified key from the configuration item. Assume that the key contains a list of items delimited with the specified delimiter. Leading and trailing spaces are removed. All of the values are returned as an array.

new

$cfg_copy = $cfg->new()

Generate a new copy of a configuration object.

read_config_file

Read a config/properties file from disk and populate this object. The current object is cleared reading the file. Any current values are over-written.

$cfg->read_config_file()

The directory and name must be set using config_path() and config_name(). get_config_full_name() is used to build the full path.

$cfg->read_config_file('full_path_to_file')

Neither config_path() nor config_name() are updated.

set_key_value

$cfg->set_key_value(key, value)

Set the specified key to the specified value.


Private Methods

initialize

initialize()

The initialize() method is called automatically when an object is created. The new method also calls initialize() directly

Initialize the data structure by copying values from the initial attributes hash into the newly created object. Finally, set the read properties hash to an empty reference.