NAME
Parse::PlainConfig - Parser for plain-text configuration files
MODULE VERSION
$Id: PlainConfig.pm,v 1.7 2002/10/08 19:04:59 corliss Exp corliss $
SYNOPSIS
use Parse::PlainConfig;
$conf = new Parse::PlainConfig;
$conf = Parse::PlainConfig->new('DELIM' => '=', 'FILE' => '.myrc',
'PURGE' => 1);
$conf->purge(1);
$conf->purge;
$conf->delim('=');
$rv = $conf->read('myconf.conf');
$rv = $conf->read;
$conf->write('.myrc', 2);
@directives = $conf->directives;
$conf->set(KEY1 => 'foo', KEY2 => 'bar');
$conf->describe(KEY1 => '# This is foo', KEY2 => '# This is 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.
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. Please note, however, that you still cannot do the following:
# INCORRECT
FOO: \
BarEvery directive/value pair must start with a key and some part of the value on the first line of the assignment.
If any directive 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 directives and associated 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',
'PURGE' => 1);The object constructor can be called with or without arguments. The only recognised arguments are DELIM, which specifies the directive/value delimiter to use in the files, FILE, which specifies a file to read, PURGE, which sets the mode of the auto-purge feature, and FORCE_SCALAR, which forces the specified directives to be read and stored as scalars. The PURGE argument will cause the object to automatically read and parse the file if possible.
purge
$conf->purge(1);
$conf->purge;This method either (re)sets the auto-purge mode, or performs an immediate manual purge. Auto-purge mode clears the configuration hash each time a configuration file is read, so that the internal configuration data consists solely of what is in that file. If you wanted to combine the settings of multiple files that each may exclusively hold some directives, setting this to 'off' will load the combined configuration as you read each file.
You can still clobber configuration values, of course, if the same directive is defined in multiple files. In that case, the last file's value will be the one stored in the hash.
This is set to 0, or 'off', by default.
delim
$conf->delim('=');This method gets and/or sets the directive/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 directive/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.
directives
@directives = $conf->directives;This method returns a list of all the names of the directives currently stored in the configuration hash.
set
$conf->set(KEY1 => 'foo', KEY2 => 'bar');The set method takes any number of directive/value pairs and copies them into the internal configuration hash.
describe
$conf->describe(KEY1 => '# This is foo', KEY2 => '# This is bar');The describe method takes any number of key/description pairs which will be used as comments preceding the directives in any newly written conf file. If you do not precede each line with comment characters ('#') this method will insert them for you. However, it will not split lines longer than the display into multiple lines.
get
$field = $conf->get('KEY1');
($field1, $field2) = $conf->get(qw(KEY1 KEY2));The get method takes any number of directives 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 directives as read from the file. If called with a list as an argument, it will set the directive order with that list. This method is probably of limited use except when you wish to control the order in which directives are written in new conf files.
Please note that if there are more directives 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)