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.140
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
108           is '"#"'.
109
110           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
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
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
137       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
142       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
148       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
153       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
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

Mapping between INI structure and model

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
170   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
175         foo = foo_v
176         [ A ]
177         bar = bar_v
178         [ B ]
179         baz = baz_v
180
181       In this case, class "A" and class "B" do not use the same configuration
182       class.
183
184       The model has this structure:
185
186        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
193   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
197         foo = foo_v
198         [ A ]
199         bar = bar_v1
200         [ B ]
201         bar = bar_v2
202
203       In this case, class "A" and class "B" do not use the same configuration
204       class.  The model has this structure:
205
206        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
214       In this case, the "my_class_holder" name is specified in "rw_config"
215       with "store_class_in_hash" parameter:
216
217           rw_config  => {
218             backend => 'IniFile',
219             config_dir => '/tmp',
220             file  => 'foo.ini',
221             store_class_in_hash => 'my_class_holder',
222           }
223
224       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
228           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
238       "section_map" can also map an INI class to the root node:
239
240           rw_config => {
241             backend => 'ini_file',
242             store_class_in_hash => 'sections',
243             section_map => {
244                 General => '!'
245             },
246           }
247

Handle key value files

249       This backend is able to handle simple configuration files where the
250       values are written as key value pairs like:
251
252        foo = bar
253
254       or
255
256        foo: bar
257
258       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
262       The "assign_with" is used to control how the file is written back. E.g:
263
264        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

Methods

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
276       It can also be undef. In this case, "read" returns 0.
277
278       When a file is read, "read" returns 1.
279
280   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
284       "write" returns 1.
285

AUTHOR

287       Dominique Dumont, (ddumont at cpan dot org); Krzysztof Tyszecki,
288       (krzysztof.tyszecki at gmail dot com)
289

SEE ALSO

291       Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,
292

AUTHOR

294       Dominique Dumont
295
297       This software is Copyright (c) 2005-2020 by Dominique Dumont.
298
299       This is free software, licensed under:
300
301         The GNU Lesser General Public License, Version 2.1, February 1999
302
303
304
305perl v5.32.0                      2020-08-02Config::Model::Backend::IniFile(3)
Impressum