1Config::Model::Backend:U:sIenriFCiolnet(r3i)buted Perl DCoocnufmiegn:t:aMtoidoenl::Backend::IniFile(3)
2
6 Config::Model::Backend::IniFile - Read and write config as a INI file
7
9 version 2.129
10
12 use Config::Model;
13 my $model = Config::Model->new;
15 $model->create_config_class (
16 name => "IniClass",
17 element => [
18 [qw/foo bar/] => {
19 type => 'list',
20 cargo => {qw/type leaf value_type string/}
21 }
22 ]
23 );
24 # model for free INI class name and constrained class parameters
26 $model->create_config_class(
27 name => "MyClass",
28 element => [
30 ini_class => {
31 type => 'hash',
32 index_type => 'string',
33 cargo => {
34 type => 'node',
35 config_class_name => 'IniClass'
36 },
37 },
38 ],
39 rw_config => {
41 backend => 'IniFile',
42 config_dir => '/tmp',
43 file => 'foo.conf',
44 store_class_in_hash => 'ini_class',
45 auto_create => 1,
46 }
47 );
48 my $inst = $model->instance(root_class_name => 'MyClass' );
50 my $root = $inst->config_root ;
51 $root->load('ini_class:ONE foo=FOO1 bar=BAR1 -
53 ini_class:TWO foo=FOO2' );
54 $inst->write_back ;
56 Now "/tmp/foo.conf" contains:
58 ## file written by Config::Model
60 [ONE]
61 foo=FOO1
62 bar=BAR1
64 [TWO]
66 foo=FOO2
67
69 This module is used directly by Config::Model to read or write the
70 content of a configuration tree written with INI syntax in
71 "Config::Model" configuration tree.
72 This INI file can have arbitrary comment delimiter. See the example in
74 the SYNOPSIS that sets a semi-column as comment delimiter. By default
75 the comment delimiter is '#' like in Shell or Perl.
76 Note that undefined values are skipped for list element. I.e. when a
78 list element contains "('a',undef,'b')", the data structure contains
79 'a','b'.
80
82 Structure
83 Structure of the Config::Model must be very simple. Either:
84 · A single class with hash of leaves elements.
86 · 2 levels of classes. The top level has nodes elements. All other
88 classes have only leaf elements.
89
91 This backend tries to read and write comments from configuration file.
92 The comments are stored as annotation within the configuration tree.
93 Comments extraction is based on best estimation as to which parameter
94 the comment may apply. Wrong estimations are possible.
95
97 new
98 Parameters: "( node => $node_obj, name => 'inifile' )"
99 Inherited from Config::Model::Backend::Any. The constructor is called
101 by Config::Model::BackendMgr.
102
104 Optional parameters declared in the model:
105 comment_delimiter
107 Change the character that starts comments in the INI file. Default
108 is '"#"'.
109 Some Ini files allows comments to begin with several characters
111 (e.g. "#" or ";"). In this case, set "comment_delimiter" to the
112 possible characters (e.g ""#;""). The first character is used to
113 write back comments. (In the example above, comment "; blah" is
114 written back as "# blah".
115 store_class_in_hash
117 See "Arbitrary class name"
118 section_map
120 Is a kind of exception of the above rule. See also "Arbitrary class
121 name"
122 force_lc_section
124 Boolean. When set, sections names are converted to lowercase.
125 force_lc_key
127 Idem for key name
128 force_lc_value
130 Idem for all values.
131 split_list_value
133 Some INI values are in fact a list of items separated by a space or
134 a comma. This parameter specifies the regex to use to split the
135 value into a list. This applies only to "list" elements.
136 join_list_value
138 Conversely, the list element split with "split_list_value" needs to
139 be written back with a string to join them. Specify this string
140 (usually ' ' or ', ') with "join_list_value".
141 split_check_list_value
143 Some INI values are in fact a check list of items separated by a
144 space or a comma. This parameter specifies the regex to use to
145 split the value read from the file into a list of items to check.
146 This applies only to "check_list" elements.
147 join_check_list_value
149 Conversely, the check_list element split with "split_list_value"
150 needs to be written back with a string to join them. Specify this
151 string (usually ' ' or ', ') with "join_check_list_value".
152 write_boolean_as
154 Array ref. Reserved for boolean value. Specify how to write a
155 boolean value. Default is "[0,1]" which may not be the most
156 readable. "write_boolean_as" can be specified as "['false','true']"
157 or "['no','yes']".
158 assign_char
160 Character used to assign value in INI file. Default is "=".
161 assign_with
163 String used write assignment in INI file. Default is "" = "".
164
166 INI file typically have the same structure with 2 different
167 conventions. The class names can be imposed by the application or may
168 be chosen by user.
169 Imposed class name
171 In this case, the class names must match what is expected by the
172 application. The elements of each class can be different. For
173 instance:
174 foo = foo_v
176 [ A ]
177 bar = bar_v
178 [ B ]
179 baz = baz_v
180 In this case, class "A" and class "B" do not use the same configuration
182 class.
183 The model has this structure:
185 Root class
187 |- leaf element foo
188 |- node element A of class_A
189 | \- leaf element bar
190 \- node element B of class_B
191 \- leaf element baz
192 Arbitrary class name
194 In this case, the class names can be chosen by the end user. Each class
195 has the same elements. For instance:
196 foo = foo_v
198 [ A ]
199 bar = bar_v1
200 [ B ]
201 bar = bar_v2
202 In this case, class "A" and class "B" do not use the same configuration
204 class. The model has this structure:
205 Root class
207 |- leaf foo
208 \- hash element my_class_holder
209 |- key A (value is node of class_A)
210 | \- element-bar
211 \- key B (value is node of class_A)
212 \- element-bar
213 In this case, the "my_class_holder" name is specified in "rw_config"
215 with "store_class_in_hash" parameter:
216 rw_config => {
218 backend => 'IniFile',
219 config_dir => '/tmp',
220 file => 'foo.ini',
221 store_class_in_hash => 'my_class_holder',
222 }
223 Of course they are exceptions. For instance, in "Multistrap", the
225 "[General]" INI class must be mapped to a specific node object. This
226 can be specified with the "section_map" parameter:
227 rw_config => }
229 backend => 'IniFile',
230 config_dir => '/tmp',
231 file => 'foo.ini',
232 store_class_in_hash => 'my_class_holder',
233 section_map => {
234 General => 'general_node',
235 }
236 }
237 "section_map" can also map an INI class to the root node:
239 rw_config => {
241 backend => 'ini_file',
242 store_class_in_hash => 'sections',
243 section_map => {
244 General => '!'
245 },
246 }
247
249 This backend is able to handle simple configuration files where the
250 values are written as key value pairs like:
251 foo = bar
253 or
255 foo: bar
257 The option "assign_char" is used to specify which character is used to
259 assign a value in the file (white spaces are ignored). "assign_char"
260 is ""="" (the default) in the first example, and "":"" in the second.
261 The "assign_with" is used to control how the file is written back. E.g:
263 foo=bar # the default
265 foo= bar # assign_with is "= "
266 foo = bar # assign_with is " = "
267 foo:bar # assign_char is ':', assign_with is the default
268 foo: bar # assign_char is ':', assign_with is ": "
269 foo : bar # assign_char is ':', assign_with is " : "
270
272 read
273 Of all parameters passed to this read call-back, only "file_path" is
274 used. This parameter must be Path::Tiny object.
275 It can also be undef. In this case, "read" returns 0.
277 When a file is read, "read" returns 1.
279 write
281 Of all parameters passed to this write call-back, only "file_path" is
282 used. This parameter must be a Path::Tiny object.
283 "write" returns 1.
285
287 Dominique Dumont, (ddumont at cpan dot org); Krzysztof Tyszecki,
288 (krzysztof.tyszecki at gmail dot com)
289
291 Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,
292
294 Dominique Dumont
295
297 This software is Copyright (c) 2005-2018 by Dominique Dumont.
298 This is free software, licensed under:
300 The GNU Lesser General Public License, Version 2.1, February 1999
302perl v5.28.1 2018-12-07Config::Model::Backend::IniFile(3)