1Config::Validator(3)  User Contributed Perl Documentation Config::Validator(3)
2
3
4

NAME

6       Config::Validator - schema based configuration validation
7

SYNOPSIS

9         use Config::Validator;
10
11         # 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
17         # 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

DESCRIPTION

41       This module allows to perform schema based configuration validation.
42
43       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
47       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

METHODS

53       The following methods are available:
54
55       new([OPTIONS])
56           return a new Config::Validator object (class method)
57
58       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
62       validate(DATA[, NAME])
63           validate the given data using the named schema (or the default
64           schema if the name is not given)
65
66       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

FUNCTIONS

72       The following convenient functions are available:
73
74       is_true(SCALAR)
75           check if the given scalar is the boolean "true"
76
77       is_false(SCALAR)
78           check if the given scalar is the boolean "false"
79
80       is_regexp(SCALAR)
81           check if the given scalar is a compiled regular expression
82
83       expand_duration(STRING)
84           convert a string representing a duration (such as "1h10m12s") into
85           the corresponding number of seconds (such as "4212")
86
87       expand_size(STRING)
88           convert a string representing a size (such as "1.5kB") into the
89           corresponding integer (such as "1536")
90
91       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
95       string2hash(STRING)
96           convert a string of space separated key=value pairs into a hash or
97           hash reference
98
99       hash2string(HASH)
100           convert a hash or hash reference into a string of space separated
101           key=value pairs
102
103       treeify(HASH)
104           modify (in place) a hash reference to turn it into a tree, using
105           the dash character to split keys
106
107       treeval(HASH, NAME)
108           return the value of the given option (e.g. "foo-bar") in a
109           treeified hash
110
111       mutex(HASH, NAME...)
112           treat the given options as mutually exclusive
113
114       reqall(HASH, NAME1, NAME...)
115           if the first option is set, all the others are required
116
117       reqany(HASH, NAME1, NAME...)
118           if the first option is set, one at least of the others is required
119

SCHEMAS

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
124       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
129       subtype
130           for an homogeneous list or table, the schema of its elements
131
132       fields
133           for a structure, a table of the allowed fields, in the form: field
134           name => corresponding schema
135
136       optional
137           for a structure field, it indicates that the field is optional
138
139       min the minimum length/size, only for some types (integer, number,
140           string, list and table)
141
142       max the maximum length/size, only for some types (integer, number,
143           string, list and table)
144
145       match
146           a regular expression used to validate a string or table keys
147
148       check
149           a code reference allowing to run user-supplied code to further
150           validate the data
151
152       As an example, the following schema describe what a valid schema is:
153
154         {
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

NAMED SCHEMAS

169       For convenience and self-reference, schemas can be named.
170
171       To use named schemas, give them along with their names to the new()
172       method:
173
174         $validator = Config::Validator->new(
175             name1 => { ... schema1 ... },
176             name2 => { ... schema2 ... },
177         );
178
179       You can then refer to them in the validate() method:
180
181         $validator->validate($data, "name1");
182
183       If you don't need named schemas, you can use the simpler form:
184
185         $validator = Config::Validator->new({ ... schema ... });
186         $validator->validate($data);
187

TYPES

189       Here are the different types that can be used:
190
191       anything
192           really anything, including undef
193
194       undef
195           the undefined value
196
197       undefined
198           synonym for "undef"
199
200       defined
201           anything but undef
202
203       string
204           any string (in fact, anything that is defined and not a reference)
205
206       boolean
207           either "true" or "false"
208
209       number
210           any number (this is tested using a regular expression)
211
212       integer
213           any integer (this is tested using a regular expression)
214
215       duration
216           any duration (integers with optional time suffixes)
217
218       size
219           any size (integer with optional fractional part and optional byte-
220           suffix)
221
222       hostname
223           any host name (as per RFC 1123)
224
225       ipv4
226           any IPv4 address (this is tested using a regular expression)
227
228       ipv6
229           any IPv6 address (this is tested using a regular expression)
230
231       reference
232           any reference, blessed or not
233
234       ref(*)
235           synonym for "reference"
236
237       blessed
238           any blessed reference
239
240       object
241           synonym for "blessed"
242
243       isa(*)
244           synonym for "blessed"
245
246       unblessed
247           any reference which is not blessed
248
249       code
250           a code reference
251
252       regexp
253           a compiled regular expression
254
255       list
256           an homogeneous list
257
258       list(X)
259           idem but with the given subtype
260
261       list?(X)
262           shortcut for either "X" or list(X)
263
264       table
265           an homogeneous table
266
267       table(X)
268           idem but with the given subtype
269
270       struct
271           a structure, i.e. a table with known keys
272
273       ref(X)
274           a reference of the given kind
275
276       isa(X)
277           an object of the given kind
278
279       valid(X)
280           something valid according to the given named schema
281

EXAMPLES

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
287       For instance, one could use the following code:
288
289         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
310       This would work with:
311
312         <host>
313           name = foo
314           <service>
315             port = 80
316             proto = http
317           </service>
318         </host>
319
320       where $cfg{host}{service} is the service hash but also with:
321
322         <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
334       where $cfg{host}{service} is the list of service hashes.
335
336   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
340       Here is a simple example:
341
342         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
367   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
371       ·   define a unique schema validating both configuration and options
372
373       ·   parse the command line options using Getopt::Long (first pass, to
374           detect a "--config" option)
375
376       ·   read the configuration file using Config::General
377
378       ·   parse again the command line options, using the configuration data
379           as default values
380
381       ·   validate the merged configuration/options data
382
383       In some situations, it may make sense to consider the configuration
384       data as a tree and prefer:
385
386         <incoming>
387           uri = foo://host1:1234
388         </incoming>
389         <outgoing>
390           uri = foo://host2:2345
391         </outgoing>
392
393       to:
394
395         incoming-uri = foo://host1:1234
396         outgoing-uri = foo://host2:2345
397
398       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
403       See the bundled examples for complete working programs illustrating
404       some of the possibilities of this module.
405

AUTHOR

407       Lionel Cons <http://cern.ch/lionel.cons>
408
409       Copyright (C) CERN 2012-2015
410
411
412
413perl v5.32.0                      2020-07-28              Config::Validator(3)
Impressum