/ 
ParsePlainConfig-1.1
/ Parse::PlainConfig

NAME

Parse::PlainConfig - Parser for plain-text configuration files

MODULE VERSION

$Id: PlainConfig.pm,v 1.1 2002/01/18 07:08:28 corliss Exp corliss $

SYNOPSIS

use Parse::PlainConfig;

$conf = new Parse::PlainConfig;

$rv = $conf->read('myconf.conf');
$rv = $conf->read;

$conf->set(KEY1 => 'foo', KEY2 => 'bar');
$field = $conf->get('KEY1');
($field1, $field2) = $conf->get(qw(KEY1 KEY2));

$hashref = $conf->get_ref;

REQUIREMENTS

Nothing outside of the core Perl modules.

DESCRIPTION

Parse::PerlConfig provides OO objects which can parse and generate human-readable configuration files.

NOTE: The write method is not yet implemented, but will be available with the next revision.

FILE SYNTAX

The plain parser supports the reconstructions of relatively simple data structures. Simple scalar assignment and one-dimensional arrays and hashes are possible. Below are are various examples of constructs:

# Scalar assignment
FIRST_NAME: Joe
LAST_NAME: Blow

# Array assignment
FAVOURITE_COLOURS: red, yellow, green
ACCOUNT_NUMBERS:  9956-234-9943211, \
		  2343232-421231445, \
		  004422-03430-0343

# Hash assignment
CARS:  crown_vic => 1982, \
       geo => 1993

As the example above demonstrates, all lines that begin with a '#' (leading whitespace is allowed) are ignored as comments. if '#" occurs in any other position, it is accepted as part of the passed value. This means that you cannot place comments on the same lines as values.

The above example also shows that escaping the end of a line (using '\' as the trailing character) allows you to assign values that may span multiple lines.

Note: If you wish to use a hash or list delimiter ('=>' & ',') as part of a scalar value, you must enclose that value within quotation marks. If you wish to preserve quotation marks as part of a value, you must escape the quotation characters.

METHODS

new

$conf = new Parse::PlainConfig;

The object constructor requires no arguments.

read

$rv = $conf->read('myconf.conf');
$rv = $conf->read;

The read method is called initially with a filename as the only argument. This causes the parser to read the file and extract all of the configuration directives from it. The return value will have one of five values, depending on the success or type of error encountered:

RV     Meaning
==============================================
-3     filename never defined
-2     file does not exist
-1     file is unreadable
0      some other error occurred while reading
1      read was successful

You'll notice that you can also call the read method without an argument. This is only possible after calling the read method with a filename. The name of the file read is stored internally, and can be reread should you need to restore your configuration hash. If you call the read method without having defined that filename at least once, you'll get a return value of -3.

write

Not yet implemented.

set

$conf->set(KEY1 => 'foo', KEY2 => 'bar');

The set method takes any number of key/value pairs and copies them into the internal configuration hash.

get

$field = $conf->get('KEY1');
($field1, $field2) = $conf->get(qw(KEY1 KEY2));

The get method takes any number of keys to retrieve, and returns them. Please note that both hash and list values are passed by reference. In order to protect the internal state information, the contents of either reference is merely a copy of what is in the configuration object's hash. This will not pass you a reference to data stored internally in the object. Because of this, it's perfectly safe for you to shift off values from a list as you process it, and so on.

get_ref

$hashref = $conf->get_ref;

This method is made available for convenience, but it's certainly not recommended that you use it. If you need to work directly on the configuration hash, though, this is one way to do it.

HISTORY

None worth noting. ;-)

AUTHOR/COPYRIGHT

(c) 2002 Arthur Corliss (corliss@digitalmages.com)