Config::Properties(3pm)

1Config::Properties(3) User Contributed Perl DocumentationConfig::Properties(3)
2
3
4

NAME

6       Config::Properties - Read and write property files
7

SYNOPSIS

9         use Config::Properties;
10
11         # reading...
12
13         open my $fh, '<', 'my_config.props'
14           or die "unable to open configuration file";
15
16         my $properties = Config::Properties->new();
17         $properties->load($fh);
18
19         $value = $properties->getProperty($key);
20
21
22         # saving...
23
24         open my $fh, '>', 'my_config.props'
25           or die "unable to open configuration file for writing";
26
27         $properties->setProperty($key, $value);
28
29         $properties->format('%s => %s');
30         $properties->store($fh, $header );
31

DESCRIPTION

33       Config::Properties is a near implementation of the java.util.Properties
34       API.  It is designed to allow easy reading, writing and manipulation of
35       Java-style property files.
36
37       The format of a Java-style property file is that of a key-value pair
38       separated by either whitespace, the colon (:) character, or the equals
39       (=) character.  Whitespace before the key and on either side of the
40       separator is ignored.
41
42       Lines that begin with either a hash (#) or a bang (!) are considered
43       comment lines and ignored.
44
45       A backslash (\) at the end of a line signifies a continuation and the
46       next line is counted as part of the current line (minus the backslash,
47       any whitespace after the backslash, the line break, and any whitespace
48       at the beginning of the next line).
49
50       The official references used to determine this format can be found in
51       the Java API docs for java.util.Properties at
52       <http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html>.
53
54       When a property file is saved it is in the format "key=value" for each
55       line. This can be changed by setting the format attribute using either
56       $object->format( $format_string ) or $object->setFormat( $format_string
57       ) (they do the same thing). The format string is fed to printf and must
58       contain exactly two %s format characters. The first will be replaced
59       with the key of the property and the second with the value. The string
60       can contain no other printf control characters, but can be anything
61       else. A newline will be automatically added to the end of the string.
62       The current format string can be obtained by using $object->format()
63       (with no arguments) or $object->getFormat().
64
65       If a recent version of Text::Wrap is available, long lines are
66       conveniently wrapped when saving.
67

METHODS

69       "Config::Property" objects have this set of methods available:
70
71       Config::Properties->new(%opts)
72           Creates a new Config::Properties object.
73
74           The optional arguments are as follows:
75
76           file => $filename
77               Opens and reads the entries from the given properties file
78
79           format => $format
80               Sets the format using for saving the properties to a file. See
81               "setFormat".
82
83           wrap => 0
84               Disables wrapping of long lines when saving the properties to a
85               file.
86
87           defaults => $defaults
88               Default configuration values.
89
90               The given parameter can be a hash reference or another
91               Config::Properties object.
92
93               In that way several configuration objects can be chained. For
94               instance:
95
96                 my %defaults = (...);
97                 my $global_config = Config::Properties->new(file => '/etc/foo.properties',
98                                                             defaults => \%defaults);
99                 my $user_config = Config::Properties->new(file => '/home/jsmith/.foo/foo.properties',
100                                                           defaults => $global_config);
101
102           order => 'keep'|'alpha'|'none'
103               Sets how to order the properties when saved to a file or when
104               returned by "properties" and "propertyNames" methods.
105
106               "alpha" sorts the keys in alphanumeric order. "keep" keeps the
107               order of the properties as added or read from a file. "none"
108               returns the properties unordered.
109
110           encoding => $encoding
111               IO encoding used to read the configuration file. See PerlIO.
112
113               When "load" is called the given encoding is used unless the
114               file handler already has a encoding layer applied.
115
116               "latin1" is used as the default encoding (as specified in the
117               Java properties specification).
118
119           be_like_java => 1
120               When this feature is enabled, the module will try to mimic the
121               Java implementation as much as possible when saving files.
122
123               Currently, some escaping rules are changed and line wrapping is
124               disabled.
125
126       Config::Properties->new($defaults)
127           Calling "new" in this way is deprecated.
128
129       $p->getProperty($k, $default, $default2, ...)
130           return property $k or when not defined, the first defined
131           "$default*".
132
133       $p->requireProperty($k, $default, $default2, ...)
134           this method is similar to "getProperty" but dies if the requested
135           property is not found.
136
137       $p->setProperty($k, $v)
138           set property $k value to $v.
139
140       $p->changeProperty($k, $v)
141       $p->changeProperty($k, $v, $default, $default2, ...)
142           method similar to "setPropery" but that does nothing when the new
143           value is equal to the one returned by "getProperty".
144
145           An example shows why it is useful:
146
147             my $defaults=Config::Properties->new();
148             $defaults->setProperty(foo => 'bar');
149
150             my $p1=Config::Properties->new($defaults);
151             $p1->setProperty(foo => 'bar');   # we set here!
152             $p1->store(FILE1); foo gets saved on the file
153
154             my $p2=Config::Properties->new($defaults);
155             $p2->changeProperty(foo => 'bar'); # does nothing!
156             $p2->store(FILE2); # foo doesn't get saved on the file
157
158       $p->deleteProperty($k)
159       $p->deleteProperty($k, $recurse)
160           deletes property $k from the object.
161
162           If $recurse is true, it also deletes any $k property from the
163           default properties object.
164
165       $p->properties
166           returns a flatten hash with all the property key/value pairs, i.e.:
167
168             my %props=$p->properties;
169
170       $p->getProperties
171           returns a hash reference with all the properties (including those
172           passed as defaults).
173
174       $p->propertyNames;
175           returns the names of all the properties (including those passed as
176           defaults).
177
178       $p->splitToTree()
179       $p->splitToTree($regexp)
180       $p->splitToTree($regexp, $start)
181           builds a tree from the properties, splitting the keys with the
182           regular expression $re (or "/\./" by default). For instance:
183
184             my $data = <<EOD;
185             name = pete
186             date.birth = 1958-09-12
187             date.death = 2004-05-11
188             surname = moo
189             surname.length = 3
190             EOD
191
192             open my $fh, '<', \$data;
193             $cfg->load();
194             my $tree = $cfg->splitToTree();
195
196           makes...
197
198             $tree = { date => { birth => '1958-09-12',
199                                 death => '2004-05-11' },
200                       name => 'pete',
201                       surname => { '' => 'moo',
202                                    length => '3' } };
203
204           The $start parameter allows to split only a subset of the
205           properties. For instance, with the same data as on the previous
206           example:
207
208              my $subtree = $cfg->splitToTree(qr/\./, 'date');
209
210           makes...
211
212             $tree = { birth => '1958-09-12',
213                       death => '2004-05-11' };
214
215       $p->setFromTree($tree)
216       $p->setFromTree($tree, $separator)
217       $p->setFromTree($tree, $separator, $start)
218           This method sets properties from a tree of Perl hashes and arrays.
219           It is the opposite of "splitToTree".
220
221           $separator is the string used to join the parts of the property
222           names. The default value is a dot (".").
223
224           $start is a string used as the starting point for the property
225           names.
226
227           For instance:
228
229             my $c = Config::Properties->new;
230             $c->setFromTree( { foo => { '' => one,
231                                         hollo => [2, 3, 4, 1] },
232                                bar => 'doo' },
233                              '->',
234                              'mama')
235
236             # sets properties:
237             #      mama->bar = doo
238             #      mama->foo = one
239             #      mama->foo->hollo->0 = 2
240             #      mama->foo->hollo->1 = 3
241             #      mama->foo->hollo->2 = 4
242             #      mama->foo->hollo->3 = 1
243
244       $p->changeFromTree($tree)
245       $p->changeFromTree($tree, $separator)
246       $p->changeFromTree($tree, $separator, $start)
247           similar to "setFromTree" but internally uses "changeProperty"
248           instead of "setProperty" to set the property values.
249
250       $p->load($file)
251           loads properties from the open file $file.
252
253           Old properties on the object are discarded.
254
255       $p->save($file)
256       $p->save($file, $header)
257       $p->store($file)
258       $p->store($file, $header)
259           save the properties to the open file $file. Default properties are
260           not saved.
261
262       $p->saveToString($header)
263           similar to "save", but instead of saving to a file, it returns a
264           string with the content.
265
266       $p->getFormat()
267       $p->setFormat($f)
268           get/set the format string used when saving the object to a file.
269

TODO

278       Add support for derived format as supported by Java class
279       org.apache.commons.configuration.PropertiesConfiguration
280       (<http://commons.apache.org/configuration/apidocs/org/apache/commons/configuration/PropertiesConfiguration.html>)
281

AUTHORS

283       "Config::Properties" was originally developed by Randy Jay Yarger. It
284       was maintained for some time by Craig Manley and finally it passed
285       hands to Salvador Fandiño <sfandino@yahoo.com>, the current maintainer.
286

COPYRIGHT AND LICENSE

288       Copyright 2001, 2002 by Randy Jay Yarger Copyright 2002, 2003 by Craig
289       Manley.  Copyright 2003-2009, 2011-2012, 2014-2015 by Salvador Fandiño.
290
291       This library is free software; you can redistribute it and/or modify it
292       under the same terms as Perl itself.
293
294
295
296perl v5.34.0                      2021-07-22             Config::Properties(3)