aboutsummaryrefslogtreecommitdiff
path: root/lib/Config/Parser
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2019-08-20 16:02:08 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2019-08-20 16:02:08 +0300
commitb3d1cf2fb648f77a6ea432486ba2a8f026068f11 (patch)
tree97e6450c863b478ec62bb25134e86e6434705e1a /lib/Config/Parser
parente9f110af920cf4e6642bc3301340b23a7a2a6589 (diff)
downloadconfig-parser-b3d1cf2fb648f77a6ea432486ba2a8f026068f11.tar.gz
config-parser-b3d1cf2fb648f77a6ea432486ba2a8f026068f11.tar.bz2
Provide a way for supplying options to section definition. Improve the docs
* lib/Config/Parser.pm (loadsynt): Return a reference to the reference hash. Process eventual __options__ keywords in sections. Finish documentation. * lib/Config/Parser/Ini.pm: Add documentation * t/ConfigSpec2.pm: Use the __options__ keyword.
Diffstat (limited to 'lib/Config/Parser')
-rw-r--r--lib/Config/Parser/Ini.pm174
1 files changed, 174 insertions, 0 deletions
diff --git a/lib/Config/Parser/Ini.pm b/lib/Config/Parser/Ini.pm
index 0ea632c..79d231e 100644
--- a/lib/Config/Parser/Ini.pm
+++ b/lib/Config/Parser/Ini.pm
@@ -94,3 +94,177 @@ sub _readconfig {
94 94
951; 951;
96 96
97=head1 NAME
98
99Config::Parser::Ini - configuration file parser for ini-style files
100
101=head1 SYNOPSIS
102
103$cfg = new Config::Parser::Ini($filename);
104
105$val = $cfg->get('dir', 'tmp');
106
107print $val->value;
108print $val->locus;
109
110$val = $cfg->tree->Dir->Tmp;
111
112=head1 DESCRIPTION
113
114An I<ini-style configuration file> is a textual file consisting of settings
115grouped into one or more sections. A I<setting> has the form
116
117 KEYWORD = VALUE
118
119where I<KEYWORD> is the setting name and I<VALUE> is its value.
120Syntactically, I<VALUE> is anything to the right of the equals sign and up
121to the linefeed character terminating the line (ASCII 10), not including
122the leading and trailing whitespace characters.
123
124Each setting occupies one line. Very long lines can be split over several
125physical lines by ending each line fragment except the last with a backslash
126character appearing right before the linefeed character.
127
128A I<section> begins with a section declaration in the following form:
129
130 [NAME NAME...]
131
132Here, square brackets form part of the syntax. Any number of I<NAME>s
133can be present inside the square brackets. The first I<NAME> must follow the
134usual rules for a valid identifier name. Rest of I<NAME>s can contain any
135characters, provided that any I<NAME> that includes non-alphanumeric characters
136is enclosed in a pair of double-quotes. Any double-quotes and backslash
137characters appearing within the quoted string must be escaped by prefixing
138them with a single backslash.
139
140The B<Config::Parser::Ini> module is a framework for parsing such files.
141
142In the simplest case, the usage of this module is as simple as in the following
143fragment:
144
145 use Config::Parser::Ini;
146 my $cf = new Config::Parser::Ini(filename => "config.ini");
147
148On success, this returns a valid B<Config::Parser::Ini> object. On error,
149the diagnostic message is issued using the B<error> method (see the description
150of the method in B<Config::AST>(3)) and the module croaks.
151
152This usage, although simple, has one major drawback - no checking is performed
153on the input file, except for the syntax check. To fix this, you can supply
154a dictionary (or I<lexicon>) of allowed keywords along with their values.
155Such a dictionary is itself a valid ini file, where the value of each
156keyword describes its properties. The dictionary is placed in the B<__DATA__>
157section of the source file which invokes the B<Config::Parser::Ini> constructor.
158
159Expanding the example above:
160
161 use Config::Parser::Ini;
162 my $cf = new Config::Parser::Ini(filename => "config.ini");
163
164 __DATA__
165 [core]
166 root = STRING :default /
167 umask = OCTAL
168 [user]
169 uid = NUMBER
170 gid = NUMBER
171
172This code specifies that the configuration file can contain at most two
173sections: C<[core]> and C<[user]>. Two keywords are defined within each
174section. Data types are specified for each keyword, so the parser will
175bail out in case of type mismatches. If the B<core.root> setting is not
176present in the configuration, the default one will be created with the
177value C</>.
178
179It is often advisable to create a subclass of B<Config::Parser::Ini> and
180use it for parsing. For instance:
181
182 package App::MyConf;
183 use Config::Parser::Ini;
184 1;
185 __DATA__
186 [core]
187 root = STRING :default /
188 umask = OCTAL
189 [user]
190 uid = NUMBER
191 gid = NUMBER
192
193Then, to parse the configuration file, it will suffice to do:
194
195 $cf = my App::MyConf(filename => "config.ini");
196
197One advantage of this approach is that it will allow you to install
198additional validation for the configuration statements using the
199B<:check> option. The argument to this option is the name of a
200method which will be invoked after parsing the statement in order
201to verify its value. It is described in detail below (see the section
202B<SYNTAX DEFINITION> in the documentation of B<Config::Parser>).
203For example, if you wish to ensure that the value of the C<root> setting
204in C<core> section points to an existing directory, you would do:
205
206 package App::MyConf;
207 use Config::Parser::Ini;
208
209 sub dir_exists {
210 my ($self, $valref, $prev_value, $locus) = @_;
211
212 unless (-d $$valref) {
213 $self->error("$$valref: directory does not exist",
214 locus => $locus);
215 return 0;
216 }
217 return 1;
218 }
219 1;
220 __DATA__
221 [core]
222 root = STRING :default / :check=dir_exists
223 umask = OCTAL
224 [user]
225 uid = NUMBER
226 gid = NUMBER
227
228=head1 CONSTRUCTOR
229
230 $cfg = new Config::Parser::Ini(%opts)
231
232Creates a new parser object. Keyword arguments are:
233
234=over 4
235
236=item B<filename>
237
238Name of the file to parse. If not supplied, you will have to
239call the B<$cfg-E<gt>parse> method explicitly after you are returned a
240valid B<$cfg>.
241
242=item B<line>
243
244Optional line where the configuration starts in B<filename>. It is used to
245keep track of statement location in the file for correct diagnostics. If
246not supplied, B<1> is assumed.
247
248=item B<fh>
249
250File handle to read from. If it is not supplied, new handle will be
251created by using B<open> on the supplied filename.
252
253=item B<lexicon>
254
255Dictionary of allowed configuration statements in the file. You will not
256need this parameter. It is listed here for completeness sake. Refer to
257the B<Config::AST> constructor for details.
258
259=back
260
261=head1 METHODS
262
263All methods are inferited from B<Config::Parser>. Please see its
264documentation for details.
265
266=head1 SEE ALSO
267
268B<Config::Parser>(3), B<Config::AST>(3).
269
270=cut

Return to:

Send suggestions and report system problems to the System administrator.