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