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

NAME

       Parse::PlainConfig - Configuration file class

VERSION

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

SYNOPSIS

   SAMPLE CONFIG CLASS
         package MyConfig;

         use Parse::PlainConfig;
         use Parse::PlainConfig::Constants;
         use base qw(Parse::PlainConfig);
         use vars qw(%_globals %_parameters %_prototypes);

         %_globals = (
               'comment'        => '#',
               'delimiter'      => ':',
               'list delimiter' => ',',
               'hash delimiter' => '=>',
               'subindentation' => 4,
               'here doc'       => 'EOF',
             );
         %_parameters = (
             'daemon ports'    => PPC_ARRAY,
             'banner'          => PPC_HDOC,
             'user'            => PPC_SCALAR,
             'group'           => PPC_SCALAR,
             'database'        => PPC_HASH,
             'acls'            => PPC_HASH,
             );
         %_prototypes = (
             'define net'      => PPC_ARRAY,
             );

         1;

         __DATA__

         # This is the default configuration for MyConfig.
         # Newly created objects based on this class will
         # inherit the below configuration as default values.
         #
         # daemon ports:  list of ports to listen on
         daemon ports:  8888, 9010

         # banner:  default banner to display on each connection
         banner:
             ********  WARNING  ********
                You are being watched
             ********  WARNING  ********
         EOF

         user: nobody
         group: nogroup
         database:
             host => localhost,
             db   => mydb,
             user => dbuser,
             pass => dbpass

         define net loopback: 127.0.0.1/8, ::1/128
         define net localnet: 192.168.0.0/24, 192.168.35.0/24
         define net nonlocal:  ! 192.168.0.0/16

         acls:  loopback => allow, localnet => allow, nonlocal => deny

         __END__

         =head1 NAME

         normal pod text can be put here...

   SAMPLE OBJECT USAGE
         $config = new MyConfig;

         print "default user: ", $config->get('user'), "\n";
         print "default group: ", $config->get('group'), "\n";

         # Override value
         $config->set('user', 'root');

         # Get config from a file
         $rv = $config->read($filename);

         # Parse config from in-memory text
         $rv = $config->parse(@lines);

         # Prototyps are accessed like parameters
         @localnets = $config->get('localnet');

         # Reset config values back to class defaults
         $config->reset;

         # Print default config file
         print $config->default;

DESCRIPTION

       Parse::PlainConfig provides a simple way to write a config object class that supports all
       the basic primitive data types (scalar, array, and hashes) while allowing for arbitrary
       delimiters, comment characters, and more.

       The use of a __DATA__ block to merge your default config not only provides for a reference
       config but a convenient way to set default values for parameters and prototypes.  Use of
       __END__ also allows you to append your standard POD text to allow for the creation of man
       pages documenting your configuration options.

       The parser supports the use of "include {filename|glob}" syntax for splitting
       configuration parameters amongst multiple config files.  Even without it every call to
       read or parse only applies new settings on top of the existing set, allowing you to
       aggregate multiple config file parameters into one set of parameters.

       Unlike previous versions of this module Parse::PlainConfig is strictly a parser, not a
       generator.  That functionality never seem to be used enough to be worth maintaining with
       this upgrade.  For backwards compatibility the old Parser/Generator is still included
       under the new namespace Parse::PlainConfig::Legacy.  Updating legacy scripts to use that
       package name instead should keep everything working.

       Parse::PlainConfig is a subclass of Class::EHierarchy, and all parameters are public
       properties allowing access to the full set of data-aware methods provided by that module
       (such as merge, empty, pop, shift, and others).

       I/O is also done in a platform-agnostic manner, allowing parsed values to read reliably on
       any platform regardless of line termination style used to author the config file.

SUBCLASSING

       All parsing objects are now subclasses of Parse::PlainConfig tuned for a specific style
       and a known list of parameters and/or prototypes.  This makes coding for config file
       parsing extremely simple and convenient.

       Control of the parser is performed by setting values in three class hashes:

   %_globals
       The %_globals hash is primarily used to specify special character sequences the parser
       will key to identify comments and the various parameters and data types.  The following
       key/value are supported:

           Key             Default   Description
           ---------------------------------------------------------------
           comment         #         Character(s) used to denote comments
           delimiter       :         Parameter/value delimiter
           list delimiter  ,         Ordinal array values delimiter
           hash delimiter  =>        Hash values' key/value pair delimiter
           subindentation  4         Default level of indentation to
                                     expect for line continuations
           here doc        EOF       Token used for terminating here doc
                                     parameter values

       If all of the defaults are acceptable this hash can be omitted entirely.

       Note that the subindentation is merely advisory, any additional level of subindentation on
       line continuations will work.  What this does, however, is trim up to that amount of
       preceding white space on each line within a here-doc.  This allows one to indent blocks of
       text to maintain the visual flow of the config file, while still allowing the editor the
       use of all columns in the display.

   %_parameters
       The %_parameters hash is used to list all of the formal parameters recognized by this
       config object.  All parameters must be one of four data types:

           Type        Description
           ----------------------------------------------------------------
           PPC_SCALAR  Simple strings
           PPC_ARRAY   Arrays/lists
           PPC_HASH    Hashes/Associative arrays
           PPC_HDOC    Essentially a PPC_SCALAR that preserves formatting

       All but PPC_HDOC will trim leading/trailing white space and collapse all lines into a
       single line for parsing.  That means that no string, ordinal value, key, or associative
       value can have embedded line breaks.  You can, however, have delimiter characters as part
       of any values as long as they are encapusated in quoted text or escaped.

       PPC_HDOC will preserve line breaks, but will trim leading white space on each line up to
       the value given to $_globals{subindentation}.

   %_prototypes
       %_prototypes exist to allow for user-defined parameters that fall outside of the formal
       parameterss in %_parameters.  ACLs, for instance, are often of indeterminate number and
       naming, which is a perfect use-case for prototypes.

       Like parameters prototypes are assigned a data type.  Unlike parameters prototypes are
       assigned types based on a declarative preamble since the the name (or token) is not known
       in advance.

       To continue with the ACL example we could define a prototype like so:

           %_prototypes = ( 'define acl' => PPC_ARRAY );

       The config editor could then define any number of ACLs:

           define acl loopback 127.0.0.1/8
           define acl localnet 192.168.0.0/24,192.168.1.0/24

       Once parsed those ACL parameters can then be accessed simply by their unique token:

           @localnets = $config->get('localnet');

CONFIG FILE FORMAT RULES

       This module is intended to provide support for parsing human-readable config files, while
       supporting basic data structures and delimiter flexibility.  That said, there are a few
       basic rules by which the parser operates.

       Note that the use __DATA__ and/or __END__ blocks are entirely optional.

   DELIMITERS
       Delimiters must be unique.  You cannot use the same character(s) for both list delimiters
       and hash key/value pair delimiters, for instance.  That said, the parser is very forgiving
       on the use of whitespace around all delimiters, even if one of your delimiters is
       literally a space.

       Hash and array delimiters can be embedded in elements as long as they're quoted or escaped
       appropriately.  Those elements are split using Text::ParseWords' quotewords function.

   LINE CONTINUATIONS
       Parameters values may need to be, by necessity, longer than a single line.  This is fully
       supported for all data types.  All that is needed that the line continuations be at least
       one space more indented than the preceding line.  Empty lines are considered to be line
       breaks which terminate the parameter value.  Likewise, a line that is indented equal or
       less than the parameter declaration line implies a new block of content.

       There is one exception to that rule:  here docs.  If you need to preserve formatting,
       which can include line breaks, the use of here docs will suck in everything up to the next
       here doc EOF token.  The entire here doc, however, is treated as scalar value for purposes
       of parameter storage.

   COMMENTS
       Comments can be any sequence of characters, but must be on a line by themselves.
       Preceding white space is allowed.

   PARAMETER NAMES
       Given that parameters are actually formal object properties it could go without saying
       that each parameter must be uniquely named.  Parameters names can include white space or
       other miscellaneous punctuation.

   PROTOTYPES
       Prototypes allow for the dynamic creation of parameters.  There are a few caveats in their
       usage, however.  Prototypes are specified through a unique preamble followed by a unique
       token.  Unlike parameter names this token cannot have embedded white space.  But like
       parameters they are specified by that unique token (minus the preamble) during get and set
       operations.

       Since these dynamic properties are also formal properties the token must not be in use as
       a formal property.  In other words, all prototype tokens and parameter names must be
       unique as a set.

       Parsing errors will be generated if the token occurs as a formal parameter.  It will also
       be generated if you attempt to redfine a token as a different type of data structure.

SUBROUTINES/METHODS

   new
         $conf = new MyConfig;

       This creates a new config object based on the specified config class, initialized with the
       defaults merged in __DATA__.  No additional arguments are supported.  This will fail if
       the default config is invalid in any way.

   settings
         $settings = $config->settings;

       This provides a reference to the engine settings object from which you can interrogate
       various settings such as delimiters, etc.  The full set of methods supported by the
       settings object is documented in Parse::PlainConfig::Settings.

   default
          $text  = $config->default;
          @lines = $config->default;

       This returns the text of the default configuration file embedded in the __DATA__ section
       of the config class.

   get
         $val = $config->get($parameter);
         @val = $config->get($parameter);
         %val = $config->get($parameter);

       This returns the store value(s) for the specified parameter.  It is essentially the same
       as using the parent class property method, although this will not cause the program to
       croak like property does.  It will carp, instead.

   set
         $rv = $config->set($parameter);
         $rv = $config->set($parameter, $newval);
         $rv = $config->set($parameter, @newval);
         $rv = $config->set($parameter, %newval);

       This method sets the desired parameter to the newly specified value(s).  If no values are
       provided it will assume that you wish to set scalars to undef or empty arrays and hashes.

   parse
         $rv = $config->parse($text);
         $rv = $config->parse(@lines);

       This will parse and set any parameters or prototypes found in the content.  It will return
       false if any parsing errors are found (spurious text, etc.) but will extract everything of
       intelligible value it can.

   read
         $rv = $config->read($filename);
         $rv = $config->read(@files);
         $rv = $config->read($pglob);
         $rv = $config->read(*fh);

       This method will attempt to read every file passed to it, whether it be passed by file
       name, file handle, Paranoid::Glob, or objec reference support I/O functions.  Fair
       warning:  this does observe file locking semantics (flock) and it will close any file
       handles passed to it after consuming the content.

       Also note that this method uses Paranoid::IO::Line, which implements protections against
       memory-utilization attacks.  You may need to adjust the following parameters depending on
       the size of your config files:

         use Paranoid::IO qw(PIOMAXFSIZE PIOBLKSIZE);
         use Paranoid::IO qw(PIOMAXLNSIZE);

         # Adjust read block size for performance
         PIOBLKSIZE = 16 * 1024;

         # Allow file sizes up to 128KB
         PIOMAXFSIZE = 128 * 1024;

         # Allow individual lines to be 4KB long
         PIOMAXLNSIZE = 4 * 1024;

   reset
         $rv = $config->reset;

       This method emptys the contents of all parameters and prototypes, then applies the default
       settings as found in __DATA__.

   prototyped
           @protos = $config->prototyped;
           @protos = $config->prototyped($preamble);

       This method returns a list of properties that were defined as the result of prototypes.
       With no arguments it returns all properties that were defined.  With an argument it
       returns only those properties that were defined by that specific prototype preamble.

   error
           $errStr = $config->error;

       Returns the last error that occurred.  Note that this isn't reset between method
       invocations.

DEPENDENCIES

       o   Class::EHierarchy

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::Glob

       o   Paranoid::IO

       o   Paranoid::IO::Line

       o   Paranoid::Input

       o   Parse::PlainConfig::Constants

       o   Parse::PlainConfig::Settings

       o   Text::ParseWords

       o   Text::Tabs

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.

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is licensed under the same terms as Perl, itself.  Please see
       http://dev.perl.org/licenses/ for more information.

       (c) 2002 - 2016, Arthur Corliss (corliss@digitalmages.com)