Provided by: libparse-plainconfig-perl_3.05-1_all bug


       Parse::PlainConfig::Legacy - Parsing engine Legacy for Parse::PlainConfig


       $Id: lib/Parse/PlainConfig/, 3.05 2017/02/06 10:36:37 acorliss Exp $


         use Parse::PlainConfig::Legacy;

         $conf = new Parse::PlainConfig::Legacy;
         $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);


         @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;

         $errstr = Parse::PlainConfig::Parse::PlainConfig::Legacy::ERROR;

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


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


         $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
         DEFAULTS        {}         Specifies default values for config
                                    parameters if not specified/parsed

       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

       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 and applies the defaults (if any) before
       reading a file.  This does not, however, erase any values set for ORDER.

         $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.

       NOTE: As of version 2.07 all hashes and lists are copied both in and out of the object, so
       any alterations to a referenced structure retrieved will have no effect on the property
       within the object.


       This method 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.

         $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

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

         $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::Legacy::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.

         $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

       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 = $conf->parameters;

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

         $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.

         $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.

       NOTE: Coercing existing values into another data type can provide for some interesting
       conversions.  Strings, for instance, are split on the list delimiter when converting to
       arrays, and similarly on list and hash delimiters for hashes.  Going from a hash or list
       to a string is done in the opposite manner, elements/key-value pairs are joined with the
       applicable delimiters and concatenated into a string.

       For this reason one should try to avoid coercing one data type into another if you can
       avoid it.  Instead one should predefine what the data types for each parameter should be
       and define that in the COERCE hash passed during object instantiation, or via this method
       prior to reading and parsing a file.

         $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

         @order = $conf->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.

         $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.



       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 = $conf->directives;

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

         $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.

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

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

         $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.

         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.

         $error = Parse::PlainConfig::ERROR();

       Lvalue subroutine storing the last error which may have occurred.


       o   Paranoid

       o   Text::ParseWords

       o   Text::Tabs


       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, \

         # 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

       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.

       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: \

       or save empty assignments like


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


       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.


       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.



       Arthur Corliss (


       This software is licensed under the same terms as Perl, itself.  Please see for more information.

       (c) 2002 - 2016, Arthur Corliss (