1Config::INI::Writer(3)User Contributed Perl DocumentationConfig::INI::Writer(3)
2
6 Config::INI::Writer - a subclassable .ini-file emitter
7
9 version 0.025
10
12 If <$hash> contains:
13 {
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 Then when your program contains:
27 Config::INI::Writer->write_file($hash, 'family.ini');
29 family.ini will contains:
31 admin = rjbs
33 [rjbs]
35 awesome = yes
36 height = 5' 10"
37 [mj]
39 awesome = totally
40 height = 23"
41
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 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
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 The given data should be a hashref of hashrefs:
61 {
63 section_name_1 => { prop1 => 'value1', prop2 => 'value2' },
64 section_name_2 => ...
65 }
66 ...or an arrayref of section name and arrayref pairs:
68 [
70 section_name_1 => [ prop1 => 'value1', prop2 => 'value2' ],
71 section_name_2 => ...
72 ]
73 ...or a combination of those:
75 [
77 section_name_1 => { prop1 => 'value1', prop2 => 'value2' },
78 section_name_2 => [ prop3 => 'value3', prop4 => 'value4' ],
79 section_name_3 => ...
80 ]
81 All the reader methods throw an exception when they encounter an error.
83 write_file
85 Config::INI::Writer->write_file($input, $filename);
86 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 This method will either succeed or raise an exception. (Its return
92 value is not defined.)
93 write_string
95 my $string = Config::INI::Writer->write_string($input);
96 This method returns a string containing the INI content describing the
98 given data.
99 write_handle
101 Config::INI::Writer->write_handle($input, $handle);
102 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
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 preprocess_input
111 my $processed_input = $writer->preprocess_input($input_data);
112 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 In other words, given:
120 {
122 section_1 => { a => 1, b => 2 },
123 section_2 => { c => 3, c => 4 },
124 _ => { d => 5, e => 6 },
125 }
126 This method will return:
128 [
130 _ => [ d => 5, e => 6 ],
131 section_2 => [ c => 3, c => 4 ],
132 section_1 => [ a => 1, b => 2 ],
133 ]
134 The only guaranteed ordering when hashes are provided as input is that
136 the starting section will appear first.
137 validate_section_name
139 Carp::croak "section name contains illegal character"
140 if not $writer->is_valid_section_name($name);
141 is_valid_property_name
143 Carp::croak "property name contains illegal character"
144 if not $writer->is_valid_property_name($name);
145 is_valid_value
147 Carp::croak "value contains illegal character"
148 if not $writer->is_valid_value($name);
149 validate_input
151 $writer->validate_input($input);
152 This method is called on the input data once they've been preprocessed
154 by "preprocess_input".
155 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 This method either raises an exception or it doesn't.
161 change_section
163 $writer->change_section($section_name);
164 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 In other words, given this input:
170 [
172 section_1 => [ a => 1 ],
173 section_1 => [ b => 2 ],
174 ]
175 "change_section" will be called twice: once before the first
177 "section_1" and once before the second "section_1".
178 current_section
180 $writer->current_section
181 This method returns the section currently being written out.
183 finish_section
185 $writer->finish_section
186 This method is called after all of the current section's properties
188 have been written.
189 done_sections
191 my @names = $writer->done_sections;
192 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 stringify_section
200 my $string = $writer->stringify_section($props);
201 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 This method is implemented in terms of "stringify_section_header" and
210 "stringify_section_data".
211 stringify_section_data
213 my $string = $writer->stringify_section_data($props)
214 This method returns a string containing a series of lines, each
216 containing a value assignment for the given properties.
217 stringify_value_assignment
219 my $string = $writer->stringify_value_assignment($name => $value);
220 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 stringify_value
225 my $string = $writer->stringify_value($value);
226 This method returns the string that will represent the given value in a
228 property assignment.
229 stringify_section_header
231 my $string = $writer->stringify_section_header($section_name);
232 This method returns the string (a line) that represents the given
234 section name. Basically, this returns:
235 [section_name]
237 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 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 new
250 my $reader = Config::INI::Writer->new;
251 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
257 Ricardo Signes <rjbs@cpan.org>
258
260 This software is copyright (c) 2007 by Ricardo Signes.
261 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.
264perl v5.30.0 2019-07-26 Config::INI::Writer(3)