GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DATA::PROPERTIES (3)

.ds Aq ’

NAME

Data::Properties - persistent properties

CONTENTS

SYNOPSIS



  my $props = Data::Properties->new();

  open FH, "./my.properties" or
      die "cant 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 "cant open new.properties: $!\n";
  $props->store(\*FH);
  close FH;



DESCRIPTION

This class is a Perl version of Java’s <B>java.util.PropertiesB> and aims to be format-compatible with that class.

The <B>PropertiesB> class represents a persistent set of properties. The <B>PropertiesB> 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.

<B>PropertiesB> 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 <B>PropertiesB> 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? <B>java.util.PropertiesB> uses ISO-8859-1 and allows for Unicode escape sequences.

SEE ALSO

<B>POSIXB>

<B>java.util.PropertiesB>, http://java.sun.com/j2se/1.3/docs/api/index.html

AUTHOR

Brian Moseley, bcm@maz.org

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 346: You forgot a ’=back’ before ’=head1’
Around line 353: =back without =over
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PROPERTIES (3) 2001-11-26

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.