Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Validator(3)  User Contributed Perl Documentation Config::Validator(3)

NAME
       Config::Validator - schema based	configuration validation

SYNOPSIS
	 use Config::Validator;

	 # simple usage
	 $validator = Config::Validator->new({ type => "list(integer)" });
	 $validator->validate([	1, 2 ]);   # OK
	 $validator->validate([	1, 2.3 ]); # FAIL
	 $validator->validate({	1, 2 });   # FAIL

	 # advanced usage
	 $validator = Config::Validator->new(
	     octet => {
		 type => "integer",
		 min  => 0,
		 max  => 255,
	     },
	     color => {
		 type	=> "struct",
		 fields	=> {
		     red   => {	type =>	"valid(octet)" },
		     green => {	type =>	"valid(octet)" },
		     blue  => {	type =>	"valid(octet)" },
		 },
	     },
	 );
	 $validator->validate(
	     { red => 23, green	=> 47,	blue =>	6 }, "color"); # OK
	 $validator->validate(
	     { red => 23, green	=> 470,	blue =>	6 }, "color"); # FAIL
	 $validator->validate(
	     { red => 23, green	=> 47,	lbue =>	6 }, "color"); # FAIL

DESCRIPTION
       This module allows to perform schema based configuration	validation.

       The idea	is to define in	a schema what valid data is. This schema can
       be used to create a validator object that can in	turn be	used to	make
       sure that some data indeed conforms to the schema.

       Although	the primary focus is on	"configuration"	(for instance as
       provided	by modules like	Config::General) and, to a lesser extent,
       "options" (for instance as provided by modules like Getopt::Long), this
       module can in fact validate any data structure.

METHODS
       The following methods are available:

       new([OPTIONS])
	   return a new	Config::Validator object (class	method)

       options([NAME])
	   convert the named schema (or	the default schema if the name is not
	   given) to a list of Getopt::Long compatible options

       validate(DATA[, NAME])
	   validate the	given data using the named schema (or the default
	   schema if the name is not given)

       traverse(CALLBACK, DATA[, NAME])
	   traverse the	given data using the named schema (or the default
	   schema if the name is not given) and	call the given CALLBACK	on
	   each	node

FUNCTIONS
       The following convenient	functions are available:

       is_true(SCALAR)
	   check if the	given scalar is	the boolean "true"

       is_false(SCALAR)
	   check if the	given scalar is	the boolean "false"

       is_regexp(SCALAR)
	   check if the	given scalar is	a compiled regular expression

       expand_duration(STRING)
	   convert a string representing a duration (such as "1h10m12s") into
	   the corresponding number of seconds (such as	"4212")

       expand_size(STRING)
	   convert a string representing a size	(such as "1.5kB") into the
	   corresponding integer (such as "1536")

       listof(SCALAR)
	   return the given scalar as a	list, dereferencing it if it is	a list
	   reference (this is very useful with the "list?(X)" type)

       string2hash(STRING)
	   convert a string of space separated key=value pairs into a hash or
	   hash	reference

       hash2string(HASH)
	   convert a hash or hash reference into a string of space separated
	   key=value pairs

       treeify(HASH)
	   modify (in place) a hash reference to turn it into a	tree, using
	   the dash character to split keys

       treeval(HASH, NAME)
	   return the value of the given option	(e.g. "foo-bar") in a
	   treeified hash

       mutex(HASH, NAME...)
	   treat the given options as mutually exclusive

       reqall(HASH, NAME1, NAME...)
	   if the first	option is set, all the others are required

       reqany(HASH, NAME1, NAME...)
	   if the first	option is set, one at least of the others is required

SCHEMAS
       A schema	is simply a structure (i.e. a hash reference) with the
       following fields	(all of	them being optional except the first one):

       type
	   the type of the thing to validate (see the "TYPES" section for the
	   complete list); this	can also be a list of possible types (e.g.
	   "integer" or	"undef")

       subtype
	   for an homogeneous list or table, the schema	of its elements

       fields
	   for a structure, a table of the allowed fields, in the form:	field
	   name	=> corresponding schema

       optional
	   for a structure field, it indicates that the	field is optional

       min the minimum length/size, only for some types	(integer, number,
	   string, list	and table)

       max the maximum length/size, only for some types	(integer, number,
	   string, list	and table)

       match
	   a regular expression	used to	validate a string or table keys

       check
	   a code reference allowing to	run user-supplied code to further
	   validate the	data

       As an example, the following schema describe what a valid schema	is:

	 {
	   type	  => "struct",
	   fields => {
	     type     => { type	=> "list?(valid(type))"	},
	     subtype  => { type	=> "valid(schema)",	   optional => "true" },
	     fields   => { type	=> "table(valid(schema))", optional => "true" },
	     optional => { type	=> "boolean",		   optional => "true" },
	     min      => { type	=> "number",		   optional => "true" },
	     max      => { type	=> "number",		   optional => "true" },
	     match    => { type	=> "regexp",		   optional => "true" },
	     check    => { type	=> "code",		   optional => "true" },
	   },
	 }

NAMED SCHEMAS
       For convenience and self-reference, schemas can be named.

       To use named schemas, give them along with their	names to the new()
       method:

	 $validator = Config::Validator->new(
	     name1 => {	... schema1 ...	},
	     name2 => {	... schema2 ...	},
	 );

       You can then refer to them in the validate() method:

	 $validator->validate($data, "name1");

       If you don't need named schemas,	you can	use the	simpler	form:

	 $validator = Config::Validator->new({ ... schema ... });
	 $validator->validate($data);

TYPES
       Here are	the different types that can be	used:

       anything
	   really anything, including undef

       undef
	   the undefined value

       undefined
	   synonym for "undef"

       defined
	   anything but	undef

       string
	   any string (in fact,	anything that is defined and not a reference)

       boolean
	   either "true" or "false"

       number
	   any number (this is tested using a regular expression)

       integer
	   any integer (this is	tested using a regular expression)

       duration
	   any duration	(integers with optional	time suffixes)

       size
	   any size (integer with optional fractional part and optional	byte-
	   suffix)

       hostname
	   any host name (as per RFC 1123)

       ipv4
	   any IPv4 address (this is tested using a regular expression)

       ipv6
	   any IPv6 address (this is tested using a regular expression)

       reference
	   any reference, blessed or not

       ref(*)
	   synonym for "reference"

       blessed
	   any blessed reference

       object
	   synonym for "blessed"

       isa(*)
	   synonym for "blessed"

       unblessed
	   any reference which is not blessed

       code
	   a code reference

       regexp
	   a compiled regular expression

       list
	   an homogeneous list

       list(X)
	   idem	but with the given subtype

       list?(X)
	   shortcut for	either "X" or list(X)

       table
	   an homogeneous table

       table(X)
	   idem	but with the given subtype

       struct
	   a structure,	i.e. a table with known	keys

       ref(X)
	   a reference of the given kind

       isa(X)
	   an object of	the given kind

       valid(X)
	   something valid according to	the given named	schema

EXAMPLES
   CONFIGURATION VALIDATION
       This module works well with Config::General. In particular, the
       "list?(X)" type matches the way Config::General merges blocks.

       For instance, one could use the following code:

	 use Config::General qw(ParseConfig);
	 use Config::Validator;
	 $validator = Config::Validator->new(
	   service => {
	     type   => "struct",
	     fields => {
	       port  =>	{ type => "integer", min => 0, max => 65535 },
	       proto =>	{ type => "string" },
	     },
	   },
	   host	=> {
	     type   => "struct",
	     fields => {
	       name    => { type => "string", match => qr/^\w+$/ },
	       service => { type => "list?(valid(service))" },
	     },
	   },
	 );
	 %cfg =	ParseConfig(-ConfigFile	=> $path, -CComments =>	0);
	 $validator->validate($cfg{host}, "host");

       This would work with:

	 <host>
	   name	= foo
	   <service>
	     port = 80
	     proto = http
	   </service>
	 </host>

       where $cfg{host}{service} is the	service	hash but also with:

	 <host>
	   name	= foo
	   <service>
	     port = 80
	     proto = http
	   </service>
	   <service>
	     port = 443
	     proto = https
	   </service>
	 </host>

       where $cfg{host}{service} is the	list of	service	hashes.

   OPTIONS VALIDATION
       This module interacts nicely with Getopt::Long: the options() method
       can be used to convert a	schema into a list of Getopt::Long options.

       Here is a simple	example:

	 use Config::Validator;
	 use Getopt::Long qw(GetOptions);
	 use Pod::Usage	qw(pod2usage);
	 $validator = Config::Validator->new({
	   type	  => "struct",
	   fields => {
	     debug => {
	       type	=> "boolean",
	       optional	=> "true",
	     },
	     proto => {
	       type  =>	"string",
	       match =>	qr/^\w+$/,
	     },
	     port => {
	       type => "integer",
	       min  => 0,
	       max  => 65535,
	     },
	   },
	 });
	 @options = $validator->options();
	 GetOptions(\%cfg, @options) or	pod2usage(2);
	 $validator->validate(\%cfg);

   ADVANCED VALIDATION
       This module can also be used to combine configuration and options
       validation using	the same schema. The idea is to:

       o   define a unique schema validating both configuration	and options

       o   parse the command line options using	Getopt::Long (first pass, to
	   detect a "--config" option)

       o   read	the configuration file using Config::General

       o   parse again the command line	options, using the configuration data
	   as default values

       o   validate the	merged configuration/options data

       In some situations, it may make sense to	consider the configuration
       data as a tree and prefer:

	 <incoming>
	   uri = foo://host1:1234
	 </incoming>
	 <outgoing>
	   uri = foo://host2:2345
	 </outgoing>

       to:

	 incoming-uri =	foo://host1:1234
	 outgoing-uri =	foo://host2:2345

       The options() method flatten the	schema to get a	list of	command	line
       options and the treeify() function transform flat options (as returned
       by Getopt::Long)	into a deep tree so that it matches the	schema.	 Then
       the treeval() function can conveniently access the value	of an option.

       See the bundled examples	for complete working programs illustrating
       some of the possibilities of this module.

AUTHOR
       Lionel Cons <http://cern.ch/lionel.cons>

       Copyright (C) CERN 2012-2015

perl v5.32.0			  2015-11-30		  Config::Validator(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | FUNCTIONS | SCHEMAS | NAMED SCHEMAS | TYPES | EXAMPLES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Validator&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help