1Config::Validator(3) User Contributed Perl Documentation Config::Validator(3)
2
6 Config::Validator - schema based configuration validation
7
9 use Config::Validator;
10 # simple usage
12 $validator = Config::Validator->new({ type => "list(integer)" });
13 $validator->validate([ 1, 2 ]); # OK
14 $validator->validate([ 1, 2.3 ]); # FAIL
15 $validator->validate({ 1, 2 }); # FAIL
16 # advanced usage
18 $validator = Config::Validator->new(
19 octet => {
20 type => "integer",
21 min => 0,
22 max => 255,
23 },
24 color => {
25 type => "struct",
26 fields => {
27 red => { type => "valid(octet)" },
28 green => { type => "valid(octet)" },
29 blue => { type => "valid(octet)" },
30 },
31 },
32 );
33 $validator->validate(
34 { red => 23, green => 47, blue => 6 }, "color"); # OK
35 $validator->validate(
36 { red => 23, green => 470, blue => 6 }, "color"); # FAIL
37 $validator->validate(
38 { red => 23, green => 47, lbue => 6 }, "color"); # FAIL
39
41 This module allows to perform schema based configuration validation.
42 The idea is to define in a schema what valid data is. This schema can
44 be used to create a validator object that can in turn be used to make
45 sure that some data indeed conforms to the schema.
46 Although the primary focus is on "configuration" (for instance as
48 provided by modules like Config::General) and, to a lesser extent,
49 "options" (for instance as provided by modules like Getopt::Long), this
50 module can in fact validate any data structure.
51
53 The following methods are available:
54 new([OPTIONS])
56 return a new Config::Validator object (class method)
57 options([NAME])
59 convert the named schema (or the default schema if the name is not
60 given) to a list of Getopt::Long compatible options
61 validate(DATA[, NAME])
63 validate the given data using the named schema (or the default
64 schema if the name is not given)
65 traverse(CALLBACK, DATA[, NAME])
67 traverse the given data using the named schema (or the default
68 schema if the name is not given) and call the given CALLBACK on
69 each node
70
72 The following convenient functions are available:
73 is_true(SCALAR)
75 check if the given scalar is the boolean "true"
76 is_false(SCALAR)
78 check if the given scalar is the boolean "false"
79 is_regexp(SCALAR)
81 check if the given scalar is a compiled regular expression
82 expand_duration(STRING)
84 convert a string representing a duration (such as "1h10m12s") into
85 the corresponding number of seconds (such as "4212")
86 expand_size(STRING)
88 convert a string representing a size (such as "1.5kB") into the
89 corresponding integer (such as "1536")
90 listof(SCALAR)
92 return the given scalar as a list, dereferencing it if it is a list
93 reference (this is very useful with the "list?(X)" type)
94 string2hash(STRING)
96 convert a string of space separated key=value pairs into a hash or
97 hash reference
98 hash2string(HASH)
100 convert a hash or hash reference into a string of space separated
101 key=value pairs
102 treeify(HASH)
104 modify (in place) a hash reference to turn it into a tree, using
105 the dash character to split keys
106 treeval(HASH, NAME)
108 return the value of the given option (e.g. "foo-bar") in a
109 treeified hash
110 mutex(HASH, NAME...)
112 treat the given options as mutually exclusive
113 reqall(HASH, NAME1, NAME...)
115 if the first option is set, all the others are required
116 reqany(HASH, NAME1, NAME...)
118 if the first option is set, one at least of the others is required
119
121 A schema is simply a structure (i.e. a hash reference) with the
122 following fields (all of them being optional except the first one):
123 type
125 the type of the thing to validate (see the "TYPES" section for the
126 complete list); this can also be a list of possible types (e.g.
127 "integer" or "undef")
128 subtype
130 for an homogeneous list or table, the schema of its elements
131 fields
133 for a structure, a table of the allowed fields, in the form: field
134 name => corresponding schema
135 optional
137 for a structure field, it indicates that the field is optional
138 min the minimum length/size, only for some types (integer, number,
140 string, list and table)
141 max the maximum length/size, only for some types (integer, number,
143 string, list and table)
144 match
146 a regular expression used to validate a string or table keys
147 check
149 a code reference allowing to run user-supplied code to further
150 validate the data
151 As an example, the following schema describe what a valid schema is:
153 {
155 type => "struct",
156 fields => {
157 type => { type => "list?(valid(type))" },
158 subtype => { type => "valid(schema)", optional => "true" },
159 fields => { type => "table(valid(schema))", optional => "true" },
160 optional => { type => "boolean", optional => "true" },
161 min => { type => "number", optional => "true" },
162 max => { type => "number", optional => "true" },
163 match => { type => "regexp", optional => "true" },
164 check => { type => "code", optional => "true" },
165 },
166 }
167
169 For convenience and self-reference, schemas can be named.
170 To use named schemas, give them along with their names to the new()
172 method:
173 $validator = Config::Validator->new(
175 name1 => { ... schema1 ... },
176 name2 => { ... schema2 ... },
177 );
178 You can then refer to them in the validate() method:
180 $validator->validate($data, "name1");
182 If you don't need named schemas, you can use the simpler form:
184 $validator = Config::Validator->new({ ... schema ... });
186 $validator->validate($data);
187
189 Here are the different types that can be used:
190 anything
192 really anything, including undef
193 undef
195 the undefined value
196 undefined
198 synonym for "undef"
199 defined
201 anything but undef
202 string
204 any string (in fact, anything that is defined and not a reference)
205 boolean
207 either "true" or "false"
208 number
210 any number (this is tested using a regular expression)
211 integer
213 any integer (this is tested using a regular expression)
214 duration
216 any duration (integers with optional time suffixes)
217 size
219 any size (integer with optional fractional part and optional byte-
220 suffix)
221 hostname
223 any host name (as per RFC 1123)
224 ipv4
226 any IPv4 address (this is tested using a regular expression)
227 ipv6
229 any IPv6 address (this is tested using a regular expression)
230 reference
232 any reference, blessed or not
233 ref(*)
235 synonym for "reference"
236 blessed
238 any blessed reference
239 object
241 synonym for "blessed"
242 isa(*)
244 synonym for "blessed"
245 unblessed
247 any reference which is not blessed
248 code
250 a code reference
251 regexp
253 a compiled regular expression
254 list
256 an homogeneous list
257 list(X)
259 idem but with the given subtype
260 list?(X)
262 shortcut for either "X" or list(X)
263 table
265 an homogeneous table
266 table(X)
268 idem but with the given subtype
269 struct
271 a structure, i.e. a table with known keys
272 ref(X)
274 a reference of the given kind
275 isa(X)
277 an object of the given kind
278 valid(X)
280 something valid according to the given named schema
281
283 CONFIGURATION VALIDATION
284 This module works well with Config::General. In particular, the
285 "list?(X)" type matches the way Config::General merges blocks.
286 For instance, one could use the following code:
288 use Config::General qw(ParseConfig);
290 use Config::Validator;
291 $validator = Config::Validator->new(
292 service => {
293 type => "struct",
294 fields => {
295 port => { type => "integer", min => 0, max => 65535 },
296 proto => { type => "string" },
297 },
298 },
299 host => {
300 type => "struct",
301 fields => {
302 name => { type => "string", match => qr/^\w+$/ },
303 service => { type => "list?(valid(service))" },
304 },
305 },
306 );
307 %cfg = ParseConfig(-ConfigFile => $path, -CComments => 0);
308 $validator->validate($cfg{host}, "host");
309 This would work with:
311 <host>
313 name = foo
314 <service>
315 port = 80
316 proto = http
317 </service>
318 </host>
319 where $cfg{host}{service} is the service hash but also with:
321 <host>
323 name = foo
324 <service>
325 port = 80
326 proto = http
327 </service>
328 <service>
329 port = 443
330 proto = https
331 </service>
332 </host>
333 where $cfg{host}{service} is the list of service hashes.
335 OPTIONS VALIDATION
337 This module interacts nicely with Getopt::Long: the options() method
338 can be used to convert a schema into a list of Getopt::Long options.
339 Here is a simple example:
341 use Config::Validator;
343 use Getopt::Long qw(GetOptions);
344 use Pod::Usage qw(pod2usage);
345 $validator = Config::Validator->new({
346 type => "struct",
347 fields => {
348 debug => {
349 type => "boolean",
350 optional => "true",
351 },
352 proto => {
353 type => "string",
354 match => qr/^\w+$/,
355 },
356 port => {
357 type => "integer",
358 min => 0,
359 max => 65535,
360 },
361 },
362 });
363 @options = $validator->options();
364 GetOptions(\%cfg, @options) or pod2usage(2);
365 $validator->validate(\%cfg);
366 ADVANCED VALIDATION
368 This module can also be used to combine configuration and options
369 validation using the same schema. The idea is to:
370 • define a unique schema validating both configuration and options
372 • parse the command line options using Getopt::Long (first pass, to
374 detect a "--config" option)
375 • read the configuration file using Config::General
377 • parse again the command line options, using the configuration data
379 as default values
380 • validate the merged configuration/options data
382 In some situations, it may make sense to consider the configuration
384 data as a tree and prefer:
385 <incoming>
387 uri = foo://host1:1234
388 </incoming>
389 <outgoing>
390 uri = foo://host2:2345
391 </outgoing>
392 to:
394 incoming-uri = foo://host1:1234
396 outgoing-uri = foo://host2:2345
397 The options() method flatten the schema to get a list of command line
399 options and the treeify() function transform flat options (as returned
400 by Getopt::Long) into a deep tree so that it matches the schema. Then
401 the treeval() function can conveniently access the value of an option.
402 See the bundled examples for complete working programs illustrating
404 some of the possibilities of this module.
405
407 Lionel Cons <http://cern.ch/lionel.cons>
408 Copyright (C) CERN 2012-2015
410perl v5.36.0 2022-07-22 Config::Validator(3)