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.027
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

PERL VERSION SUPPORT

53       This module has a long-term perl support period.  That means it will
54       not require a version of perl released fewer than five years ago.
55
56       Although it may work on older versions of perl, no guarantee is made
57       that the minimum required version will not be increased.  The version
58       may be increased for any reason, and there is no promise that patches
59       will be accepted to lower the minimum required perl.
60

METHODS FOR WRITING CONFIG

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

METHODS FOR SUBCLASSING

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

AUTHOR

266       Ricardo Signes <rjbs@semiotic.systems>
267

269       This software is copyright (c) 2007 by Ricardo Signes.
270
271       This is free software; you can redistribute it and/or modify it under
272       the same terms as the Perl 5 programming language system itself.
273
274
275
276perl v5.36.0                      2022-07-22            Config::INI::Writer(3)
Impressum