Config::Properties - Read and write property files

NAME

Config::Properties - Read and write property files

SYNOPSIS

  use Config::Properties;

  # reading...

  open PROPS, "< my_config.props"
    or die "unable to open configuration file";

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

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

  # saving...

  open PROPS, "> my_config.props"
    or die "unable to open configuration file for writing";

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

  $properties->format( '%s => %s' );
  $properties->store(*PROPS, $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 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. You an get the current format string either by using $object->format() (with no arguments) or $object->getFormat().

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

METHODS

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

Config::Properties->new()

Config::Properties->new($defaults)

creates a new Config::Properties object. The optional $defaults parameter can be used to pass another Config::Properties object holding default property values.

$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.

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 Fandiño <sfandino@yahoo.com>, the current maintainer.

COPYRIGHT AND LICENSE

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