NAME
Parse::PlainConfig - Parser for plain-text configuration files
MODULE VERSION
$Id: PlainConfig.pm,v 1.2 2002/01/31 11:00:05 corliss Exp $
SYNOPSIS
use Parse::PlainConfig;
$conf = new Parse::PlainConfig;
$conf = Parse::PlainConfig->new('DELIM' => '=', 'FILE' => '.myrc');
$conf->delim('=');
$rv = $conf->read('myconf.conf');
$rv = $conf->read;
$conf->write('.myrc', 2);
$conf->set(KEY1 => 'foo', KEY2 => 'bar');
$field = $conf->get('KEY1');
($field1, $field2) = $conf->get(qw(KEY1 KEY2));
@order = $conf->order;
$conf->order(@new_order);
$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 => 1993As 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.
If any key is present in the file without a corresponding value, it will be omitted from the hash. In other words, if you have something like the following:
BLANK_KEY:it will not be stored in the configuration hash.
All keys and values will have both leading and trailing whitespace stripped from them before being stored in the configuration hash. Whitespace is allowed within both.
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.
SECURITY
WARNING: This parser will attempt to open what ever you pass to it for a filename as is. If this object is to be used in programs that run with permissions other than the calling user, make sure you sanitize any user-supplied filename strings before passing them to this object.
METHODS
new
$conf = new Parse::PlainConfig;
$conf = Parse::PlainConfig->new('DELIM' => '=', 'FILE' => '.myrc');The object constructor can be called with or without arguments. The only recognised arguments are DELIM, which specifies the key/value delimiter to use in the files, and FILE, which specifies a file to read. The latter argument will cause the object to automatically read and parse the file if possible.
delim
$conf->delim('=');This method gets and/or sets the key/value delimiter to be used in the conf files. The default delimiter is ':'. This can be multiple characters.
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 successfulYou'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
$conf->write('.myrc', 2);This method writes the current configuration stored in memory to the specified file, either specified as the first argument, or as stored from an explicit or implicit read call.
The second argument specifies what kind of whitespace padding, if any, to use with the key/value delimiter. The following values are recognised:
Value Meaning
================================================
0 No padding (i.e., written as KEY:VALUE)
1 Left padding (i.e., written as KEY :VALUE)
2 Right padding (i.e., written as KEY: VALUE)
3 Full padding (i.e., written as KEY : VALUE)Both arguments are optional.
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.
order
@order = $conf->order;
$conf->order(@new_order);This method returns the current order of the configuration keys as read from the file. If called with a list as an argument, it will set the key order with that list. This method is probably of limited use except when you wish to control the order in which keys are written in new conf files.
Please note that if there are more keys than are present in this list, those extra keys will still be included in the new file, but will appear in alphabetically sorted order at the end, after all of the keys present in the list.
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.
error
warn $conf->error;This method returns a zero-length string if no errors were registered with the last operation, or a text message describing the error.
HISTORY
None worth noting. ;-)
AUTHOR/COPYRIGHT
(c) 2002 Arthur Corliss (corliss@digitalmages.com)