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.142
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 is
108 '"#"'.
109 Some Ini files allows comments to begin with several characters (e.g.
111 "#" or ";"). In this case, set "comment_delimiter" to the possible
112 characters (e.g ""#;""). The first character is used to write back
113 comments. (In the example above, comment "; blah" is written back as "#
114 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 a
134 comma. This parameter specifies the regex to use to split the value
135 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 be
139 written back with a string to join them. Specify this string (usually '
140 ' 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 space
144 or a comma. This parameter specifies the regex to use to split the
145 value read from the file into a list of items to check. This applies
146 only to "check_list" elements.
147 join_check_list_value
149 Conversely, the check_list element split with "split_list_value" needs
150 to be written back with a string to join them. Specify this string
151 (usually ' ' or ', ') with "join_check_list_value".
152 write_boolean_as
154 Array ref. Reserved for boolean value. Specify how to write a boolean
155 value. Default is "[0,1]" which may not be the most readable.
156 "write_boolean_as" can be specified as "['false','true']" or
157 "['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 quote_value
166 How to quote value in INI file. Currrently only "shell_style" is
167 supported for "quote_value".
168 E.g. INI backend declaration can contain this parameter:
170 quote_value => 'shell_style'
172 Here are some example of quoted values. The 3 columns shows the
174 original value in file, how it's stored internally and how it's written
175 back:
176 # read => shown => write
178 "foo" => foo => "foo"
179 "foo bar" => foo bar => "foo bar"
180 "20"x"4" => 20x4 => "20x4"
181
183 INI file typically have the same structure with 2 different
184 conventions. The class names can be imposed by the application or may
185 be chosen by user.
186 Imposed class name
188 In this case, the class names must match what is expected by the
189 application. The elements of each class can be different. For
190 instance:
191 foo = foo_v
193 [ A ]
194 bar = bar_v
195 [ B ]
196 baz = baz_v
197 In this case, class "A" and class "B" do not use the same configuration
199 class.
200 The model has this structure:
202 Root class
204 |- leaf element foo
205 |- node element A of class_A
206 | \- leaf element bar
207 \- node element B of class_B
208 \- leaf element baz
209 Arbitrary class name
211 In this case, the class names can be chosen by the end user. Each class
212 has the same elements. For instance:
213 foo = foo_v
215 [ A ]
216 bar = bar_v1
217 [ B ]
218 bar = bar_v2
219 In this case, class "A" and class "B" do not use the same configuration
221 class. The model has this structure:
222 Root class
224 |- leaf foo
225 \- hash element my_class_holder
226 |- key A (value is node of class_A)
227 | \- element-bar
228 \- key B (value is node of class_A)
229 \- element-bar
230 In this case, the "my_class_holder" name is specified in "rw_config"
232 with "store_class_in_hash" parameter:
233 rw_config => {
235 backend => 'IniFile',
236 config_dir => '/tmp',
237 file => 'foo.ini',
238 store_class_in_hash => 'my_class_holder',
239 }
240 Of course they are exceptions. For instance, in "Multistrap", the
242 "[General]" INI class must be mapped to a specific node object. This
243 can be specified with the "section_map" parameter:
244 rw_config => }
246 backend => 'IniFile',
247 config_dir => '/tmp',
248 file => 'foo.ini',
249 store_class_in_hash => 'my_class_holder',
250 section_map => {
251 General => 'general_node',
252 }
253 }
254 "section_map" can also map an INI class to the root node:
256 rw_config => {
258 backend => 'ini_file',
259 store_class_in_hash => 'sections',
260 section_map => {
261 General => '!'
262 },
263 }
264
266 This backend is able to handle simple configuration files where the
267 values are written as key value pairs like:
268 foo = bar
270 or
272 foo: bar
274 The option "assign_char" is used to specify which character is used to
276 assign a value in the file (white spaces are ignored). "assign_char"
277 is ""="" (the default) in the first example, and "":"" in the second.
278 The "assign_with" is used to control how the file is written back. E.g:
280 foo=bar # the default
282 foo= bar # assign_with is "= "
283 foo = bar # assign_with is " = "
284 foo:bar # assign_char is ':', assign_with is the default
285 foo: bar # assign_char is ':', assign_with is ": "
286 foo : bar # assign_char is ':', assign_with is " : "
287
289 read
290 Of all parameters passed to this read call-back, only "file_path" is
291 used. This parameter must be Path::Tiny object.
292 It can also be undef. In this case, "read" returns 0.
294 When a file is read, "read" returns 1.
296 write
298 Of all parameters passed to this write call-back, only "file_path" is
299 used. This parameter must be a Path::Tiny object.
300 "write" returns 1.
302
304 Dominique Dumont, (ddumont at cpan dot org); Krzysztof Tyszecki,
305 (krzysztof.tyszecki at gmail dot com)
306
308 Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,
309
311 Dominique Dumont
312
314 This software is Copyright (c) 2005-2021 by Dominique Dumont.
315 This is free software, licensed under:
317 The GNU Lesser General Public License, Version 2.1, February 1999
319perl v5.34.0 2021-07-22Config::Model::Backend::IniFile(3)