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

FreeBSD Manual Pages

  
 
  

home | help
Config::Properties(3) User Contributed Perl DocumentationConfig::Properties(3)

NAME
       Config::Properties - Read and write property files

SYNOPSIS
	 use Config::Properties;

	 # reading...

	 open my $fh, '<', 'my_config.props'
	   or die "unable to open configuration	file";

	 my $properties	= Config::Properties->new();
	 $properties->load($fh);

	 $value	= $properties->getProperty($key);

	 # saving...

	 open my $fh, '>', 'my_config.props'
	   or die "unable to open configuration	file for writing";

	 $properties->setProperty($key,	$value);

	 $properties->format('%s => %s');
	 $properties->store($fh, $header );

DESCRIPTION
       Config::Properties is a near implementation of the java.util.Properties
       API.  It	is designed to allow easy reading, writing and manipulation of
       Java-style property files.

       The format of a Java-style property file	is that	of a key-value pair
       separated by either whitespace, the colon (:) character,	or the equals
       (=) character.  Whitespace before the key and on	either side of the
       separator is ignored.

       Lines that begin	with either a hash (#) or a bang (!) are considered
       comment lines and ignored.

       A backslash (\) at the end of a line signifies a	continuation and the
       next line is counted as part of the current line	(minus the backslash,
       any whitespace after the	backslash, the line break, and any whitespace
       at the beginning	of the next line).

       The official references used to determine this format can be found in
       the Java	API docs for java.util.Properties at
       <http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html>.

       When a property file is saved it	is in the format "key=value" for each
       line. This can be changed by setting the	format attribute using either
       $object->format(	$format_string ) or $object->setFormat(	$format_string
       ) (they do the same thing). The format string is	fed to printf and must
       contain exactly two %s format characters. The first will	be replaced
       with the	key of the property and	the second with	the value. The string
       can contain no other printf control characters, but can be anything
       else. A newline will be automatically added to the end of the string.
       The current format string can be	obtained by using $object->format()
       (with no	arguments) or $object->getFormat().

       If a recent version of Text::Wrap is available, long lines are
       conveniently wrapped when saving.

METHODS
       "Config::Property" objects have this set	of methods available:

       Config::Properties->new(%opts)
	   Creates a new Config::Properties object.

	   The optional	arguments are as follows:

	   file	=> $filename
	       Opens and reads the entries from	the given properties file

	   format => $format
	       Sets the	format using for saving	the properties to a file. See
	       "setFormat".

	   wrap	=> 0
	       Disables	wrapping of long lines when saving the properties to a
	       file.

	   defaults => $defaults
	       Default configuration values.

	       The given parameter can be a hash reference or another
	       Config::Properties object.

	       In that way several configuration objects can be	chained. For
	       instance:

		 my %defaults =	(...);
		 my $global_config = Config::Properties->new(file => '/etc/foo.properties',
							     defaults => \%defaults);
		 my $user_config = Config::Properties->new(file	=> '/home/jsmith/.foo/foo.properties',
							   defaults => $global_config);

	   order => 'keep'|'alpha'|'none'
	       Sets how	to order the properties	when saved to a	file or	when
	       returned	by "properties"	and "propertyNames" methods.

	       "alpha" sorts the keys in alphanumeric order. "keep" keeps the
	       order of	the properties as added	or read	from a file. "none"
	       returns the properties unordered.

	   encoding => $encoding
	       IO encoding used	to read	the configuration file.	See PerlIO.

	       When "load" is called the given encoding	is used	unless the
	       file handler already has	a encoding layer applied.

	       "latin1"	is used	as the default encoding	(as specified in the
	       Java properties specification).

	   be_like_java	=> 1
	       When this feature is enabled, the module	will try to mimic the
	       Java implementation as much as possible when saving files.

	       Currently, some escaping	rules are changed and line wrapping is
	       disabled.

       Config::Properties->new($defaults)
	   Calling "new" in this way is	deprecated.

       $p->getProperty($k, $default, $default2,	...)
	   return property $k or when not defined, the first defined
	   "$default*".

       $p->requireProperty($k, $default, $default2, ...)
	   this	method is similar to "getProperty" but dies if the requested
	   property is not found.

       $p->setProperty($k, $v)
	   set property	$k value to $v.

       $p->changeProperty($k, $v)
       $p->changeProperty($k, $v, $default, $default2, ...)
	   method similar to "setPropery" but that does	nothing	when the new
	   value is equal to the one returned by "getProperty".

	   An example shows why	it is useful:

	     my	$defaults=Config::Properties->new();
	     $defaults->setProperty(foo	=> 'bar');

	     my	$p1=Config::Properties->new($defaults);
	     $p1->setProperty(foo => 'bar');   # we set	here!
	     $p1->store(FILE1);	foo gets saved on the file

	     my	$p2=Config::Properties->new($defaults);
	     $p2->changeProperty(foo =>	'bar');	# does nothing!
	     $p2->store(FILE2);	# foo doesn't get saved	on the file

       $p->deleteProperty($k)
       $p->deleteProperty($k, $recurse)
	   deletes property $k from the	object.

	   If $recurse is true,	it also	deletes	any $k property	from the
	   default properties object.

       $p->properties
	   returns a flatten hash with all the property	key/value pairs, i.e.:

	     my	%props=$p->properties;

       $p->getProperties
	   returns a hash reference with all the properties (including those
	   passed as defaults).

       $p->propertyNames;
	   returns the names of	all the	properties (including those passed as
	   defaults).

       $p->splitToTree()
       $p->splitToTree($regexp)
       $p->splitToTree($regexp,	$start)
	   builds a tree from the properties, splitting	the keys with the
	   regular expression $re (or "/\./" by	default). For instance:

	     my	$data =	<<EOD;
	     name = pete
	     date.birth	= 1958-09-12
	     date.death	= 2004-05-11
	     surname = moo
	     surname.length = 3
	     EOD

	     open my $fh, '<', \$data;
	     $cfg->load();
	     my	$tree =	$cfg->splitToTree();

	   makes...

	     $tree = { date => { birth => '1958-09-12',
				 death => '2004-05-11' },
		       name => 'pete',
		       surname => { '' => 'moo',
				    length => '3' } };

	   The $start parameter	allows to split	only a subset of the
	   properties. For instance, with the same data	as on the previous
	   example:

	      my $subtree = $cfg->splitToTree(qr/\./, 'date');

	   makes...

	     $tree = { birth =>	'1958-09-12',
		       death =>	'2004-05-11' };

       $p->setFromTree($tree)
       $p->setFromTree($tree, $separator)
       $p->setFromTree($tree, $separator, $start)
	   This	method sets properties from a tree of Perl hashes and arrays.
	   It is the opposite of "splitToTree".

	   $separator is the string used to join the parts of the property
	   names. The default value is a dot (".").

	   $start is a string used as the starting point for the property
	   names.

	   For instance:

	     my	$c = Config::Properties->new;
	     $c->setFromTree( {	foo => { '' => one,
					 hollo => [2, 3, 4, 1] },
				bar => 'doo' },
			      '->',
			      'mama')

	     # sets properties:
	     #	    mama->bar =	doo
	     #	    mama->foo =	one
	     #	    mama->foo->hollo->0	= 2
	     #	    mama->foo->hollo->1	= 3
	     #	    mama->foo->hollo->2	= 4
	     #	    mama->foo->hollo->3	= 1

       $p->changeFromTree($tree)
       $p->changeFromTree($tree, $separator)
       $p->changeFromTree($tree, $separator, $start)
	   similar to "setFromTree" but	internally uses	"changeProperty"
	   instead of "setProperty" to set the property	values.

       $p->load($file)
	   loads properties from the open file $file.

	   Old properties on the object	are discarded.

       $p->save($file)
       $p->save($file, $header)
       $p->store($file)
       $p->store($file,	$header)
	   save	the properties to the open file	$file. Default properties are
	   not saved.

       $p->saveToString($header)
	   similar to "save", but instead of saving to a file, it returns a
	   string with the content.

       $p->getFormat()
       $p->setFormat($f)
	   get/set the format string used when saving the object to a file.

SEE ALSO
       Java docs for "java.util.Properties" at
       <http://java.sun.com/j2se/1.3/docs/api/index.html>.

       Config::Properties::Simple for a	simpler	alternative interface to
       Config::Properties.

TODO
       Add support for derived format as supported by Java class
       org.apache.commons.configuration.PropertiesConfiguration
       (<http://commons.apache.org/configuration/apidocs/org/apache/commons/configuration/PropertiesConfiguration.html>)

AUTHORS
       "Config::Properties" was	originally developed by	Randy Jay Yarger. It
       was maintained for some time by Craig Manley and	finally	it passed
       hands to	Salvador FandiA+-o <sfandino@yahoo.com>, the current
       maintainer.

COPYRIGHT AND LICENSE
       Copyright 2001, 2002 by Randy Jay Yarger	Copyright 2002,	2003 by	Craig
       Manley.	Copyright 2003-2009, 2011-2012,	2014-2015 by Salvador
       FandiA+-o.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2015-05-14		 Config::Properties(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | TODO | AUTHORS | COPYRIGHT AND LICENSE

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

home | help