Provided by: libconfig-properties-perl_1.80-1_all bug

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 one 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 Fandiñ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 Fandiño.

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