Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Parse::PlainConfig(3) User Contributed Perl DocumentationParse::PlainConfig(3)

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 protoypes 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)

perl v5.32.0			  2017-02-06		 Parse::PlainConfig(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SUBCLASSING | CONFIG FILE FORMAT RULES | SUBROUTINES/METHODS | DEPENDENCIES | DIAGNOSTICS | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Parse::PlainConfig&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help