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

FreeBSD Manual Pages

  
 
  

home | help
ConfigReader::Simple(3User Contributed Perl DocumentatiConfigReader::Simple(3)

NAME
       ConfigReader::Simple - A	simple line-oriented configuration file	parser

SYNOPSIS
	       use ConfigReader::Simple;

	       # parse one file
	       $config = ConfigReader::Simple->new("configrc", [qw(Foo Bar Baz Quux)]);

	       # parse multiple	files, in order
	       $config = ConfigReader::Simple->new_multiple(
		       Files =>	[ "global", "configrc" ],
		       Keys  =>	[qw(Foo	Bar Baz	Quux)]
		       );

	       my @directives =	$config->directives;

	       $config->get( "Foo" );

	       if( $config->exists( "Bar" ) ) {
		       print "Bar was in the config file\n";
		       }

	       # copy an object	to play	with it	separately
	       my $clone = $config->clone;

	       # only affects clone
	       $clone->set( "Foo", "Buster" );

	       # save the config to a single file
	       $clone->save( "configrc"	)

	       # save the config to a single file, but only with
	       # certain directives
	       $clone->save( "configrc"	=> [qw(Foo Bar)] )

	       # save to multiple configuration	files
	       $clone->save(
		       "configrc" => [qw(Foo Bar)],
		       "global"	  => [qw(Baz Quux)],
		       );

DESCRIPTION
       "ConfigReader::Simple" reads and	parses simple configuration files.  It
       is designed to be smaller and simpler than the "ConfigReader" module
       and is more suited to simple configuration files.

   The configuration file format
       The configuration file uses a line-oriented format, meaning that	the
       directives do not have containers.  The values can be split across
       lines with a continuation character, but	for the	most part everything
       ends up on the same line.

       The first group of non-whitespace characters is the "directive",	or the
       name of the configuration item.	The linear whitespace after that
       separates the directive from the	"value", which is the rest of the
       line, including any other whitespace.

       In this example,	the directive is "Camel" and the value is "Dromedary".

	       Camel Dromedary

       Optionally, you can use a equal sign to separate	the directive from the
       value.

	       Camel=Dromedary

       The equal sign can also have whitespace on either or both sides.

	       Camel = Dromedary
	       Camel= Dromedary

       In the next example, the	directive is "Llama" and the value is "Live
       from Peru"

	       Llama Live from Peru

       This is the same, to "ConfigReader::Simple", as the following which has
       more whitespace between the directive and the value.

	       Llama	 Live from Peru

       You can also enclose the	value in single	or double quotes.

	       Llama "Live from	Peru"
	       Llama 'Live from	Peru'
	       Llama='Live from	Peru'

       In some cases you may want to split the logical line across two lines,
       perhaps to see it better	in a terminal window.  For that, use a \
       followed	only by	whitespace.  To	split the last entry across two	lines,
       we use the \ at the end of the line. These three	entries	are the	same:

	       Llama Live from Peru

	       Llama Live from \
	       Peru

	       Llama Live \
	       from \
	       Peru

       If a line is only whitespace, or	the first whitespace character is a #,
       the Perl	comment	character, "ConfigReader::Simple" ignores the line
       unless it is the	continuation of	the previous line.

   Methods
       new ( FILENAME, DIRECTIVES )
	   Creates a "ConfigReader::Simple" object.

	   "FILENAME" tells the	instance where to look for the configuration
	   file. If FILENAME cannot be found, an error message for the file is
	   added to the	%ERROR hash with the FILENAME as a key,	and a combined
	   error message appears in $ERROR.

	   "DIRECTIVES"	is an optional argument	and is a reference to an
	   array. Each member of the array should contain one valid directive.
	   A directive is the name of a	key that must occur in the
	   configuration file. If it is	not found, the method croaks. The
	   directive list may contain all the keys in the configuration	file,
	   a sub set of	keys or	no keys	at all.

	   The "new" method is really a	wrapper	around "new_multiple".

       new_multiple( Files => ARRAY_REF, Keys => ARRAY_REF )
	   Create a configuration object from several files listed in the
	   anonymous array value for the "Files" key.  The module reads	the
	   files in the	same order that	they appear in the array.  Later
	   values override earlier ones.  This allows you to specify global
	   configurations which	you may	override with more specific ones:

		   ConfigReader::Simple->new_multiple(
			   Files => [ qw( /etc/config /usr/local/etc/config /home/usr/config ) ],
			   );

	   This	function croaks	if the values are not array references.

	   If this method cannot read a	file, an error message for that	file
	   is added to the %ERROR hash with the	filename as a key, and a
	   combined error message appears in $ERROR.  Processing the list of
	   filenames continues if a file cannot	be found, which	may produced
	   undesired results. You can disable this feature by setting the
	   $ConfigReader::Simple::Die variable to a true value.

       new_string( Strings => ARRAY_REF, Keys => ARRAY_REF )
	   Create a configuration object from several strings listed in	the
	   anonymous array value for the "Strings" key.	 The module reads the
	   strings in the same order that they appear in the array.  Later
	   values override earlier ones.  This allows you to specify global
	   configurations which	you may	override with more specific ones:

		   ConfigReader::Simple->new_strings(
			   Strings => [	\$global, \$local ],
			   );

	   This	function croaks	if the values are not array references.

       add_config_file(	FILENAME )
	   Parse another configuration file and	add its	directives to the
	   current configuration object. Any directives	already	defined	will
	   be replaced with the	new values found in FILENAME.

       files
	   Return the list of configuration files associated with this object.
	   The order of	the return values is the order of parsing, so the
	   first value is the first file parsed	(and subsequent	files may mask
	   it).

       new_from_prototype(
	   Create a clone object. This is the same thing as calling clone().

       parse( FILENAME )
	   This	does the actual	work.

	   This	is automatically called	from "new()", although you can reparse
	   the configuration file by calling "parse()" again.

       parse_string( SCALAR_REF	)
	   Parses the string inside the	reference SCALAR_REF just as if	it
	   found it in a file.

       get( DIRECTIVE )
	   Returns the parsed value for	that directive.	 For directives	which
	   did not have	a value	in the configuration file, "get" returns the
	   empty string.

       set( DIRECTIVE, VALUE )
	   Sets	the value for DIRECTIVE	to VALUE.  The DIRECTIVE need not
	   already exist.  This	overwrites previous values.

	   The VALUE must be a simple scalar.  It cannot be a reference.  If
	   the VALUE is	a reference, the function prints a warning and returns
	   false.

       unset( DIRECTIVE	)
	   Remove the value from DIRECTIVE, which will still exist.  It's
	   value is undef.  If the DIRECTIVE does not exist, it	will not be
	   created.  Returns FALSE if the DIRECTIVE does not already exist,
	   and TRUE otherwise.

       remove( DIRECTIVE )
	   Remove the DIRECTIVE. Returns TRUE is DIRECTIVE existed and FALSE
	   otherwise.

       directives()
	   Returns a list of all of the	directive names	found in the
	   configuration file. The keys	are sorted ASCII-betically.

       exists( DIRECTIVE )
	   Return TRUE if the specified	directive exists, and FALSE otherwise.

       clone
	   Return a copy of the	object.	 The new object	is distinct from the
	   original so you can make changes to the new object without
	   affecting the old one.

       save( FILENAME [	=> ARRAY_REF [,	FILENAME => ARRAY_REF ]	] );
	   The save method works in three ways,	depending on the argument
	   list.

	   With	a single argument, the save function attempts to save all of
	   the field-value pairs of the	object to the file named by the
	   argument.

		   $clone->save( "configrc" );

	   With	two arguments, the method expects the second argument to be an
	   array reference which lists the directives to save in the file.

		   $clone->save( "configrc" => [qw(Foo Bar)] );

	   With	more than two arguments, the method expects filename-list
	   pairs.  The method will save	in each	file the values	in their
	   respective array references.

		   $clone->save(
			   "configrc" => [qw(Foo Bar)],
			   "global"   => [qw(Baz Quux)],
			   );

	   In the last two cases, the method checks that the value for each
	   pair	is an array reference before it	affects	any files.  It croaks
	   if any value	is not an array	reference.

	   Once	the method starts writing files, it tries to write all of the
	   specified files. Even if it has a problem with one of them, it
	   continues onto the next one.	 The method does not necessarily write
	   the files in	the order they appear in the argument list, and	it
	   does	not check if you specified the same file twice.

   Package variables
       $Die - DEPRECATED
	   If set to a true value, all errors are fatal.

       $ERROR
	   The last error message.

       %ERROR
	   The error messages from unreadable files.  The key is the filename
	   and the value is the	error message.

       $Warn - DEPRECATED
	   If set to a true value, methods may output warnings.

LIMITATIONS/BUGS
       Directives are case-sensitive.

       If a directive is repeated, the first instance will silently be
       ignored.

CREDITS
       Bek Oberin "<gossamer@tertius.net.au>" wote the original	module

       Kim Ryan	"<kimaryan@ozemail.com.au>" adapted the	module to make
       declaring keys optional.	 Thanks	Kim.

       Alan W. Jurgensen "<jurgensen@berbee.com>" added	a change to allow the
       NAME=VALUE format in the	configuration file.

       Andy Lester, "<petdance@cpan.org>", for maintaining the module while
       brian was on active duty.

       Adam Trickett, "<atrickett@cpan.org>", added multi-line support.	 You
       might want to see his "Config::Trivial" module.

       Greg White has been a very patient user and tester.

SOURCE AVAILABILITY
       The source is in	Github:

	       http://github.com/briandfoy/ConfigReader-Simple/

AUTHORS
       brian d foy, "<bdfoy@cpan.org>"

COPYRIGHT AND LICENSE
       Copyright A(C) 2002-2018, brian d foy <bdfoy@cpan.org>. All rights
       reserved.

       This program is free software; you can redistribute it and/or modify it
       under the Artistic License 2.0.

perl v5.32.0			  2018-04-26	       ConfigReader::Simple(3)

NAME | SYNOPSIS | DESCRIPTION | LIMITATIONS/BUGS | CREDITS | SOURCE AVAILABILITY | AUTHORS | COPYRIGHT AND LICENSE

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

home | help