Data::Properties(3pm)

1Properties(3)         User Contributed Perl Documentation        Properties(3)
2
3
4

NAME

6       Data::Properties - persistent properties
7

SYNOPSIS

9         my $props = Data::Properties->new();
10
11         open FH, "./my.properties" or
12             die "can't open my.properties: $!\n";
13         $props->load(\*FH);
14         close FH;
15
16         for my $name ($props->property_names()) {
17             my $val = $props->get_property($name);
18         }
19
20         $props->set_property("foo", "bar");
21
22         open FH, "> ./new.properties" or
23             die "can't open new.properties: $!\n";
24         $props->store(\*FH);
25         close FH;
26

DESCRIPTION

28       This class is a Perl version of Java's java.util.Properties and aims to
29       be format-compatible with that class.
30
31       The Properties class represents a persistent set of properties. The
32       Properties can be saved to a filehandle or loaded from a filehandle.
33       Each key and its corresponding value in the property list is a string.
34
35       A property list can contain another property list as its "defaults";
36       this second property list is searched if the property key is not found
37       in the original property ist.
38
39       Properties does no type checking on the keys or values stored with
40       set_property(). Keys and values are stored as strings via sprintf(), so
41       you almost always want to use simple keys and values, not arrays, or
42       hashes, or references. Keys and values are loaded and stored "as-is";
43       no character or other conversions are performed on them.
44

CONSTRUCTOR

46       new([$defaults])
47           Creates an empty property list, optionally with the specified
48           defaults.
49
50           Dies if $defaults is not a Properties object.
51

METHODS

53       get_property($key, [$default_value])
54           Searches for the property with the specified key in this property
55           list. If the key is not found in this property list, the default
56           property list and its defaults are recursively checked. If the
57           property is not found, $default_value is returned if specified, or
58           "undef" otherwise.
59
60       load($handle)
61           Reads a property list from the specified input handle.
62
63           Every property occupies one line read from the input handle. Lines
64           from the input handle are processed until EOF is reached.
65
66           A line that contains only whitespace or whose first non-whitespace
67           character is an ASCII "#" or "!" is ignored (thus, these characters
68           indicate comment lines).
69
70           Every line other than a blank line or a comment line describes one
71           property to be added to the property list (except that if a line
72           ends with "\", then the following line, if it exists, is treated as
73           a continuation line, as described below). The key consists of all
74           the characters in the line starting with the first non-whitespace
75           character and up to, but not including, the first ASCII "=", ":",
76           or whitespace character. Any whitespace after the key is skipped;
77           if the first non-whitespace character after the key is "=" or ":",
78           then it is ignored and any whitespace characters after it are also
79           skipped. All remaining characters on th eline become part of the
80           associated value. If the last character on the line is "\", then
81           the next line is treated as a continuation of the current line; the
82           "\" and line terminator are simply discarded, and any leading
83           whitespace characters on the continuation line are also discarded
84           and not part of the element string.
85
86           As an example, each of the following lines specifies the key
87           "Truth" and the associated element value "Beauty":
88
89             Truth = Beauty
90                   Truth:Beauty
91             Truth                        :Beauty
92
93           As another example, the following three lines specify a single
94           property:
95
96             fruits                        apple, banana, pear, \
97                                           cantaloupe, watermelon, \
98                                           kiwi, mango
99
100           The key is "fruits" and the associated element is "apple, banana,
101           pear, cantaloupe, watermelon, kiwi, mango".
102
103           Note that a space appears before each "\" so that a space will
104           appear after each comma in the final value; the "\", line
105           terminator, and leading whitespace on the continuation line are
106           merely discarded and are "not" replaced by one or more characters.
107
108           As a third example, the line:
109
110             cheeses:
111
112           specifies that the key is "cheeses" and the associated element is
113           the empty string.
114
115           Dies if an error occurs when reading from the input handle.
116
117       property_names
118           Returns an array (or an arrayref in scalar context) containing all
119           of the keys in this property list, including the keys in the
120           default property list.
121
122       set_property($key, $value)
123           Sets the property with the specified key.
124
125       store($handle, $header)
126           Writes this property list to the specified output handle. Default
127           properties are not written by this method.
128
129           If a header is specified, then the ASCII characters "# ", the
130           header string, and a line separator are first written to the output
131           handle. Thus the header can serve as an identifying comment.
132
133           Next, a comment line is always written, consisting of the ASCII
134           characters "# ", the current date and time (as produced by
135           POSIX::ctime()), and a line separator.
136
137           Then every entry in the property list is written out, one per line.
138           For each entry the key string is written, then an ASCII "=", then
139           the associated value.
140
141           The output handle remains open after this method returns.
142
143           Dies if an error occurs when writing to the input handle.
144

TODO

146       o   Read and write escaped characters in property keys and values.
147
148           In values only, the ASCII characters backslash, tab, newline,
149           carriage return, double quote, and single quote should be stored as
150           the literal strings "\\", "\t", "\n", "\r", "\"", and "\'"
151           respectively, and those literal strings should be converted into
152           the corresponding ASCII characters when loading properties. The
153           same goes for leading spaces (converted into "\ "), but not
154           embedded or trailing spaces.
155
156           In keys and values, the ASCII characters "#", "!", "=", and ":"
157           should be stored with a preceding "\", and those literal strings
158           should be unescaped when loading properties.
159

ISSUES

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

AUTHOR

171       Brian Moseley, bcm@maz.org (original version).
172
173       Johan Vromans, jv@cpan.org (revived version).
174

POD ERRORS

176       Hey! The above document had some coding errors, which are explained
177       below:
178
179       Around line 346:
180           You forgot a '=back' before '=head1'
181
182       Around line 353:
183           =back without =over
184
185
186
187perl v5.36.0                      2023-01-20                     Properties(3)