Config::Properties(3pm)

1Properties(3)         User Contributed Perl Documentation        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 PROPS, "< my_config.props"
14           or die "unable to open configuration file";
15
16         my $properties = new Config::Properties();
17         $properties->load(*PROPS);
18
19         $value = $properties->getProperty( $key );
20
21
22         # saving...
23
24         open PROPS, "> 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(*PROPS, $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       seperated by either whitespace, the colon (:) character, or the equals
39       (=) character.  Whitespace before the key and on either side of the
40       seperator 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       You an get the current format string either by using $object->format()
63       (with no arguments) or $object->getFormat().
64
65       If a recent version of module 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()
72       Config::Properties->new($defaults)
73           creates a new Config::Properties object. The optional $defaults
74           parameter can be used to pass another Config::Properties object
75           holding default property values.
76
77       $p->getProperty($k, $default, $default2, ...)
78           return property $k or when not defined, the first defined
79           "$default*".
80
81       $p->requireProperty($k, $default, $default2, ...)
82           this method is similar to "getProperty" but dies if the requested
83           property is not found.
84
85       $p->setProperty($k, $v)
86           set property $k value to $v.
87
88       $p->changeProperty($k, $v)
89       $p->changeProperty($k, $v, $default, $default2, ...)
90           method similar to "setPropery" but that does nothing when the new
91           value is equal to the one returned by "getProperty".
92
93           An example shows why it is useful:
94
95             my $defaults=Config::Properties->new();
96             $defaults->setProperty(foo => 'bar');
97
98             my $p1=Config::Properties->new($defaults);
99             $p1->setProperty(foo => 'bar');   # we set here!
100             $p1->store(FILE1); foo gets saved on the file
101
102             my $p2=Config::Properties->new($defaults);
103             $p2->changeProperty(foo => 'bar'); # does nothing!
104             $p2->store(FILE2); # foo doesn't get saved on the file
105
106       $p->deleteProperty($k)
107       $p->deleteProperty($k, $recurse)
108           deletes property $k from the object.
109
110           If $recurse is true, it also deletes any $k property from the
111           default properties object.
112
113       $p->properties
114           returns a flatten hash with all the property key/value pairs, i.e.:
115
116             my %props=$p->properties;
117
118       $p->getProperties
119           returns a hash reference with all the properties (including those
120           passed as defaults).
121
122       $p->propertyNames;
123           returns the names of all the properties (including those passed as
124           defaults).
125
126       $p->splitToTree()
127       $p->splitToTree($regexp)
128       $p->splitToTree($regexp, $start)
129           builds a tree from the properties, splitting the keys with the
130           regular expression $re (or "/\./" by default). For instance:
131
132             my $data = <<EOD;
133             name = pete
134             date.birth = 1958-09-12
135             date.death = 2004-05-11
136             surname = moo
137             surname.length = 3
138             EOD
139
140             open my $fh, '<', \$data;
141             $cfg->load();
142             my $tree = $cfg->splitToTree();
143
144           makes...
145
146             $tree = { date => { birth => '1958-09-12',
147                                 death => '2004-05-11' },
148                       name => 'pete',
149                       surname => { '' => 'moo',
150                                    length => '3' } };
151
152           The $start parameter allows to split only a subset of the
153           properties. For instance, with the same data as on the previous
154           example:
155
156              my $subtree = $cfg->splitToTree(qr/\./, 'date');
157
158           makes...
159
160             $tree = { birth => '1958-09-12',
161                       death => '2004-05-11' };
162
163       $p->setFromTree($tree)
164       $p->setFromTree($tree, $separator)
165       $p->setFromTree($tree, $separator, $start)
166           This method sets properties from a tree of Perl hashes and arrays.
167           It is the opposite to splitToTree.
168
169           $separator is the string used to join the parts of the property
170           names. The default value is a dot (".").
171
172           $start is a string used as the starting point for the property
173           names.
174
175           For instance:
176
177             my $c = Config::Properties->new;
178             $c->setFromTree( { foo => { '' => one,
179                                         hollo => [2, 3, 4, 1] },
180                                bar => 'doo' },
181                              '->',
182                              'mama')
183
184             # sets properties:
185             #      mama->bar = doo
186             #      mama->foo = one
187             #      mama->foo->hollo->0 = 2
188             #      mama->foo->hollo->1 = 3
189             #      mama->foo->hollo->2 = 4
190             #      mama->foo->hollo->3 = 1
191
192       $p->changeFromTree($tree)
193       $p->changeFromTree($tree, $separator)
194       $p->changeFromTree($tree, $separator, $start)
195           similar to "setFromTree" but internally uses "changeProperty"
196           instead of "setProperty" to set the property values.
197
198       $p->load($file)
199           loads properties from the open file $file.
200
201           Old properties on the object are forgotten.
202
203       $p->save($file)
204       $p->save($file, $header)
205       $p->store($file)
206       $p->store($file, $header)
207           save the properties to the open file $file. Default properties are
208           not saved.
209
210       $p->saveToString($header)
211           similar to "save", but instead of saving to a file, it returns a
212           string with the content.
213
214       $p->getFormat()
215       $p->setFormat($f)
216           get/set the format string used when saving the object to a file.
217

AUTHORS

226       "Config::Properties" was originally developed by Randy Jay Yarger. It
227       was mantained for some time by Craig Manley and finally it passed hands
228       to Salvador Fandin~o <sfandino@yahoo.com>, the current maintainer.
229

COPYRIGHT AND LICENSE

231       Copyright 2001, 2002 by Randy Jay Yarger Copyright 2002, 2003 by Craig
232       Manley.  Copyright 2003-2006 by Salvador Fandin~o.
233
234       This library is free software; you can redistribute it and/or modify it
235       under the same terms as Perl itself.
236
237
238
239perl v5.12.0                      2009-04-22                     Properties(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

AUTHORS

COPYRIGHT AND LICENSE