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

FreeBSD Manual Pages

  
 
  

home | help
Config::Record(3)     User Contributed Perl Documentation    Config::Record(3)

NAME
       Config::Record -	Configuration file access

SYNOPSIS
	 use Config::Record;

	 # Create an empty record & then load from file
	 my $config = Config::Record->new();
	 $config->load("/etc/myapp.cfg");

	 # Create & load, then save to filename
	 my $config = Config::Record->new(file => "/etc/myapp.cfg");
	 $config->save("/etc/myapp.cfg");

	 # Load	/ save from filehandle
	 my $fh	= IO::File->new("/etc/myapp.cfg");
	 my $config = Config::Record->new(file => $fh);
	 $config->save($fh);

	 # Get a config	value, throw error if not found
	 my $value = $config->get("foo");

	 # Get a config	value, return 'eek' if not found
	 my $value = $config->get("foo", "eek");

	 # Set a value
	 $config->set("foobar",	"wizz");

	 # Get a deep config value (ie nested hash)
	 my $value = $config->get("foo/bar", "eek");

	 # Get first element of	an array param
	 my $value = $config->get("people/[0]/forename");

	 # Get the raw hash reference forming the record
	 my $record = $config->record();

	 # Get a new config object rooted at a sub-hash
	 my $config = $config->view("foo");

DESCRIPTION
       This module provides an API for loading and saving of simple
       configuration file records. Entries in the configuration	file are
       essentially key,value pairs, with the key and values separated by a
       single equals symbol. The "key" consists	only of	alphanumeric
       characters. There are three types of values, scalar values can contain
       anything	except newlines. Trailing whitespace will be trimmed unless
       the value is surrounded in double quotes. eg

	 foo = Wizz
	 foo = "Wizz....    "

       Long lines can be split with a backslash	character, without introducing
       newlines. Without double	quotes,	whitespace at beginning	and end	of
       lines will be trimmed eg

	 foo = This is a long \
	       line of text
	 foo = "This is	a long " \
	       "line of	text"

       Multi-line strings can be provided as 'HERE' documents, eg

	 foo = <<EOF
       This is a multiple paragraph
       block of	text with newlines
       preserved
       EOF

       Array values  consist of	a single right round bracket, following	by one
       "value" per line, terminated by a single	left round bracket. eg

	 foo = (
	   Wizz
	   "Wizz...    "
	 )

       Hash values consist of a	single right curly bracket, followed by	one
       key,value pair per line,	terminated by a	single left curly bracket.  eg

	 foo = {
	   one = Wizz
	   two = "Wizz....  "
	 }

       Arrays and hashes can be	nested to arbitrary depth.

EXAMPLE
	 name =	Foo
	 title = "Wizz bang wallop"
	 eek = (
	   OOhh
	   Aahhh
	   Wizz
	 )
	 people	= (
	   {
	     forename =	John
	     surnamne =	Doe
	   }
	   {
	     forename =	Some
	     surname = One
	   }
	 )
	 wizz =	{
	   foo = "Elk"
	   ooh = "fds"
	 }

EXTRA PARSER FEATURES
       The syntax described thus far is	classed	as the base feature set. By
       passing the "features" parameter	when creating an instance of the
       "Config::Record"	class, it is posible to	turn on	certain	extra features

   QUOTED NON-ALPHANUMERIC KEYS
       The keys	for configuration parameters are normally restricted to	only
       contain the characters 'a-Z', '0-9', '_', '-' and '.'. Sometimes	it is
       desirable to allow arbitrary characters for keys. If this capability is
       required	then the "quotedkeys" parameter	can be set.

       EXAMPLE

	 name =	Foo
	 title = "Wizz bang wallop"
	 " some	parameter " = (
	    foo
	    bar
	 }
	 "an embeded \"	quote" = bar
	 "an embeded \\	backslash" = wizz

   EXTERNAL INCLUDE FILES
       With large configuration	files it can be	desirable to split them	into a
       number of smaller files.	If this	capability is required,	then the
       "includes" feature can be requested. Each included file must follow the
       syntax rules already described.

       EXAMPLE

       In the main file

	 name =	Foo
	 title = "Wizz bang wallop"
	 foo = @include(somefile.cfg)

       And in somefile.cfg

	 firstname = Joe
	 lastname = Blogs

       Is equivalent to

	 name =	Foo
	 title = "Wizz bang wallop"
	 foo = {
	   firstname = Joe
	   lastname = Blogs
	 }

METHODS
       my $config = Config::Record->new([file => $file], [features =>
       \%features]);
	   Creates a new config	object,	loading	parameters from	the file
	   specified by	the "file" parameter. The "file" parameter can either
	   be a	string representing a fully qualified filename,	or a
	   IO::Handle object. If the "file" parameter is a string, this
	   filename will be saved and future calls to "load" or	"save" are
	   permitted to	omit the filename. If the "file" parameter is not
	   supplied then an empty configuration	record is created.

	   The "features" parameter allows extra parser	features to be
	   enabled.  The two valid keys	for the	associated hash	as "includes"
	   and "quotedkeys" as described earlier in this document.

       $config->load([$file]);
	   Loads and parses a configuration record. The	"file" parameter can
	   either be a string representing a fully qualified filename, or an
	   IO::Handle object. The $file	parameter may be omitted, if a
	   filename was	specified in the constructor, or in previous calls to
	   "load" or "save". Prior to loading the record, the current contents
	   of this configuration are cleared.

       $config->save([$file]);
	   Saves the configuration record to a file. The "file"	parameter can
	   either be a string representing a fully qualified filename, or an
	   IO::Handle object opened for	writing. The $file parameter may be
	   omitted, if a filename was specified	 in the	constructor, or	in
	   previous calls to "load" or "save".

       my $value = $config->get($key[, $default]);
	   Gets	the value of a configuration parameter corresponding to	the
	   name	"key". If there	is no value in the record, then	the optional
	   "default" is	returned.

       $config->set($key, $value);
	   Sets	the value of a configuration parameter corresponding to	the
	   name	"key".

       $config->view($key)
	   Return a new	Config::Record object, rooted at the specified key.
	   If the key doesn't resolve to a hash	reference an error will	be
	   raised.

       my $record = $config->record();
	   Retrieves a hash reference for the entire configuration record.
	   Currently this is the actual	internal storage record, so changes
	   will	modify the configuration. In the next release this will	be
	   changed to be a deep	clone of the internal storage record.

BUGS
       Config::Record has the following	limitations

       o   If you load and then	save a configuration file all comments are
	   removed & whitespace	normalized.

       o   Ordering of elements	in hash	ref are	not preserved across load and
	   save	sequence

       These limitations may be	fixed in a future release if there is demand
       from users...

AUTHORS
       Daniel Berrange <dan@berrange.com>

COPYRIGHT
       Copyright (C) 2000-2007 Daniel P. Berrange <dan@berrange.com>

SEE ALSO
       perl(1)

perl v5.32.0			  2007-12-12		     Config::Record(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | EXTRA PARSER FEATURES | METHODS | BUGS | AUTHORS | COPYRIGHT | SEE ALSO

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

home | help