1Config::Model::Backend:U:sIenriFCiolnet(r3i)buted Perl DCoocnufmiegn:t:aMtoidoenl::Backend::IniFile(3)
2
3
4

NAME

6       Config::Model::Backend::IniFile - Read and write config as a INI file
7

VERSION

9       version 2.141
10

SYNOPSIS

12        use Config::Model;
13
14        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
25        # model for free INI class name and constrained class parameters
26        $model->create_config_class(
27           name => "MyClass",
28
29           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
40          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
49        my $inst = $model->instance(root_class_name => 'MyClass' );
50        my $root = $inst->config_root ;
51
52        $root->load('ini_class:ONE foo=FOO1 bar=BAR1 -
53                     ini_class:TWO foo=FOO2' );
54
55        $inst->write_back ;
56
57       Now "/tmp/foo.conf" contains:
58
59        ## file written by Config::Model
60        [ONE]
61        foo=FOO1
62
63        bar=BAR1
64
65        [TWO]
66        foo=FOO2
67

DESCRIPTION

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
73       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
77       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

Limitations

82   Structure
83       Structure of the Config::Model must be very simple. Either:
84
85       •   A single class with hash of leaves elements.
86
87       •   2 levels of classes. The top level has nodes elements. All other
88           classes have only leaf elements.
89

Comments in Ini file

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

CONSTRUCTOR

97   new
98       Parameters: "( node => $node_obj, name => 'inifile' )"
99
100       Inherited from Config::Model::Backend::Any. The constructor is called
101       by Config::Model::BackendMgr.
102

Parameters

104       Optional parameters declared in the model:
105
106   comment_delimiter
107       Change the character that starts comments in the INI file. Default is
108       '"#"'.
109
110       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
116   store_class_in_hash
117       See "Arbitrary class name"
118
119   section_map
120       Is a kind of exception of the above rule. See also "Arbitrary class
121       name"
122
123   force_lc_section
124       Boolean. When set, sections names are converted to lowercase.
125
126   force_lc_key
127       Idem for key name
128
129   force_lc_value
130       Idem for all values.
131
132   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
137   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
142   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
148   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
153   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
159   assign_char
160       Character used to assign value in INI file. Default is "=".
161
162   assign_with
163       String used write assignment in INI file. Default is "" = "".
164
165   quote_value
166       How to quote value in INI file. Currrently only "shell_style" is
167       supported for "quote_value".
168
169       E.g. INI backend declaration can contain this parameter:
170
171          quote_value => 'shell_style'
172
173       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
177          # read    => shown   => write
178          "foo"     => foo     => "foo"
179          "foo bar" => foo bar => "foo bar"
180          "20"x"4"  => 20x4    => "20x4"
181

Mapping between INI structure and model

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
187   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
192         foo = foo_v
193         [ A ]
194         bar = bar_v
195         [ B ]
196         baz = baz_v
197
198       In this case, class "A" and class "B" do not use the same configuration
199       class.
200
201       The model has this structure:
202
203        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
210   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
214         foo = foo_v
215         [ A ]
216         bar = bar_v1
217         [ B ]
218         bar = bar_v2
219
220       In this case, class "A" and class "B" do not use the same configuration
221       class.  The model has this structure:
222
223        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
231       In this case, the "my_class_holder" name is specified in "rw_config"
232       with "store_class_in_hash" parameter:
233
234           rw_config  => {
235             backend => 'IniFile',
236             config_dir => '/tmp',
237             file  => 'foo.ini',
238             store_class_in_hash => 'my_class_holder',
239           }
240
241       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
245           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
255       "section_map" can also map an INI class to the root node:
256
257           rw_config => {
258             backend => 'ini_file',
259             store_class_in_hash => 'sections',
260             section_map => {
261                 General => '!'
262             },
263           }
264

Handle key value files

266       This backend is able to handle simple configuration files where the
267       values are written as key value pairs like:
268
269        foo = bar
270
271       or
272
273        foo: bar
274
275       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
279       The "assign_with" is used to control how the file is written back. E.g:
280
281        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

Methods

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
293       It can also be undef. In this case, "read" returns 0.
294
295       When a file is read, "read" returns 1.
296
297   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
301       "write" returns 1.
302

AUTHOR

304       Dominique Dumont, (ddumont at cpan dot org); Krzysztof Tyszecki,
305       (krzysztof.tyszecki at gmail dot com)
306

SEE ALSO

308       Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,
309

AUTHOR

311       Dominique Dumont
312
314       This software is Copyright (c) 2005-2021 by Dominique Dumont.
315
316       This is free software, licensed under:
317
318         The GNU Lesser General Public License, Version 2.1, February 1999
319
320
321
322perl v5.32.1                      2021-01-27Config::Model::Backend::IniFile(3)
Impressum