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.014
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 my $hash = 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_input
139 $writer->validate_input($input);
140 This method is called on the input data once they've been preprocessed
142 by "preprocess_input".
143 It ensures that the processed input is structurally sound before
145 beginning to output it. For example, it ensures that no property is
146 ever assigned more than once in a given section.
147 This method either raises an exception or it doesn't.
149 change_section
151 $writer->change_section($section_name);
152 This method is called each time a new section is going to be written
154 out. If the same section appears twice in a row in the input, this
155 method will still be called between instances of that section.
156 In other words, given this input:
158 [
160 section_1 => [ a => 1 ],
161 section_1 => [ b => 2 ],
162 ]
163 "change_section" will be called twice: once before the first
165 "section_1" and once before the second "section_1".
166 current_section
168 $writer->current_section
169 This method returns the section currently being written out.
171 finish_section
173 $writer->finish_section
174 This method is called after all of the current section's properties
176 have been written.
177 done_sections
179 my @names = $writer->done_sections;
180 This method returns a list of all sections that have been written out
182 and finished. The fact that a section name is returned by
183 "done_sections" does not mean that there will be no more data for that
184 section, but that at least one entire set of data has been written out
185 for it.
186 stringify_section
188 my $string = $writer->stringify_section($props);
189 This method returns a string assigning all the properties set in the
191 given data. This still will include the section header, if needed.
192 (The only case in which it is not needed is when the
193 "explicit_starting_header" method returns false, no other sections have
194 been done, and the section about to be stringified is the
195 "starting_section".
196 This method is implemented in terms of "stringify_section_header" and
198 "stringify_section_data".
199 stringify_section_data
201 my $string = $writer->stringify_section_data($props)
202 This method returns a string containing a series of lines, each
204 containing a value assignment for the given properties.
205 stringify_value_assignment
207 my $string = $writer->stringify_value_assignment($name => $value);
208 This method returns a string that assigns a value to a named property.
210 If the value is undefined, an empty string is returned.
211 stringify_value
213 my $string = $writer->stringify_value($value);
214 This method returns the string that will represent the given value in a
216 property assignment.
217 stringify_section_header
219 my $string = $writer->stringify_section_header($section_name);
220 This method returns the string (a line) that represents the given
222 section name. Basically, this returns:
223 [section_name]
225 starting_section
227 This method returns the name of the starting section. If this section
228 appears first (as it will, when given a hashref as input) and if
229 "explicit_starting_header" returns false, its section header can be
230 omitted.
231 explicit_starting_header
233 If this method returns true (which it does not, by default), then the
234 section header for the starting section will be emitted, even if it
235 appears first.
236 new
238 my $reader = Config::INI::Writer->new;
239 This method returns a new writer. This generally does not need to be
241 called by anything but the various "write_*" methods, which create a
242 writer object only ephemerally.
243
245 ยท more tests
246
248 Bugs should be reported via the CPAN bug tracker at
249 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-INI
251 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-INI>
252 For other issues, or commercial enhancement or support, contact the
254 author.
255
257 Ricardo SIGNES, "E<lt>rjbs@cpan.orgE<gt>"
258 Originaly derived from Config::Tiny, by Adam Kennedy. The first pass
260 at refactoring this code into Config::INI::Writer was performed by
261 Florian Ragwitz.
262
264 Copyright 2007, Ricardo SIGNES.
265 This program is free software; you may redistribute it and/or modify it
267 under the same terms as Perl itself.
268perl v5.12.0 2009-01-16 Config::INI::Writer(3)