Provided by: libparse-plainconfig-perl_3.07-1_all 
NAME
Parse::PlainConfig - Configuration file class
VERSION
$Id: lib/Parse/PlainConfig.pm, 3.07 2024/01/10 13:32:06 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 parameters 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');
NOTES ON SUBCLASSING
The above section provided the rudimentaries of subclassing Parse::PlainConfig, but this module also
subclassing your config modules as well, including multiple inheritance. This can allow you to have a
single config that can consolidate multiple configurations in a single file. There's only a few rules to
observe:
• All configs must use the same global parsing parameters
• Each property and prototype should use be declared in one specific class to avoid conflicts with data
types and potential defaults in the DATA block
• Defaults from each class will be applied from the top down, and left to right. This means that the
top level parent class'es data block will be parsed first, then each subsequent child class, and the
final subclass, last.
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 6. 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 - 2023, Arthur Corliss (corliss@digitalmages.com)
perl v5.38.2 2024-01-20 Parse::PlainConfig(3pm)