Pitonyak::ConfigFileParser - Handle a configuration file.
use Pitonyak::ConfigFileParser;
my $cfg = new Pitonyak::ConfigFileParser();
$cfg->read_config_file('./modules/sample.cfg');
print 'keys = ('.join(', ', $cfg->get_keys()).")\n";
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:
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 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.
$cfg->clear()
Clear the entire configuration hash.
$cfg->clear_key_value('key_text')
Clear the specified key so that it is no longer in the configuration hash.
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.
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($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.
$cfg->contains_key(key_name)
Return 1 if the hash contains the key name and 0 otherwise.
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.
$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->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').
$cfg->get_keys()
Return the keys in the hash as an array.
This is equivalent to
keys(%{$cfg->get_hash_ref()}).
$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').
$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.
$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.
$cfg_copy = $cfg->new()
Generate a new copy of a configuration object.
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.
$cfg->set_key_value(key, value)
Set the specified key to the specified value.
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.