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
12 my $config = Config::Record->new();
13 $config->load("/etc/myapp.cfg");
14 # Create & load, then save to filename
16 my $config = Config::Record->new(file => "/etc/myapp.cfg");
17 $config->save("/etc/myapp.cfg");
18 # Load / save from filehandle
20 my $fh = IO::File->new("/etc/myapp.cfg");
21 my $config = Config::Record->new(file => $fh);
22 $config->save($fh);
23 # Get a config value, throw error if not found
25 my $value = $config->get("foo");
26 # Get a config value, return 'eek' if not found
28 my $value = $config->get("foo", "eek");
29 # Set a value
31 $config->set("foobar", "wizz");
32 # Get a deep config value (ie nested hash)
34 my $value = $config->get("foo/bar", "eek");
35 # Get first element of an array param
37 my $value = $config->get("people/[0]/forename");
38 # Get the raw hash reference forming the record
40 my $record = $config->record();
41 # Get a new config object rooted at a sub-hash
43 my $config = $config->view("foo");
44
46 This module provides an API for loading and saving of simple configura‐
47 tion file records. Entries in the configuration file are essentially
48 key,value pairs, with the key and values separated by a single equals
49 symbol. The "key" consists only of alphanumeric characters. There are
50 three types of values, scalar values can contain anything except new‐
51 lines. Trailing whitespace will be trimmed unless the value is sur‐
52 rounded in double quotes. eg
53 foo = Wizz
55 foo = "Wizz.... "
56 Long lines can be split with a backslash character, without introducing
58 newlines. Without double quotes, whitespace at beginning and end of
59 lines will be trimmed eg
60 foo = This is a long \
62 line of text
63 foo = "This is a long " \
64 "line of text"
65 Multi-line strings can be provided as 'HERE' documents, eg
67 foo = <<EOF
69 This is a multiple paragraph
70 block of text with newlines
71 preserved
72 EOF
73 Array values consist of a single right round bracket, following by one
75 "value" per line, terminated by a single left round bracket. eg
76 foo = (
78 Wizz
79 "Wizz... "
80 )
81 Hash values consist of a single right curly bracket, followed by one
83 key,value pair per line, terminated by a single left curly bracket. eg
84 foo = {
86 one = Wizz
87 two = "Wizz.... "
88 }
89 Arrays and hashes can be nested to arbitrary depth.
91
93 name = Foo
94 title = "Wizz bang wallop"
95 eek = (
96 OOhh
97 Aahhh
98 Wizz
99 )
100 people = (
101 {
102 forename = John
103 surnamne = Doe
104 }
105 {
106 forename = Some
107 surname = One
108 }
109 )
110 wizz = {
111 foo = "Elk"
112 ooh = "fds"
113 }
114
116 my $config = Config::Record->new([file => $file]);
117 Creates a new config object, loading parameters from the file spec‐
118 ified by the "file" parameter. The "file" parameter can either be a
119 string representing a fully qualified filename, or a IO::Handle
120 object. If the "file" parameter is a string, this filename will be
121 saved and future calls to "load" or "save" are permitted to omit
122 the filename. If the "file" parameter is not supplied then an empty
123 configuration record is created.
124 $config->load([$file]);
126 Loads and parses a configuration record. The "file" parameter can
127 either be a string representing a fully qualified filename, or an
128 IO::Handle object. The $file parameter may be omitted, if a file‐
129 name was specified in the constructor, or in previous calls to
130 "load" or "save". Prior to loading the record, the current contents
131 of this configuration are cleared.
132 $config->save([$file]);
134 Saves the configuration record to a file. The "file" parameter can
135 either be a string representing a fully qualified filename, or an
136 IO::Handle object opened for writing. The $file parameter may be
137 omitted, if a filename was specified in the constructor, or in
138 previous calls to "load" or "save".
139 my $value = $config->get($key[, $default]);
141 Gets the value of a configuration parameter corresponding to the
142 name "key". If there is no value in the record, then the optional
143 "default" is returned.
144 $config->set($key, $value);
146 Sets the value of a configuration parameter corresponding to the
147 name "key".
148 $config->view($key)
150 Return a new Config::Record object, rooted at the specified key.
151 If the key doesn't resolve to a hash reference an error will be
152 raised.
153 my $record = $config->record();
155 Retrieves a hash reference for the entire configuration record.
156 Currently this is the actual internal storage record, so changes
157 will modify the configuration. In the next release this will be
158 changed to be a deep clone of the internal storage record.
159
161 Config::Record has the following limitations
162 · If you load and then save a configuration file all comments are
164 removed & whitespace normalized.
165 · Ordering of elements in hash ref are not preserved across load and
167 save sequence
168 These limitations may be fixed in a future release if there is demand
170 from users...
171
173 Daniel Berrange <dan@berrange.com>
174
176 Copyright (C) 2000-2004 Daniel P. Berrange <dan@berrange.com>
177
179 perl(1)
180perl v5.8.8 2006-06-03 Config::Record(3)