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

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 READING CONFIG

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
70       All of the reader methods return an unblessed reference to a hash.
71
72       All throw an exception when they encounter an error.
73
74   read_file
75         my $hash_ref = Config::INI::Reader->read_file($filename);
76
77       Given a filename, this method returns a hashref of the contents of that
78       file.
79
80   read_string
81         my $hash_ref = Config::INI::Reader->read_string($string);
82
83       Given a string, this method returns a hashref of the contents of that
84       string.
85
86   read_handle
87         my $hash_ref = Config::INI::Reader->read_handle($io_handle);
88
89       Given an IO::Handle, this method returns a hashref of the contents of
90       that handle.
91

METHODS FOR SUBCLASSING

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
96   current_section
97         my $section_name = $reader->current_section;
98
99       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
103   parse_section_header
104         my $name = $reader->parse_section_header($line, $handle);
105
106       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
111   change_section
112         $reader->change_section($section_name);
113
114       This method is called whenever a section change occurs in the file.
115
116       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
119   parse_value_assignment
120         my ($name, $value) = $reader->parse_value_assignment($line, $handle);
121
122       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
127   set_value
128         $reader->set_value($name, $value);
129
130       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
134   starting_section
135         my $section = Config::INI::Reader->starting_section;
136
137       This method returns the name of the starting section.  The default is:
138       "_"
139
140   can_ignore
141         do_nothing if $reader->can_ignore($line, $handle)
142
143       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
147       This is run after preprocess_line.
148
149   preprocess_line
150         $reader->preprocess_line(\$line);
151
152       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
156   handle_unparsed_line
157         $reader->handle_unparsed_line( $line, $handle );
158
159       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
162   finalize
163         $reader->finalize;
164
165       This method is called when the reader has finished reading in every
166       line of the file.
167
168   new
169         my $reader = Config::INI::Reader->new;
170
171       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

ORIGIN

176       Originaly derived from Config::Tiny, by Adam Kennedy.
177

AUTHOR

179       Ricardo Signes <rjbs@semiotic.systems>
180
182       This software is copyright (c) 2007 by Ricardo Signes.
183
184       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.
186
187
188
189perl v5.34.0                      2022-01-21            Config::INI::Reader(3)
Impressum