1Config::INI::Writer(3)User Contributed Perl DocumentationConfig::INI::Writer(3)
2
3
4

NAME

6       Config::INI::Writer - a subclassable .ini-file emitter
7

VERSION

9       version 0.025
10

SYNOPSIS

12       If <$hash> contains:
13
14         {
15           '_'  => { admin => 'rjbs' },
16           rjbs => {
17             awesome => 'yes',
18             height  => q{5' 10"},
19           },
20           mj   => {
21             awesome => 'totally',
22             height  => '23"',
23           },
24         }
25
26       Then when your program contains:
27
28         Config::INI::Writer->write_file($hash, 'family.ini');
29
30       family.ini will contains:
31
32         admin = rjbs
33
34         [rjbs]
35         awesome = yes
36         height = 5' 10"
37
38         [mj]
39         awesome = totally
40         height = 23"
41

DESCRIPTION

43       Config::INI::Writer is yet another config module implementing yet
44       another slightly different take on the undeniably easy to read ".ini"
45       file format.  Its default behavior is quite similar to that of
46       Config::Tiny, on which it is based.
47
48       The chief difference is that Config::INI::Writer is designed to be
49       subclassed to allow for side-effects and self-reconfiguration to occur
50       during the course of reading its input.
51

METHODS FOR WRITING CONFIG

53       There are three writer methods, "write_string", "write_file", and
54       "write_handle".  The first two are implemented in terms of the third.
55       It iterates over a collection of data, emitting lines to the filehandle
56       as it goes.  The lines are generated by events produced by iterating
57       over the data.  Those events are detailed below in the "METHODS FOR
58       SUBCLASSING" section.
59
60       The given data should be a hashref of hashrefs:
61
62         {
63           section_name_1 => { prop1 => 'value1', prop2 => 'value2' },
64           section_name_2 => ...
65         }
66
67       ...or an arrayref of section name and arrayref pairs:
68
69         [
70           section_name_1 => [ prop1 => 'value1', prop2 => 'value2' ],
71           section_name_2 => ...
72         ]
73
74       ...or a combination of those:
75
76         [
77           section_name_1 => { prop1 => 'value1', prop2 => 'value2' },
78           section_name_2 => [ prop3 => 'value3', prop4 => 'value4' ],
79           section_name_3 => ...
80         ]
81
82       All the reader methods throw an exception when they encounter an error.
83
84   write_file
85         Config::INI::Writer->write_file($input, $filename);
86
87       This method writes out the configuration represented by $data to the
88       file named by $filename.  If a file by that name exists, it is
89       overwritten.
90
91       This method will either succeed or raise an exception.  (Its return
92       value is not defined.)
93
94   write_string
95         my $string = Config::INI::Writer->write_string($input);
96
97       This method returns a string containing the INI content describing the
98       given data.
99
100   write_handle
101         Config::INI::Writer->write_handle($input, $handle);
102
103       This method writes the data in $data to the IO::Handle-like object in
104       $handle.  This method should either succeed or throw an exception.
105

METHODS FOR SUBCLASSING

107       These are the methods you need to understand and possibly change when
108       subclassing Config::INI::Reader to handle a different format of input.
109
110   preprocess_input
111         my $processed_input = $writer->preprocess_input($input_data);
112
113       This method is called to ensure that the data given to the "write_*"
114       methods are in a canonical form for processing and emitting.  The
115       default implementation converts hashrefs to arrayrefs and, if the input
116       is a hashref, moves the "starting_section" to the beginning of the
117       produced arrayref.
118
119       In other words, given:
120
121         {
122           section_1 => { a => 1, b => 2 },
123           section_2 => { c => 3, c => 4 },
124           _         => { d => 5, e => 6 },
125         }
126
127       This method will return:
128
129         [
130           _         => [ d => 5, e => 6 ],
131           section_2 => [ c => 3, c => 4 ],
132           section_1 => [ a => 1, b => 2 ],
133         ]
134
135       The only guaranteed ordering when hashes are provided as input is that
136       the starting section will appear first.
137
138   validate_section_name
139         Carp::croak "section name contains illegal character"
140           if not $writer->is_valid_section_name($name);
141
142   is_valid_property_name
143         Carp::croak "property name contains illegal character"
144           if not $writer->is_valid_property_name($name);
145
146   is_valid_value
147         Carp::croak "value contains illegal character"
148           if not $writer->is_valid_value($name);
149
150   validate_input
151         $writer->validate_input($input);
152
153       This method is called on the input data once they've been preprocessed
154       by "preprocess_input".
155
156       It ensures that the processed input is structurally sound before
157       beginning to output it.  For example, it ensures that no property is
158       ever assigned more than once in a given section.
159
160       This method either raises an exception or it doesn't.
161
162   change_section
163         $writer->change_section($section_name);
164
165       This method is called each time a new section is going to be written
166       out.  If the same section appears twice in a row in the input, this
167       method will still be called between instances of that section.
168
169       In other words, given this input:
170
171         [
172           section_1 => [ a => 1 ],
173           section_1 => [ b => 2 ],
174         ]
175
176       "change_section" will be called twice: once before the first
177       "section_1" and once before the second "section_1".
178
179   current_section
180         $writer->current_section
181
182       This method returns the section currently being written out.
183
184   finish_section
185         $writer->finish_section
186
187       This method is called after all of the current section's properties
188       have been written.
189
190   done_sections
191         my @names = $writer->done_sections;
192
193       This method returns a list of all sections that have been written out
194       and finished.  The fact that a section name is returned by
195       "done_sections" does not mean that there will be no more data for that
196       section, but that at least one entire set of data has been written out
197       for it.
198
199   stringify_section
200         my $string = $writer->stringify_section($props);
201
202       This method returns a string assigning all the properties set in the
203       given data.  This still will include the section header, if needed.
204       (The only case in which it is not needed is when the
205       "explicit_starting_header" method returns false, no other sections have
206       been done, and the section about to be stringified is the
207       "starting_section".
208
209       This method is implemented in terms of "stringify_section_header" and
210       "stringify_section_data".
211
212   stringify_section_data
213         my $string = $writer->stringify_section_data($props)
214
215       This method returns a string containing a series of lines, each
216       containing a value assignment for the given properties.
217
218   stringify_value_assignment
219         my $string = $writer->stringify_value_assignment($name => $value);
220
221       This method returns a string that assigns a value to a named property.
222       If the value is undefined, an empty string is returned.
223
224   stringify_value
225         my $string = $writer->stringify_value($value);
226
227       This method returns the string that will represent the given value in a
228       property assignment.
229
230   stringify_section_header
231         my $string = $writer->stringify_section_header($section_name);
232
233       This method returns the string (a line) that represents the given
234       section name.  Basically, this returns:
235
236         [section_name]
237
238   starting_section
239       This method returns the name of the starting section.  If this section
240       appears first (as it will, when given a hashref as input) and if
241       "explicit_starting_header" returns false, its section header can be
242       omitted.
243
244   explicit_starting_header
245       If this method returns true (which it does not, by default), then the
246       section header for the starting section will be emitted, even if it
247       appears first.
248
249   new
250         my $reader = Config::INI::Writer->new;
251
252       This method returns a new writer.  This generally does not need to be
253       called by anything but the various "write_*" methods, which create a
254       writer object only ephemerally.
255

AUTHOR

257       Ricardo Signes <rjbs@cpan.org>
258
260       This software is copyright (c) 2007 by Ricardo Signes.
261
262       This is free software; you can redistribute it and/or modify it under
263       the same terms as the Perl 5 programming language system itself.
264
265
266
267perl v5.32.1                      2021-01-27            Config::INI::Writer(3)
Impressum