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

Copyright (c) 2000, 2001, Grant Mongardi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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

Private