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
41       "sprintf()", so you almost always want to use simple keys and values,
42       not arrays, or hashes, or references. Keys and values are loaded and
43       stored "as-is"; no character or other conversions are performed on
44       them.
45

CONSTRUCTOR

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

METHODS

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

TODO

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

ISSUES

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

AUTHOR

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

POD ERRORS

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