Public
Private

NAME

Config::DynaConf - This class provides an interface to a hash of information read from a configuration file. The module is written to be used with various types of files, including '.ini', '.properties', and the 'DynaConf' native format.

SYNOPSIS

	use Config::DynaConf;
	my $cfg = Config::DynaConf->new( -file => $cfgfile, -section => $useSec,
							 -JoinLines => "yes" );
	my $obj = Config::DynaConf->new([$cfgfile[, $useSec]]); # see below for parameter descriptions

	$obj->joinLines(); # strips embedded newlines from HERE documents
	$value = $obj->get($key); # returns scalar value for hash key
	@keys = $obj->getKeys(); # returns an array of all of the hash keys
	$value = $obj->_Var_Name(); # Shortcut to 'Dyna-Safe' variables (AUTOLOADed)
	$value = $obj->{$key}; # allow direct access to the $key value;
	if ( $obj->exists($key) ) ... # returns a 1 or 0 for 'true' or 'false', respectively
	if ( $obj->defined($key) ) ... # returns a 1 or 0 for 'true' or 'false', respectively

DESCRIPTION

Copyright

DynaConf.pm,v 0.70 2001/11/16 wizard@neonedge.com

General

This class provides an interface to variables defined by a user configuration file. All of these variables are stored in an anonymous hash, and accessed by either member functions or directly ($obj->{$hash_key}).

Library source viewable at <http://www.neonedge.com/perl_tools/Config/DynaConf.pm.txt>

Example program available at <http://www.neonedge.com/cgi-bin/DynaMe.pl>

Download compressed package at <http://www.neonedge.com/perl_tools/Config/Config-DynaConf-0.07.tar.gz>

This document available at <http://www.neonedge.com/perl_tools/Config/index.html>

The user-defined information is specified in the file location passed to the new() function, or in the default conf file called ``dyn.cfg'' in the current working directory. You can also specify the configuration file by setting the environment variable 'SRC_CFG' to the path/filename of the file. If no configuration file is found, $obj->get('_cfgfile') will return undef. If a '$useSec' value is specified, then the file will be opened and read until a line is found that matches the RegEx /^\[$useSec\]\s*$/, at which point the module will suck up name-value pairs until it sees a line that matches the RegEx /^\[.*\]\s*$/. The 'section name' is stored in the object element '_secname'. If the section specified was not found, then the $obj->exists('_secname') will return false.

File Format

The Configuration File format is as follows:

	# Each key must begin on the first character of the line
	variable_name=value
	undefined_name=
	!_Var_Name=value # special format - see below
	;_Ini_Var=value # special format - see below

	[Section Name]
	... more variables

which results in a $obj->get( 'variable_name' ) returning 'value' or $obj->get( 'undefined_name' ) returning 'undef' or $obj->get( '_Var_Name' ) returning 'value' (*note the stripped '!'). Each configuration directive MUST occur on a line by itself, and cannot include comments. The format for any configuration directive must meet the following requirements:

	$key must begin with A to Z, a to z, 0 to 9, underscore, '-', '!_', or ';_'
	$key or $value should not contain special characters or be reserved keywords
	$key or $value cannot contain embedded newline characters.
	$key must start at the beginning of the line (/^$key/). 
	$key should be explained in the config file header for DynaConf files.

> NOTE: ANY LINE THAT DOES NOT START WITH '#', ' '(space), ';', or '!' IS ASSUMED TO BE A CONFIGURATION DIRECTIVE (or continuation thereof), AND THEREFORE THE OBJECT ATTEMPTS TO SET A DIRECTIVE BY IT, UNLESS THE LINE LENGTH IS LESS THAN 1.

>The one exception to the $key requirements is that if $key begins with '!_' or ';_' followed immediately by one or more Capitalized A to Z characters, followed by any number of other valid capital letters, underscore, or dash, followed by an equals sign, and the $value, then the directive will be stripped of the leading '!' or ';' and set as a key/value pair. These are what I call 'Dyna-Safe' variables and are the only type of variables that can be called as Object methods. The reasoning behind this is so that the programmer can 'hide' the Dyna-Safe variables in the file. This allows DynaConf to embed it's own special variables in .properties and .ini files without confusing Java or Windows. This allows one to have configuration files common to both the Perl application and a Java or Windows program. Example:

	!_My_Key=my_value
	   or
	;_My_Key=my_value

will cause $obj->_My_Key(); to return ``my_value''. whereas:

	!1Mykey=my_value
	!MY_KEY=My_value
	;vMY_KEY=my_value

will all be ignored (treated as comments). Similarly, any other non-'Dyna-Safe' variables will return the method by which it was called. Example:

onEntry=username

will, when called as $obj->onEntry(), return the string 'onEntry'. Please also note that any variable containing special characters such as '.', '$' etc., will cause the application to fail if called as a method, but will work up to the point at which it is called (no run-time error).

NOTE: IF THE CONSTRUCTOR FAILS TO FIND A ``.cfg'' FILE, THEN ``$obj->get('_cfgfile')'' WILL RETURN undef AND ``$obj->defined('_cfgfile')'' WILL RETURN '0'. THIS VALUE SHOULD BE CHECKED ANY TIME YOU ARE EXPECTING THE OBJECT TO CREATE A CUSTOM CONFIGURATION FROM A FILE. Additionally, if you specify a section name and that section is not found within the file that you specified, the variable '_sectname' will also remain undefined.

AUTHOR

Grant M. <wizard@neonedge.com>

Thanks to: Jonathan S. <Address witheld>

KNOWN BUGS AND LIMITATIONS

If you call the autoload object method using a variable name that contains special characters, the call will cause the program to exit immediately without a warning. This is true of any Perl object.

INSTANCE MEMBER METHODS

Public

Class method new()
Answers an instance of class DynaConf. Example:
```
	$c = DyanConf->new([$filename, ['$useSec']]);
	$f = DynaConf->new( -file => "$filename", -section => "$useSec",
			 -JoinLines => "yes" );
	$k = DynaConf->new();
```
where $filename is the name of the file from which to read all of the configuration name-value pairs from, and useSec is the name of an .ini file section from which to grab the name-value pairs. if useSec is not specified, then all name value pairs are sucked-up, which results in duplicate keys being overwritten by the last one listed. If the -JoinLines parameter is specified any HERE document value will be stripped of embedded newlines. If no parameters are passed, it will check for the environment variable SRC_CFG and use that if it exists, or it will assume a file in the current working directory called ``dyn.cfg''.
Class method joinLines()
Allows the caller to remove any embedded newlines from the values of any HERE parameters. This can be used after the Configuration file is read, so that the functionality can be used when passing arguments to new() as an array. It also sets the internal '_JoinLines' variable. Example:
```
	$obj = DyanConf->new( "../etc/conf.cfg" );
	$obj->joinLines(); # remove embedded newlines from HERE documents
```
Class method getKeys()

Allows the caller to retrieve all of the keys that have been defined within this object. This method will always return AT LEAST the _cfgfile variable, although it may be undefined. Example:
@keys = $obj->getKeys();

Class method get('KEY')

Allows the caller to retrieve one of the configuration settings from the object. The caller must pass a directive that is set in the .cfg file (variable_name=) or else the call will return undef. The call returns the value of the directive, or undef if not defined. Example:
$serverName = $obj->get('Server');

Class method exists('KEY')

Allows the caller to determine if a variable has been initialized within the object. This will return true even if the variable is equal to an empty string or undef. Use the 'defined' function to see if it has a value. Example:
$bool = $obj->exists('MY_VAR');

Class method defined('KEY')

Allows the caller to determine if a variable has been defined within the object hash. This will return true only if the variable exists and is not equal to an empty string or undef. Example:
$bool = $obj->defined('MY_VAR');

Class methods $KEY_NAME()

Allows the caller to retrieve any 'Dyna-Safe' variable by simply calling the variable as a subroutine. The definition of a 'Dyna-Safe' variable in the context of this module is any varaible that meets the RegEx of /^_[a-zA-Z]+[a-zA-Z_\-0-9]+/. This includes the '_cfgfile', '_section', and '_JoinLines' variables. Example:
$bin = $obj->_binDir(); # in the config file as "_binDir=/directory/path"

Private

Instance method _initialize()

Perform internal initialization(s).

Instance method _initini()

Perform internal initialization(s) by section.