1Config::Record(3)     User Contributed Perl Documentation    Config::Record(3)
2
3
4

NAME

6       Config::Record - Configuration file access
7

SYNOPSIS

9         use Config::Record;
10
11
12         # Create an empty record & then load from file
13         my $config = Config::Record->new();
14         $config->load("/etc/myapp.cfg");
15
16         # Create & load, then save to filename
17         my $config = Config::Record->new(file => "/etc/myapp.cfg");
18         $config->save("/etc/myapp.cfg");
19
20         # Load / save from filehandle
21         my $fh = IO::File->new("/etc/myapp.cfg");
22         my $config = Config::Record->new(file => $fh);
23         $config->save($fh);
24
25         # Get a config value, throw error if not found
26         my $value = $config->get("foo");
27
28         # Get a config value, return 'eek' if not found
29         my $value = $config->get("foo", "eek");
30
31         # Set a value
32         $config->set("foobar", "wizz");
33
34         # Get a deep config value (ie nested hash)
35         my $value = $config->get("foo/bar", "eek");
36
37         # Get first element of an array param
38         my $value = $config->get("people/[0]/forename");
39
40         # Get the raw hash reference forming the record
41         my $record = $config->record();
42
43         # Get a new config object rooted at a sub-hash
44         my $config = $config->view("foo");
45

DESCRIPTION

47       This module provides an API for loading and saving of simple
48       configuration file records. Entries in the configuration file are
49       essentially key,value pairs, with the key and values separated by a
50       single equals symbol. The "key" consists only of alphanumeric
51       characters. There are three types of values, scalar values can contain
52       anything except newlines. Trailing whitespace will be trimmed unless
53       the value is surrounded in double quotes. eg
54
55         foo = Wizz
56         foo = "Wizz....    "
57
58       Long lines can be split with a backslash character, without introducing
59       newlines. Without double quotes, whitespace at beginning and end of
60       lines will be trimmed eg
61
62         foo = This is a long \
63               line of text
64         foo = "This is a long " \
65               "line of text"
66
67       Multi-line strings can be provided as 'HERE' documents, eg
68
69         foo = <<EOF
70       This is a multiple paragraph
71       block of text with newlines
72       preserved
73       EOF
74
75       Array values  consist of a single right round bracket, following by one
76       "value" per line, terminated by a single left round bracket. eg
77
78         foo = (
79           Wizz
80           "Wizz...    "
81         )
82
83       Hash values consist of a single right curly bracket, followed by one
84       key,value pair per line, terminated by a single left curly bracket.  eg
85
86         foo = {
87           one = Wizz
88           two = "Wizz....  "
89         }
90
91       Arrays and hashes can be nested to arbitrary depth.
92

EXAMPLE

94         name = Foo
95         title = "Wizz bang wallop"
96         eek = (
97           OOhh
98           Aahhh
99           Wizz
100         )
101         people = (
102           {
103             forename = John
104             surnamne = Doe
105           }
106           {
107             forename = Some
108             surname = One
109           }
110         )
111         wizz = {
112           foo = "Elk"
113           ooh = "fds"
114         }
115

EXTRA PARSER FEATURES

117       The syntax described thus far is classed as the base feature set. By
118       passing the "features" parameter when creating an instance of the
119       "Config::Record" class, it is posible to turn on certain extra features
120
121   QUOTED NON-ALPHANUMERIC KEYS
122       The keys for configuration parameters are normally restricted to only
123       contain the characters 'a-Z', '0-9', '_', '-' and '.'. Sometimes it is
124       desirable to allow arbitrary characters for keys. If this capability is
125       required then the "quotedkeys" parameter can be set.
126
127       EXAMPLE
128
129         name = Foo
130         title = "Wizz bang wallop"
131         " some parameter " = (
132            foo
133            bar
134         }
135         "an embeded \" quote" = bar
136         "an embeded \\ backslash" = wizz
137
138   EXTERNAL INCLUDE FILES
139       With large configuration files it can be desirable to split them into a
140       number of smaller files. If this capability is required, then the
141       "includes" feature can be requested. Each included file must follow the
142       syntax rules already described.
143
144       EXAMPLE
145
146       In the main file
147
148         name = Foo
149         title = "Wizz bang wallop"
150         foo = @include(somefile.cfg)
151
152       And in somefile.cfg
153
154         firstname = Joe
155         lastname = Blogs
156
157       Is equivalent to
158
159         name = Foo
160         title = "Wizz bang wallop"
161         foo = {
162           firstname = Joe
163           lastname = Blogs
164         }
165

METHODS

167       my $config = Config::Record->new([file => $file], [features =>
168       \%features]);
169           Creates a new config object, loading parameters from the file
170           specified by the "file" parameter. The "file" parameter can either
171           be a string representing a fully qualified filename, or a
172           IO::Handle object. If the "file" parameter is a string, this
173           filename will be saved and future calls to "load" or "save" are
174           permitted to omit the filename. If the "file" parameter is not
175           supplied then an empty configuration record is created.
176
177           The "features" parameter allows extra parser features to be
178           enabled.  The two valid keys for the associated hash as "includes"
179           and "quotedkeys" as described earlier in this document.
180
181       $config->load([$file]);
182           Loads and parses a configuration record. The "file" parameter can
183           either be a string representing a fully qualified filename, or an
184           IO::Handle object. The $file parameter may be omitted, if a
185           filename was specified in the constructor, or in previous calls to
186           "load" or "save". Prior to loading the record, the current contents
187           of this configuration are cleared.
188
189       $config->save([$file]);
190           Saves the configuration record to a file. The "file" parameter can
191           either be a string representing a fully qualified filename, or an
192           IO::Handle object opened for writing. The $file parameter may be
193           omitted, if a filename was specified  in the constructor, or in
194           previous calls to "load" or "save".
195
196       my $value = $config->get($key[, $default]);
197           Gets the value of a configuration parameter corresponding to the
198           name "key". If there is no value in the record, then the optional
199           "default" is returned.
200
201       $config->set($key, $value);
202           Sets the value of a configuration parameter corresponding to the
203           name "key".
204
205       $config->view($key)
206           Return a new Config::Record object, rooted at the specified key.
207           If the key doesn't resolve to a hash reference an error will be
208           raised.
209
210       my $record = $config->record();
211           Retrieves a hash reference for the entire configuration record.
212           Currently this is the actual internal storage record, so changes
213           will modify the configuration. In the next release this will be
214           changed to be a deep clone of the internal storage record.
215

BUGS

217       Config::Record has the following limitations
218
219       •   If you load and then save a configuration file all comments are
220           removed & whitespace normalized.
221
222       •   Ordering of elements in hash ref are not preserved across load and
223           save sequence
224
225       These limitations may be fixed in a future release if there is demand
226       from users...
227

AUTHORS

229       Daniel Berrange <dan@berrange.com>
230
232       Copyright (C) 2000-2007 Daniel P. Berrange <dan@berrange.com>
233

SEE ALSO

235       perl(1)
236
237
238
239perl v5.32.1                      2021-01-27                 Config::Record(3)
Impressum