1Config::INI::Reader(3)User Contributed Perl DocumentationConfig::INI::Reader(3)
2
3
4

NAME

6       Config::INI::Reader - a subclassable .ini-file parser
7

VERSION

9       version 0.014
10

SYNOPSIS

12       If family.ini contains:
13
14         admin = rjbs
15
16         [rjbs]
17         awesome = yes
18         height = 5' 10"
19
20         [mj]
21         awesome = totally
22         height = 23"
23
24       Then when your program contains:
25
26         my $hash = Config::INI::Reader->read_file('family.ini');
27
28       $hash will contain:
29
30         {
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

DESCRIPTION

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
48       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

METHODS FOR READING CONFIG

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
61       All of the reader methods return an unblessed reference to a hash.
62
63       All throw an exception when they encounter an error.
64
65   read_file
66         my $hash_ref = Config::INI::Reader->read_file($filename);
67
68       Given a filename, this method returns a hashref of the contents of that
69       file.
70
71   read_string
72         my $hash_ref = Config::INI::Reader->read_string($string);
73
74       Given a string, this method returns a hashref of the contents of that
75       string.
76
77   read_handle
78         my $hash_ref = Config::INI::Reader->read_handle($io_handle);
79
80       Given an IO::Handle, this method returns a hashref of the contents of
81       that handle.
82

METHODS FOR SUBCLASSING

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
87   current_section
88         my $section_name = $reader->current_section;
89
90       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
94   parse_section_header
95         my $name = $reader->parse_section_header($line);
96
97       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
102   change_section
103         $reader->change_section($section_name);
104
105       This method is called whenever a section change occurs in the file.
106
107       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
110   parse_value_assignment
111         my ($name, $value) = $reader->parse_value_assignment($line);
112
113       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
118   set_value
119         $reader->set_value($name, $value);
120
121       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
125   starting_section
126         my $section = Config::INI::Reader->starting_section;
127
128       This method returns the name of the starting section.  The default is:
129       "_"
130
131   can_ignore
132         do_nothing if $reader->can_ignore($line)
133
134       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
138   preprocess_line
139         $reader->preprocess_line(\$line);
140
141       This method is called to preprocess each line after it's read but
142       before it's parsed.  The default implementation just strips inline
143       comments.  Alterations to the line are made in place.
144
145   finalize
146         $reader->finalize;
147
148       This method is called when the reader has finished reading in every
149       line of the file.
150
151   new
152         my $reader = Config::INI::Reader->new;
153
154       This method returns a new reader.  This generally does not need to be
155       called by anything but the various "read_*" methods, which create a
156       reader object only ephemerally.
157

TODO

159       ·   more tests
160

BUGS

162       Bugs should be reported via the CPAN bug tracker at
163
164       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-INI
165       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-INI>
166
167       For other issues, or commercial enhancement or support, contact the
168       author.
169

AUTHOR

171       Ricardo SIGNES, "E<lt>rjbs@cpan.orgE<gt>"
172
173       Originaly derived from Config::Tiny, by Adam Kennedy.
174

COPYRIGHT

176       Copyright 2007, Ricardo SIGNES.
177
178       This program is free software; you may redistribute it and/or modify it
179       under the same terms as Perl itself.
180
181
182
183perl v5.12.0                      2009-01-16            Config::INI::Reader(3)