Parse::PlainConfig(3pm) 				User Contributed Perl Documentation				   Parse::PlainConfig(3pm)

NAME

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

MODULE VERSION

       $Id: PlainConfig.pm,v 2.06 2008/07/07 22:59:35 acorliss Exp $

SYNOPSIS

	 use Parse::PlainConfig;

	 $conf = new Parse::PlainConfig;
	 $conf = Parse::PlainConfig->new(
	   'PARAM_DELIM' => '=',
	   'FILE'	 => '.myrc',
	   'MAX_BYTES'	 => 65536,
	   'SMART_PARSER => 1,
	   );

	 $conf->property(PARAM_DELIM => '=');

	 $rv = $conf->read('myconf.conf');
	 $rv = $conf->read;
	 $rv = $conf->readIfNewer;
	 $conf->write('.myrc', 2);

	 $conf->purge;

	 @parameters = $conf->parameters;
	 $conf->parameter(FOO => "bar");
	 $value = $conf->parameter(FOO);
	 $conf->describe(FOO => 'This is foo');
	 $conf->coerce("string", qw(FOO BAR));

	 @order = $conf->order;
	 $conf->order(@new_order);

	 $errstr = Parse::PlainConfig::ERROR;

	 $rv = $conf->hasParameter('FOO');

       The following methods are only supported for backwards compatibility reasons.  They will likely be removed at some point in the future.

	 # Use of the tags DELIM and PURGE are deprecated in favour of
	 # PARAM_DELIM, LIST_DELIM, HASH_DELIM, and AUTOPURGE
	 $conf = Parse::PlainConfig->new(
	   'DELIM' => '=',
	   'PURGE' => 1,
	   );

	 # As is the delim method since it works only on the tag delimiter
	 $conf->delim('=');

	 # Auto-purge should be enabled/disabled via the property method
	 $conf->purge(1);

	 # directives is replaced with parameters
	 @directives = $conf->directives;

	 # get/set methods are replaced with a unifed parameter method
	 $field = $conf->get('KEY1');
	 ($field1, $field2) = $conf->get(qw(KEY1 KEY2));
	 $conf->set(KEY1 => 'foo', KEY2 => 'bar');

	 # This was just a really bad idea to begin with, plus it's
	 # effective broken at this point (only returns a copy of the
	 # internal hash now, so it's effectively read-only)
	 $hashref = $conf->getRef;

	 # This is just a wrapper for the class function
	 $errstr = $conf->error

REQUIREMENTS

       o   Paranoid

       o   Text::ParseWords

       o   Text::Tabs

DESCRIPTION

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

FILE SYNTAX

   TRADITIONAL USAGE
       The plain parser supports the reconstructions of relatively simple data structures.  Simple string assignments 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.

       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.

       In traditional mode (meaning no parameters are set to be coerced into a specific datatype) one must encapsulate list and hash delimiters
       with quotation marks in order to prevent the string from being split and stored as a list or hash.  Quotation marks that are a literal part
       of the string must be backslashed.

   SMART PARSER
       The new parser now provides some options to make the file syntax more convenient.  You can activate the smart parser by setting
       SMART_PARSER to a true value during object instantiation or via the property method.

       With the traditional parser you had to backslach the end of all preceding lines if you wanted to split a value into more than one line:

	 FOO:  This line starts here 
	       and ends here...

       With the smart parser enabled that is no longer necessary as long as the following lines are indented further than the first line:

	 FOO:  This line starts here
	       and ends here...

       Note:  The indentation is compared by byte count with no recognition of tab stops.  That means if you indent with spaces on the first line
       and indent with tabs on the following it may not concantenate those values.

       Another benefit of the smart parser is found when you specify a parameter to be of a specific datatype via the COERCE hash during object
       instantiation or the coerce method.  For instance, the traditional parser requires you to encapsulate strings with quotation marks if they
       contain list or hash delimiters:

	 Quote:  ""It can't be that easy," he said."

       Also note how you had to escape quotation marks if they were to be a literal part of the string.  With this parameter set to be coerced to
       a scalar you can simply write:

	 Quote:  "It can't be that easy," he said.

       Similarly, you don't have to quote hash delimiters in parameters set to be coerced into lists.  Quotation marks as part of an element value
       must be escaped, though, since unescaped quotation marks are assumed to encapsulate strings containing list delimiters you don't want to
       split on.

       Note: The previous versions of Parse::PlainConfig did not allow the user to set keys like:

	 FOO: 
	     bar

       or save empty assignments like

	 FOO:

       This is no longer the case.  Both are now valid and honoured.

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.

       This also uses a blocking b<flock> call to open the file for reading and writing.

FUNCTIONS

   Parse::PlainConfig::ERROR
METHODS

   new
	 $conf = new Parse::PlainConfig;
	 $conf = Parse::PlainConfig->new(
	   'PARAM_DELIM' => '=',
	   'FILE'	 => '.myrc',
	   'MAX_BYTES'	 => 65536,
	   'SMART_PARSER => 1,
	   );

       The object constructor can be called with or without arguments.	Arguments available for use include:

	 Argument	 Default    Purpose
	 =============================================================
	 ORDER		 []	    Specifies specific order of
				    fields to be used while writing
	 FILE		 undef	    Filename for read/write ops
	 PARAM_DELIM	   ':'	      Field/value delimiter
	 LIST_DELIM	 ','	    List delimiter within field values
	 HASH_DELIM	 '=>'	    Hash key/value delimiter within
				    field values
	 AUTOPURGE	 0	    Autopurge enabled/disabled
	 COERCE 	 {}	    Field coercion hash
	 DEFAULTS	 {}	    Default field values
	 SMART_PARSER	 0	    Smart parser enabled/disabled
	 MAX_BYTES	 16384	    Integer denoting maximum bytes
				    to read in any given file

       DELIM, PURGE, and  FORCE_SCALAR are still available for backwards compatibility, but may be removed in the future.  One should use
       PARAM_DELIM AUTOPURGE, and COERCE instead.

       COERCE is a hash of field name/data type pairs.	If a field is listed in this hash then their values will always be returned in the
       requested format of either string, list, or hash.  Any field coerced to string, for instance, will ignore list and hash delimiters and
       assume the entire value will always be string value.

       DEFAULTS is a hash of field name/value pairs.  This ensures that even if a field is not explicitly set (either in a conf file or
       programmatically) a default value can still be retrieved.

       SMART_PARSER removes the need to backslash end-of-lines to continue the value onto the next.  If the following line is indented further
       than the tag was it will automatically assume that the next line is a continuation of the previous.  It also affects the need to
       encapsulate coerced datatypes with quotation marks for irrelevant delimiters.

       AUTOPURGE erases all stored parameters and values before reading a file.  This does not, however, erase any values set for ORDER.

   property
	 $conf->property(PARAM_DELIM => '=');

       This method sets or retrieves the specified property.  Please note that this overwrites the current value, even for those properties that
       are references to lists and hashes.

       If you're using this to set a property it will return a boolean true or false depending on the success of the operation.  If you're just
       retrieving a property it will return the value of the property.	If you ask for a nonexistent property it will croak.

   purge
	 $conf->purge(1);
	 $conf->purge;

       NOTE:  Use of this method to set the purge mode is deprecated and will be removed in the future.  For that please use the property method
       instead.

       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 does not clear the order or coerce properties.

       Autopurge mode is disabled by default.

   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.

       You'll notice that you can also call the read method without an argument.  The name of the file read is stored internally, and if already
       set to a valid value (either by a previous call to read with a filename argument or by setting the FILE property) this will read that
       file's contents.

       The return value will be one if the file was successfully read and parsed, or zero otherwise.  The reason for failure can be read via
       Parse::PlainConfig::ERROR.

       This function will cause the program to croak if called without a filename ever being defined.

   readIfNewer
	 $rv = $conf->readIfNewer;

       This method is used to reread & parse the file only if the mtime appears newer than when last read.  If the file was successfully reread or
       appears to be the same it will return true.  Any errors will be stored in Parse::PlainConfig::ERROR and it will return a false value.

       You can determine whether or not the file was read by the true value.  If it was re-read it will return 1.  If the file appears to be the
       same age it will return a 2.

   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.

   parameters
	 @parameters = $conf->parameters;

       This method returns a list of all the names of the directives currently stored in the configuration hash in no particular order.

   parameter
	 $value = $conf->parameter('SCALAR1');
	 @values = $conf->parameter('LIST1');
	 %values = $conf->parameter('HASH1');
	 $conf->parameter('SCALAR1', "foo");
	 $conf->parameter('LIST1', [qw(foo bar)]);
	 $conf->parameter('HASH1', { foo => 'bar' });

       This method sets or retrieves the specified parameter.  Hash and list values are copied and returned as a list.	If the specified parameter
       is set to be coerced into a specific data type the specified value will be converted to that datatype.	This means you can do something
       like:

	 # SCALAR1 will equal "foo , bar , roo" assuming LIST_DELIM is set to ','
	 $conf->coerce(qw(string SCALAR1));
	 $conf->parameter('SCALAR1', [qw(foo bar roo)]);

	 # SCALAR1 will equal "foo => bar : roo => ''" assuming HASH_DELIM is set
	 # to '=>' and LIST_DELIM is set to ':'
	 $conf->parameter('SCALAR1', { 'foo' => 'bar', 'roo' => '' });

       In order for conversions to be somewhat predictable (in the case of hashes coerced into other values) hash key/value pairs will be assigned
       to string or list portions according to the alphabetic sort order of the keys.

   coerce
	 $conf->coerce("string", "FOO", "BAR");

       This method configures the parser to coerce values into the specified datatype (either string, list, or hash) and immediately convert any
       existing values and store them into that datatype as well.

   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.  You are responsible for prepending a comment character to each line, as well as splitting along your desired text width.

   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.

   hasParameter
	 $rv = $conf->hasParameter('FOO');

       This function allows you to see if a parameter has been defined or has a default set for it.  Returns a boolean value.

DEPRECATED METHODS

   delim
	 $conf->delim('=');

       This method gets and/or sets the parameter name/value delimiter to be used in the conf files.  The default delimiter is ':'.  This can be
       multiple characters.

   directives
	 @directives = $conf->directives;

       This method returns a list of all the names of the directives currently stored in the configuration hash in no particular order.

   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.

   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.

   get_ref
	 $href = $conf->get_ref

       Note:  This used to give you a reference to the internal configuration hash so you could manipulate it directly.  It now only gives you a
       copy of the internal hash (actually, it's reconstructed has to make it look like the old data structure).  In short, any changes you make
       to this hash will be lost.

   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.

DIAGNOSTICS

       Through the use of Paranoid::Debug this module will produce internal diagnostic output to STDERR.  It begins logging at log level 7.  To
       enable debugging output please see the pod for Paranoid::Debug.

HISTORY

	 2002/01/18:  Original public release (v1.1)
	 2006/05/26:  Complete rewrite (v2.0)

AUTHOR
/COPYRIGHT
       (c) 2002 Arthur Corliss (corliss@digitalmages.com)

perl v5.10.0							    2008-07-07						   Parse::PlainConfig(3pm)