1Config::INI::Reader(3)User Contributed Perl DocumentationConfig::INI::Reader(3)
2
6 Config::INI::Reader - a subclassable .ini-file parser
7
9 version 0.027
10
12 If family.ini contains:
13 admin = rjbs
15 [rjbs]
17 awesome = yes
18 height = 5' 10"
19 [mj]
21 awesome = totally
22 height = 23"
23 Then when your program contains:
25 my $hash = Config::INI::Reader->read_file('family.ini');
27 $hash will contain:
29 {
31 '_' => { admin => 'rjbs' },
32 rjbs => {
33 awesome => 'yes',
34 height => q{5' 10"},
35 },
36 mj => {
37 awesome => 'totally',
38 height => '23"',
39 },
40 }
41
43 Config::INI::Reader 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::Reader 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 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 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
62 These methods are all that most users will need: they read
63 configuration from a source of input, then they return the data
64 extracted from that input. There are three reader methods,
65 "read_string", "read_file", and "read_handle". The first two are
66 implemented in terms of the third. It iterates over lines in a file,
67 calling methods on the reader when events occur. Those events are
68 detailed below in the "METHODS FOR SUBCLASSING" section.
69 All of the reader methods return an unblessed reference to a hash.
71 All throw an exception when they encounter an error.
73 read_file
75 my $hash_ref = Config::INI::Reader->read_file($filename);
76 Given a filename, this method returns a hashref of the contents of that
78 file.
79 read_string
81 my $hash_ref = Config::INI::Reader->read_string($string);
82 Given a string, this method returns a hashref of the contents of that
84 string.
85 read_handle
87 my $hash_ref = Config::INI::Reader->read_handle($io_handle);
88 Given an IO::Handle, this method returns a hashref of the contents of
90 that handle.
91
93 These are the methods you need to understand and possibly change when
94 subclassing Config::INI::Reader to handle a different format of input.
95 current_section
97 my $section_name = $reader->current_section;
98 This method returns the name of the current section. If no section has
100 yet been set, it returns the result of calling the "starting_section"
101 method.
102 parse_section_header
104 my $name = $reader->parse_section_header($line, $handle);
105 Given a line of input, this method decides whether the line is a
107 section-change declaration. If it is, it returns the name of the
108 section to which to change. If the line is not a section-change, the
109 method returns false.
110 change_section
112 $reader->change_section($section_name);
113 This method is called whenever a section change occurs in the file.
115 The default implementation is to change the current section into which
117 data is being read and to initialize that section to an empty hashref.
118 parse_value_assignment
120 my ($name, $value) = $reader->parse_value_assignment($line, $handle);
121 Given a line of input, this method decides whether the line is a
123 property value assignment. If it is, it returns the name of the
124 property and the value being assigned to it. If the line is not a
125 property assignment, the method returns false.
126 set_value
128 $reader->set_value($name, $value);
129 This method is called whenever an assignment occurs in the file. The
131 default behavior is to change the value of the named property to the
132 given value.
133 starting_section
135 my $section = Config::INI::Reader->starting_section;
136 This method returns the name of the starting section. The default is:
138 "_"
139 can_ignore
141 do_nothing if $reader->can_ignore($line, $handle)
142 This method returns true if the given line of input is safe to ignore.
144 The default implementation ignores lines that contain only whitespace
145 or comments.
146 This is run after preprocess_line.
148 preprocess_line
150 $reader->preprocess_line(\$line);
151 This method is called to preprocess each line after it's read but
153 before it's parsed. The default implementation just strips inline
154 comments. Alterations to the line are made in place.
155 handle_unparsed_line
157 $reader->handle_unparsed_line( $line, $handle );
158 This method is called when the reader encounters a line that doesn't
160 look like anything it recognizes. By default, it throws an exception.
161 finalize
163 $reader->finalize;
164 This method is called when the reader has finished reading in every
166 line of the file.
167 new
169 my $reader = Config::INI::Reader->new;
170 This method returns a new reader. This generally does not need to be
172 called by anything but the various "read_*" methods, which create a
173 reader object only ephemerally.
174
176 Originaly derived from Config::Tiny, by Adam Kennedy.
177
179 Ricardo Signes <rjbs@semiotic.systems>
180
182 This software is copyright (c) 2007 by Ricardo Signes.
183 This is free software; you can redistribute it and/or modify it under
185 the same terms as the Perl 5 programming language system itself.
186perl v5.34.0 2022-01-21 Config::INI::Reader(3)