diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2019-08-20 16:02:08 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2019-08-20 16:02:08 +0300 |
commit | b3d1cf2fb648f77a6ea432486ba2a8f026068f11 (patch) | |
tree | 97e6450c863b478ec62bb25134e86e6434705e1a /lib/Config/Parser | |
parent | e9f110af920cf4e6642bc3301340b23a7a2a6589 (diff) | |
download | config-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.pm | 174 |
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 | ||
95 | 1; | 95 | 1; |
96 | 96 | ||
97 | =head1 NAME | ||
98 | |||
99 | Config::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 | |||
107 | print $val->value; | ||
108 | print $val->locus; | ||
109 | |||
110 | $val = $cfg->tree->Dir->Tmp; | ||
111 | |||
112 | =head1 DESCRIPTION | ||
113 | |||
114 | An I<ini-style configuration file> is a textual file consisting of settings | ||
115 | grouped into one or more sections. A I<setting> has the form | ||
116 | |||
117 | KEYWORD = VALUE | ||
118 | |||
119 | where I<KEYWORD> is the setting name and I<VALUE> is its value. | ||
120 | Syntactically, I<VALUE> is anything to the right of the equals sign and up | ||
121 | to the linefeed character terminating the line (ASCII 10), not including | ||
122 | the leading and trailing whitespace characters. | ||
123 | |||
124 | Each setting occupies one line. Very long lines can be split over several | ||
125 | physical lines by ending each line fragment except the last with a backslash | ||
126 | character appearing right before the linefeed character. | ||
127 | |||
128 | A I<section> begins with a section declaration in the following form: | ||
129 | |||
130 | [NAME NAME...] | ||
131 | |||
132 | Here, square brackets form part of the syntax. Any number of I<NAME>s | ||
133 | can be present inside the square brackets. The first I<NAME> must follow the | ||
134 | usual rules for a valid identifier name. Rest of I<NAME>s can contain any | ||
135 | characters, provided that any I<NAME> that includes non-alphanumeric characters | ||
136 | is enclosed in a pair of double-quotes. Any double-quotes and backslash | ||
137 | characters appearing within the quoted string must be escaped by prefixing | ||
138 | them with a single backslash. | ||
139 | |||
140 | The B<Config::Parser::Ini> module is a framework for parsing such files. | ||
141 | |||
142 | In the simplest case, the usage of this module is as simple as in the following | ||
143 | fragment: | ||
144 | |||
145 | use Config::Parser::Ini; | ||
146 | my $cf = new Config::Parser::Ini(filename => "config.ini"); | ||
147 | |||
148 | On success, this returns a valid B<Config::Parser::Ini> object. On error, | ||
149 | the diagnostic message is issued using the B<error> method (see the description | ||
150 | of the method in B<Config::AST>(3)) and the module croaks. | ||
151 | |||
152 | This usage, although simple, has one major drawback - no checking is performed | ||
153 | on the input file, except for the syntax check. To fix this, you can supply | ||
154 | a dictionary (or I<lexicon>) of allowed keywords along with their values. | ||
155 | Such a dictionary is itself a valid ini file, where the value of each | ||
156 | keyword describes its properties. The dictionary is placed in the B<__DATA__> | ||
157 | section of the source file which invokes the B<Config::Parser::Ini> constructor. | ||
158 | |||
159 | Expanding 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 | |||
172 | This code specifies that the configuration file can contain at most two | ||
173 | sections: C<[core]> and C<[user]>. Two keywords are defined within each | ||
174 | section. Data types are specified for each keyword, so the parser will | ||
175 | bail out in case of type mismatches. If the B<core.root> setting is not | ||
176 | present in the configuration, the default one will be created with the | ||
177 | value C</>. | ||
178 | |||
179 | It is often advisable to create a subclass of B<Config::Parser::Ini> and | ||
180 | use 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 | |||
193 | Then, to parse the configuration file, it will suffice to do: | ||
194 | |||
195 | $cf = my App::MyConf(filename => "config.ini"); | ||
196 | |||
197 | One advantage of this approach is that it will allow you to install | ||
198 | additional validation for the configuration statements using the | ||
199 | B<:check> option. The argument to this option is the name of a | ||
200 | method which will be invoked after parsing the statement in order | ||
201 | to verify its value. It is described in detail below (see the section | ||
202 | B<SYNTAX DEFINITION> in the documentation of B<Config::Parser>). | ||
203 | For example, if you wish to ensure that the value of the C<root> setting | ||
204 | in 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 | |||
232 | Creates a new parser object. Keyword arguments are: | ||
233 | |||
234 | =over 4 | ||
235 | |||
236 | =item B<filename> | ||
237 | |||
238 | Name of the file to parse. If not supplied, you will have to | ||
239 | call the B<$cfg-E<gt>parse> method explicitly after you are returned a | ||
240 | valid B<$cfg>. | ||
241 | |||
242 | =item B<line> | ||
243 | |||
244 | Optional line where the configuration starts in B<filename>. It is used to | ||
245 | keep track of statement location in the file for correct diagnostics. If | ||
246 | not supplied, B<1> is assumed. | ||
247 | |||
248 | =item B<fh> | ||
249 | |||
250 | File handle to read from. If it is not supplied, new handle will be | ||
251 | created by using B<open> on the supplied filename. | ||
252 | |||
253 | =item B<lexicon> | ||
254 | |||
255 | Dictionary of allowed configuration statements in the file. You will not | ||
256 | need this parameter. It is listed here for completeness sake. Refer to | ||
257 | the B<Config::AST> constructor for details. | ||
258 | |||
259 | =back | ||
260 | |||
261 | =head1 METHODS | ||
262 | |||
263 | All methods are inferited from B<Config::Parser>. Please see its | ||
264 | documentation for details. | ||
265 | |||
266 | =head1 SEE ALSO | ||
267 | |||
268 | B<Config::Parser>(3), B<Config::AST>(3). | ||
269 | |||
270 | =cut | ||