1Config::Record(3) User Contributed Perl Documentation Config::Record(3)
2
6 Config::Record - Configuration file access
7
9 use Config::Record;
10 # Create an empty record & then load from file
13 my $config = Config::Record->new();
14 $config->load("/etc/myapp.cfg");
15 # Create & load, then save to filename
17 my $config = Config::Record->new(file => "/etc/myapp.cfg");
18 $config->save("/etc/myapp.cfg");
19 # 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 # Get a config value, throw error if not found
26 my $value = $config->get("foo");
27 # Get a config value, return 'eek' if not found
29 my $value = $config->get("foo", "eek");
30 # Set a value
32 $config->set("foobar", "wizz");
33 # Get a deep config value (ie nested hash)
35 my $value = $config->get("foo/bar", "eek");
36 # Get first element of an array param
38 my $value = $config->get("people/[0]/forename");
39 # Get the raw hash reference forming the record
41 my $record = $config->record();
42 # Get a new config object rooted at a sub-hash
44 my $config = $config->view("foo");
45
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 foo = Wizz
56 foo = "Wizz.... "
57 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 foo = This is a long \
63 line of text
64 foo = "This is a long " \
65 "line of text"
66 Multi-line strings can be provided as 'HERE' documents, eg
68 foo = <<EOF
70 This is a multiple paragraph
71 block of text with newlines
72 preserved
73 EOF
74 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 foo = (
79 Wizz
80 "Wizz... "
81 )
82 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 foo = {
87 one = Wizz
88 two = "Wizz.... "
89 }
90 Arrays and hashes can be nested to arbitrary depth.
92
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
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 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 EXAMPLE
128 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 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 EXAMPLE
145 In the main file
147 name = Foo
149 title = "Wizz bang wallop"
150 foo = @include(somefile.cfg)
151 And in somefile.cfg
153 firstname = Joe
155 lastname = Blogs
156 Is equivalent to
158 name = Foo
160 title = "Wizz bang wallop"
161 foo = {
162 firstname = Joe
163 lastname = Blogs
164 }
165
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 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 $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 $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 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 $config->set($key, $value);
202 Sets the value of a configuration parameter corresponding to the
203 name "key".
204 $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 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
217 Config::Record has the following limitations
218 • If you load and then save a configuration file all comments are
220 removed & whitespace normalized.
221 • Ordering of elements in hash ref are not preserved across load and
223 save sequence
224 These limitations may be fixed in a future release if there is demand
226 from users...
227
229 Daniel Berrange <dan@berrange.com>
230
232 Copyright (C) 2000-2007 Daniel P. Berrange <dan@berrange.com>
233
235 perl(1)
236perl v5.34.0 2021-07-22 Config::Record(3)