NAME

Data::Properties - persistent properties

SYNOPSIS

  my $props = Data::Properties->new();
  open FH, "./my.properties" or
      die "can't open my.properties: $!\n";
  $props->load(\*FH);
  close FH;
  for my $name ($props->property_names()) {
      my $val = $props->get_property($name);
  }
  $props->set_property("foo", "bar");
  open FH, "> ./new.properties" or
      die "can't open new.properties: $!\n";
  $props->store(\*FH);
  close FH;

DESCRIPTION

This class is a Perl version of Java's java.util.Properties and aims to be format-compatible with that class.

The Properties class represents a persistent set of properties. The Properties can be saved to a filehandle or loaded from a filehandle. Each key and its corresponding value in the property list is a string.

A property list can contain another property list as its "defaults"; this second property list is searched if the property key is not found in the original property ist.

Properties does no type checking on the keys or values stored with set_property(). Keys and values are stored as strings via sprintf(), so you almost always want to use simple keys and values, not arrays, or hashes, or references. Keys and values are loaded and stored "as-is"; no character or other conversions are performed on them.

CONSTRUCTOR

new([$defaults]): Creates an empty property list, optionally with the specified defaults.
Dies if $defaults is not a Properties object.

METHODS

get_property($key, [$default_value])

Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list and its defaults are recursively checked. If the property is not found, $default_value is returned if specified, or "undef" otherwise.

load($handle)

Reads a property list from the specified input handle.

Every property occupies one line read from the input handle. Lines from the input handle are processed until EOF is reached.

A line that contains only whitespace or whose first non-whitespace character is an ASCII "#" or "!" is ignored (thus, these characters indicate comment lines).

Every line other than a blank line or a comment line describes one property to be added to the property list (except that if a line ends with "\", then the following line, if it exists, is treated as a continuation line, as described below). The key consists of all the characters in the line starting with the first non-whitespace character and up to, but not including, the first ASCII "=", ":", or whitespace character. Any whitespace after the key is skipped; if the first non-whitespace character after the key is "=" or ":", then it is ignored and any whitespace characters after it are also skipped. All remaining characters on th eline become part of the associated value. If the last character on the line is "\", then the next line is treated as a continuation of the current line; the "\" and line terminator are simply discarded, and any leading whitespace characters on the continuation line are also discarded and not part of the element string.

As an example, each of the following lines specifies the key "Truth" and the associated element value "Beauty":

  Truth = Beauty
        Truth:Beauty
  Truth                        :Beauty

As another example, the following three lines specify a single property:

  fruits                        apple, banana, pear, \
                                cantaloupe, watermelon, \
                                kiwi, mango

The key is "fruits" and the associated element is "apple, banana, pear, cantaloupe, watermelon, kiwi, mango".

Note that a space appears before each "\" so that a space will appear after each comma in the final value; the "\", line terminator, and leading whitespace on the continuation line are merely discarded and are "not" replaced by one or more characters.

As a third example, the line:

  cheeses:

specifies that the key is "cheeses" and the associated element is the empty string.

Dies if an error occurs when reading from the input handle.

property_names

Returns an array (or an arrayref in scalar context) containing all of the keys in this property list, including the keys in the default property list.

set_property($key, $value)

Sets the property with the specified key.

store($handle, $header)

Writes this property list to the specified output handle. Default properties are not written by this method.

If a header is specified, then the ASCII characters "# ", the header string, and a line separator are first written to the output handle. Thus the header can serve as an identifying comment.

Next, a comment line is always written, consisting of the ASCII characters "# ", the current date and time (as produced by POSIX::ctime()), and a line separator.

Then every entry in the property list is written out, one per line. For each entry the key string is written, then an ASCII "=", then the associated value.

The output handle remains open after this method returns.

Dies if an error occurs when writing to the input handle.

TODO

o

Read and write escaped characters in property keys and values.

In values only, the ASCII characters backslash, tab, newline, carriage return, double quote, and single quote should be stored as the literal strings "\\", "\t", "\n", "\r", "\"", and "\'" respectively, and those literal strings should be converted into the corresponding ASCII characters when loading properties. The same goes for leading spaces (converted into "\ "), but not embedded or trailing spaces.

In keys and values, the ASCII characters "#", "!", "=", and ":" should be stored with a preceding "\", and those literal strings should be unescaped when loading properties.

ISSUES

o: What happens when non-ASCII characters are used? java.util.Properties uses ISO-8859-1 and allows for Unicode escape sequences.

AUTHOR

Brian Moseley, bcm@maz.org (original version).

Johan Vromans, jv@cpan.org (revived version).

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 346:: You forgot a '=back' before '=head1'
Around line 353:: =back without =over