Config::Properties(3) User Contributed Perl DocumentationConfig::Properties(3)NAMEConfig::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 );
DESCRIPTIONConfig::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
seperated by either whitespace, the colon (:) character, or the equals
(=) character. Whitespace before the key and on either side of the
seperator 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".
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);
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 to 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 forgotten.
$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.
AUTHORS
"Config::Properties" was originally developed by Randy Jay Yarger. It
was mantained for some time by Craig Manley and finally it passed hands
to Salvador Fandin~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 by Salvador Fandin~o.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2011-07-13 Config::Properties(3)
