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

FreeBSD Manual Pages

  
 
  

home | help
Parse::PlainConfig::LeUser(Contributed Perl DocumParse::PlainConfig::Legacy(3)

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

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

SYNOPSIS
	 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);

	 $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::Parse::PlainConfig::Legacy::ERROR;

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

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

SUBROUTINES/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
	 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 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 and applies the
       defaults	(if any) 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.

       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.

   purge
	 $conf->purge;

       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.

   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::Parse::PlainConfig::Legacy::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::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.

   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.

       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.

   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.

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

       Lvalue subroutine storing the last error	which may have occurred.

DEPENDENCIES
       o   Paranoid

       o   Text::ParseWords

       o   Text::Tabs

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.

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::Legacy(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SUBROUTINES/METHODS | DEPRECATED METHODS | DEPENDENCIES | FILE SYNTAX | SECURITY | 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::Legacy&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help