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.025
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 These methods are all that most users will need: they read
54 configuration from a source of input, then they return the data
55 extracted from that input. There are three reader methods,
56 "read_string", "read_file", and "read_handle". The first two are
57 implemented in terms of the third. It iterates over lines in a file,
58 calling methods on the reader when events occur. Those events are
59 detailed below in the "METHODS FOR SUBCLASSING" section.
60 All of the reader methods return an unblessed reference to a hash.
62 All throw an exception when they encounter an error.
64 read_file
66 my $hash_ref = Config::INI::Reader->read_file($filename);
67 Given a filename, this method returns a hashref of the contents of that
69 file.
70 read_string
72 my $hash_ref = Config::INI::Reader->read_string($string);
73 Given a string, this method returns a hashref of the contents of that
75 string.
76 read_handle
78 my $hash_ref = Config::INI::Reader->read_handle($io_handle);
79 Given an IO::Handle, this method returns a hashref of the contents of
81 that handle.
82
84 These are the methods you need to understand and possibly change when
85 subclassing Config::INI::Reader to handle a different format of input.
86 current_section
88 my $section_name = $reader->current_section;
89 This method returns the name of the current section. If no section has
91 yet been set, it returns the result of calling the "starting_section"
92 method.
93 parse_section_header
95 my $name = $reader->parse_section_header($line, $handle);
96 Given a line of input, this method decides whether the line is a
98 section-change declaration. If it is, it returns the name of the
99 section to which to change. If the line is not a section-change, the
100 method returns false.
101 change_section
103 $reader->change_section($section_name);
104 This method is called whenever a section change occurs in the file.
106 The default implementation is to change the current section into which
108 data is being read and to initialize that section to an empty hashref.
109 parse_value_assignment
111 my ($name, $value) = $reader->parse_value_assignment($line, $handle);
112 Given a line of input, this method decides whether the line is a
114 property value assignment. If it is, it returns the name of the
115 property and the value being assigned to it. If the line is not a
116 property assignment, the method returns false.
117 set_value
119 $reader->set_value($name, $value);
120 This method is called whenever an assignment occurs in the file. The
122 default behavior is to change the value of the named property to the
123 given value.
124 starting_section
126 my $section = Config::INI::Reader->starting_section;
127 This method returns the name of the starting section. The default is:
129 "_"
130 can_ignore
132 do_nothing if $reader->can_ignore($line, $handle)
133 This method returns true if the given line of input is safe to ignore.
135 The default implementation ignores lines that contain only whitespace
136 or comments.
137 This is run after preprocess_line.
139 preprocess_line
141 $reader->preprocess_line(\$line);
142 This method is called to preprocess each line after it's read but
144 before it's parsed. The default implementation just strips inline
145 comments. Alterations to the line are made in place.
146 handle_unparsed_line
148 $reader->handle_unparsed_line( $line, $handle );
149 This method is called when the reader encounters a line that doesn't
151 look like anything it recognizes. By default, it throws an exception.
152 finalize
154 $reader->finalize;
155 This method is called when the reader has finished reading in every
157 line of the file.
158 new
160 my $reader = Config::INI::Reader->new;
161 This method returns a new reader. This generally does not need to be
163 called by anything but the various "read_*" methods, which create a
164 reader object only ephemerally.
165
167 Originaly derived from Config::Tiny, by Adam Kennedy.
168
170 Ricardo Signes <rjbs@cpan.org>
171
173 This software is copyright (c) 2007 by Ricardo Signes.
174 This is free software; you can redistribute it and/or modify it under
176 the same terms as the Perl 5 programming language system itself.
177perl v5.32.1 2021-01-27 Config::INI::Reader(3)