aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2019-08-20 07:26:06 +0300
committerSergey Poznyakoff <gray@gnu.org>2019-08-20 07:26:06 +0300
commite9f110af920cf4e6642bc3301340b23a7a2a6589 (patch)
tree11b2b32588923b952f03177e9d9bfeaa087dcad8
parent18455d3afab3365d522fb6fa85ca8e03d0a388e6 (diff)
downloadconfig-parser-e9f110af920cf4e6642bc3301340b23a7a2a6589.tar.gz
config-parser-e9f110af920cf4e6642bc3301340b23a7a2a6589.tar.bz2
Start writing the documentation
-rw-r--r--Makefile.PL4
-rw-r--r--lib/Config/Parser.pm153
2 files changed, 155 insertions, 2 deletions
diff --git a/Makefile.PL b/Makefile.PL
index cee8413..b832c66 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -24,8 +24,8 @@ WriteMakefile(NAME => 'Config::Parser',
24 resources => { 24 resources => {
25 repository => { 25 repository => {
26 type => 'git', 26 type => 'git',
27 url => 'git://git.gnu.org.ua/config-td.git', 27 url => 'git://git.gnu.org.ua/config-parser.git',
28 web => 'http://git.gnu.org.ua/cgit/config-td.git/', 28 web => 'http://git.gnu.org.ua/cgit/config-parser.git/',
29 }, 29 },
30 }, 30 },
31 provides => Module::Metadata->provides(version => '1.4', 31 provides => Module::Metadata->provides(version => '1.4',
diff --git a/lib/Config/Parser.pm b/lib/Config/Parser.pm
index 0f0a1f0..7d20aa2 100644
--- a/lib/Config/Parser.pm
+++ b/lib/Config/Parser.pm
@@ -132,4 +132,157 @@ sub loadsynt {
132 132
1331; 1331;
134 134
135=head1 NAME
136
137Config::Parser - base class for configuration file parsers
138
139=head1 DESCRIPTION
140
141B<Config::Parser> provides a framework for writing configuration file
142parsers. It is an intermediate layer between the abstract syntax tree
143(B<Config::AST>) and implementation of a parser for a particular
144configuration file format.
145
146It takes a I<define by example> approach. That means that the implementor
147creates a derived class that implements a parser on top of B<Config::Parser>.
148Application writers write an example of configuration file in the B<__DATA__>
149section of their application, which defines the statements that are allowed
150in a valid configuration. This example is then processed by the parser
151implementation to create an instance of the parser, which is then used to
152process the actual configuration file.
153
154Let's illustrate this on a practical example. Suppose you need a parser for
155a simple configuration file, which consists of keyword/value pairs. In each
156pair, the keyword is separated from the value by an equals sign. Pairs are
157delimited by newlines. Leading and trailing whitespace characters on a line
158are ignored as well as are empty lines. Comments begin with a hash sign and
159end with a newline.
160
161You create the class B<Config::Parser::KV> based on B<Config::Parser>. The
162method B<parser> in this class implements the actual parser.
163
164Application writer decides what keywords are allowed in a valid configuration
165file and what are their values and puts them forth in the B<__DATA__> section
166of his program (normally in a class derived from B<Config::Parser::KV>, in
167the same format as the actual configuration file. For example:
168
169 __DATA__
170 basedir = STRING :mandatory
171 mode = OCTAL
172 size = NUMBER :array
173
174This excerpt defines a configuration with three allowed statements. Uppercase
175values to the right of the equals sign are data types. Values starting with
176a colon are flags that define the semantics of the values. This section
177declares that three keywords are allowed. The B<basedir> keyword takes
178string as its argument and must be present in a valid configuration. The
179B<mode> expects octal number as its argument. The B<size> keyword takes
180a number. Multiple B<size> statements are collapsed into an array.
181
182To parse the actual configuration file, the programmer creates an instance
183of the B<Config::Parse::KV> class, passing it the name of the file as its
184argument:
185
186 $cf = new Config::Parse::KV($filename);
187
188This call first parses the B<__DATA__> section and builds validation rules,
189then it parses the actual configuration from B<$filename>. Finally, it
190applies the validation rules to the created syntax tree. If all rules pass,
191the configuration is correct and the constructor returns a valid object.
192Otherwise, it issues proper diagnostics and returns B<undef>.
193
194Upon successful return, the B<$cf> object is used to obtain the actual
195configuration values as needed.
196
197Notice that syntax declarations in the B<__DATA__> section always follow the
198actual configuration file format, that's why we call them I<definition by
199example>. For instance, the syntax definition for a configuration file in
200Apache-like format would look like
201
202 __DATA__
203 <section ANY>
204 basedir STRING :mandatory
205 mode OCTAL
206 size NUMBER :array
207 </section>
208
209=head1 CONSTRUCTOR
210
211=head2 $cfg = new Config::Parser(%hash)
212
213Creates a new parser object. Keyword arguments are:
214
215=over 4
216
217=item B<filename>
218
219Name of the file to parse. This keyword must be present.
220
221=item B<line>
222
223Optional line where the configuration starts in B<filename>. It is used to
224keep track of statement location in the file for correct diagnostics. If
225not supplied, B<1> is assumed.
226
227=item B<fh>
228
229File handle to read from. If it is not supplied, new handle will be
230created by using B<open> on the supplied filename.
231
232=item B<lexicon>
233
234Dictionary of allowed configuration statements in the file. You will not
235need this parameter. It is listed here for completeness sake. Refer to
236the B<Config::AST> constructor for details.
237
238=back
239
240=head1 USER HOOKS
241
242These are the methods provided for implementors to do any implementation-
243specific tasks. Default implementations are empty placeholders.
244
245=head2 $cfg->init
246
247Called after creation of the base object, when parsing of the syntax
248definition has finished. Implementors can use it to do any
249implementation-specific initialization.
250
251=head2 $cfg->mangle
252
253Called after successful parsing. It can be used to modify the created
254source tree.
255
256=head1 PARSER METHODS
257
258The following two methods are derived from B<Config::AST>. They are
259called internally by the constructor, if the file name is supplied.
260
261=head2 $cfg->parse($filename, %opts)
262
263Parses the configuration from B<$filename>. Optional arguments are:
264
265=over 4
266
267=item B<fh>
268
269File handle to read from. If it is not supplied, new handle will be
270created by using B<open> on the supplied filename.
271
272=item B<line>
273
274Line to start numbering of lines from. It is used to keep track of
275statement location in the file for correct diagnostics. If not supplied,
276B<1> is assumed.
277
278=back
279
280=head2 $cfg->commit
281
282Finalizes the syntax tree. Returns true on success, and false on errors.
283
284=head1 SYNTAX DEFINITION
285
286=cut
287
135 288

Return to:

Send suggestions and report system problems to the System administrator.