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

FreeBSD Manual Pages


home | help
Config::Model::Value(3User Contributed Perl DocumentatiConfig::Model::Value(3)

       Config::Model::Value - Strongly typed configuration value

       version 2.140

	use Config::Model;

	# define configuration tree object
	my $model = Config::Model->new;
	$model ->create_config_class (
	   name	=> "MyClass",

	   element => [

	       [qw/foo bar/] =>	{
		   type		  => 'leaf',
		   value_type => 'string',
		   description => 'foobar',
	       country => {
		   type	=>		 'leaf',
		   value_type => 'enum',
		   choice =>	  [qw/France US/],
		   description => 'big countries',
	) ;

	my $inst = $model->instance(root_class_name => 'MyClass' );

	my $root = $inst->config_root ;

	# put data
	$root->load( steps => 'foo=FOO country=US' );

	print $root->report ;
	#  foo = FOO
	#		 DESCRIPTION: foobar
	#  country = US
	#		 DESCRIPTION: big countries

       This class provides a way to specify configuration value	with the
       following properties:

       o   Strongly typed scalar: the value can	either be an enumerated	type,
	   a boolean, a	number,	an integer or a	string

       o   default parameter: a	value can have a default value specified
	   during the construction. This default value is written in the
	   target configuration	file. ("default" parameter)

       o   upstream default parameter: specifies a default value that is used
	   by the application when no information is provided in the
	   configuration file. This upstream_default value is not written in
	   the configuration files. Only the "fetch_standard" method returns
	   the builtin value. This parameter was previously referred as
	   "built_in" value. This may be used for audit	purpose.
	   ("upstream_default" parameter)

       o   mandatory value: reading a mandatory	value raises an	exception if
	   the value is	not specified and has no default value.

       o   dynamic change of property: A slave value can be registered to
	   another master value	so that	the properties of the slave value can
	   change according to the value of the	master value. For instance,
	   paper size value can	be 'letter' for	country	'US' and 'A4' for
	   country 'France'.

       o   A reference to the Id of a hash of list element. In other word, the
	   value is an enumerated type where the possible values (choice) is
	   defined by the existing keys	of a has element somewhere in the
	   tree. See "Value Reference".

Default	values
       There are several kind of default values. They depend on	where these
       values are defined (or found).

       From the	lowest default level to	the "highest":

       o   "upstream_default": The value is known in the application, but is
	   not written in the configuration file.

       o   "layered": The value	is known by the	application through another
	   mean	(e.g. an included configuration	file), but is not written in
	   the configuration file.

       o   "default": The value	is known by the	model, but not by the
	   application.	This value must	be written in the configuration	file.

       o   "computed": The value is computed from other	configuration
	   elements. This value	must be	written	in the configuration file.

       o   "preset": The value is not known by the model or by the
	   application.	But it can be found by an automatic program and	stored
	   while the configuration Config::Model::Instance is in preset	mode

       Then there is the value entered by the user. This overrides all kind of
       "default" value.

       The fetch_standard function returns the "highest" level of default
       value, but does not return a custom value, i.e. a value entered by the

       Value object should not be created directly.

Value model declaration
       A leaf element must be declared with the	following parameters:

	   Either "boolean", "enum", "integer",	"number", "uniline", "string",
	   "file", "dir". Mandatory. See "Value	types".

	   Specify the default value (optional)

	   Specify a built in default value (optional).	I.e a value known by
	   the application which does not need to be written in	the
	   configuration file.

	   Array ref. Reserved for boolean value. Specify how to write a
	   boolean value.  Default is "[0,1]" which may	not be the most
	   readable. "write_as"	can be specified as "['false','true']" or

	   Computes a value according to a formula and other values. By
	   default a computed value cannot be set. See
	   Config::Model::ValueComputer	for computed value declaration.

	   This	is a special parameter to cater	for smooth configuration
	   upgrade. This parameter can be used to copy the value of a
	   deprecated parameter	to its replacement. See	"Upgrade" for details.

       convert => [uc |	lc ]
	   When	stored,	the value is converted to uppercase (uc) or lowercase

       min Specify the minimum value (optional,	only for integer, number)

       max Specify the maximum value (optional,	only for integer, number)

	   Set to 1 if the configuration value must be set by the
	   configuration user (default:	0)

	   Array ref of	the possible value of an enum. Example :

	    choice => [	qw/foo bar/]

	   Perl	regular	expression. The	value is matched with the regex	to
	   assert its validity.	Example	"match => '^foo'" means	that the
	   parameter value must	begin with "foo". Valid	only for "string" or
	   "uniline" values.

	   Hash	ref. Keys are made of Perl regular expression. The value can
	   specify a warning message (leave empty or undefined for a default
	   warning message) and	instructions to	fix the	value. A warning is
	   issued when the value matches the passed regular expression.	Valid
	   only	for "string" or	"uniline" values. The fix instructions is
	   evaluated when apply_fixes is called. $_ contains the value to fix.
	   $_ is stored	as the new value once the instructions are done.
	   $self contains the value object. Use	with care.

	   In the example below, any value matching 'foo' is converted in

	    warn_if_match => {
	      'foo' => {
		   fix => 'uc;',
		   msg =>  'value $_ contains foo'
	      'BAR' => {
		   fix =>'lc;',
		   msg =>  'value $_ contains BAR'

	   The tests are done in alphabetical order. In	the example above,
	   "BAR" test is done before "foo" test.

	   $_ is substituted with the bad value	when the message is generated.
	   $std_value is substituted with the standard value (i.e the preset,
	   computed or default value).

	   Hash	ref like above.	A warning is issued when the value does	not
	   match the passed regular expression.	Valid only for "string"	or
	   "uniline" values.

	   String. Issue a warning to user with	the specified string any time
	   a value is set or read.

	   A bit like "warn_if_match". The hash	key is not a regexp but	a
	   label to help users.	The hash ref contains some Perl	code that is
	   evaluated to	perform	the test. A warning is issued if the given
	   code	returns	true.

	   $_ contains the value to check. $self contains the
	   "Config::Model::Value" object (use with care).

	   The example below warns if value contains a number:

	    warn_if => {
	       warn_test => {
		   code	=> 'defined $_ && /\d/;',
		   msg	=> 'value $_ should not	have numbers',
		   fix	=> 's/\d//g;'

	   Hash	key is used in warning message when "msg" is not set:

	    warn_if => {
	      'should begin with foo' => {
		   code	=> 'defined && /^foo/'

	   Any operation or check on file must be done with "file" sub
	   (otherwise tests will break). This sub returns a Path::Tiny object
	   that	can be used to perform checks. For instance:

	     warn_if =>	{
		warn_test => {
		    code => 'not file($_)->exists',
		    msg	 => 'file $_ should exist'

	   Like	"warn_if", but issue a warning when the	given "code" returns

	   The example below warns unless the value points to an existing

	    warn_unless	=> {
		'missing dir' => {
		     code => '-d',
		     fix => "system(mkdir $_);"	}

	   Like	"warn_if". Except that returned	value triggers an error	when
	   the given code returns false:

	    assert => {
	       test_nb => {
		   code	=> 'defined $_ && /\d/;',
		   msg	=> 'should not have numbers',
		   fix	=> 's/\d//g;'

	   hash	key can	also be	used to	generate error message when "msg"
	   parameter is	not set.

	   Setup a Parse::RecDescent grammar to	perform	validation.

	   If the grammar does not start with a	"check"	rule (i.e does not
	   start with "check: "), the first line of the	grammar	is modified to
	   add "check" rule and	this rules is set up so	the entire value must
	   match the passed grammar.

	   I.e.	the grammar:

	    token (oper	token)(s?)
	    oper: 'and'	| 'or'
	    token: 'Apache' | 'CC-BY' |	'Perl'

	   is changed to

	    check: token (oper token)(s?) /^\Z/	{$return = 1;}
	    oper: 'and'	| 'or'
	    token: 'Apache' | 'CC-BY' |	'Perl'

	   The rule is called with Value object	and a string reference.	So, in
	   the actions you may need to define, you can call the	value object
	   as $arg[0], store error message in "${$arg[1]}}" and	store warnings
	   in "${$arg[2]}}".

	   Hash	ref. Used for enum to substitute one value with	another. This
	   parameter must be used to enable user to upgrade a configuration
	   with	obsolete values. For instance, if the value "foo" is obsolete
	   and replaced	by "foo_better", you must declare:

	    replace => { foo =>	'foo_better' }

	   The hash key	can also be a regular expression for wider range
	   replacement.	 The regexp must match the whole value:

	    replace => ( 'foo.*' => 'better_foo' }

	   In this case, a value is replaced by	"better_foo" when the
	   "/^foo.*$/" regexp matches.

	   Path	specifying a hash of value element in the configuration	tree.
	   The hash if used in a way similar to	the "replace" parameter. In
	   this	case, the replacement is not coded in the model	but specified
	   by the configuration.

	   Specify a path to an	id element used	as a reference.	See Value
	   Reference for details.

	   Specify a path to an	id element used	as a computed reference. See
	   "Value Reference" for details.

	   See section below: "Warp: dynamic value configuration".

	   You may provide detailed description	on possible values with	a hash
	   ref.	Example:

	   help	=> { oui => "French for	'yes'",	non => "French for 'no'"}

	   The key of help is used as a	regular	expression to find the help
	   text	applicable to a	value. These regexp are	tried from the longest
	   to the shortest and are matched from	the beginning of the string.
	   The key "".""  or "".*"" are	fallback used last.

	   For instance:

	    help => {
	      'foobar' => 'help	for values matching /^foobar/',
	      'foo' => 'help for values	matching /^foo/	but not	/^foobar/ (used	above)',
	      '.' => 'help for all other values'

   Value types
       This modules can	check several value types:

	   Accepts values 1 or 0, "yes"	or "no", "true"	or "false", and	empty
	   string. The value read back is always 1 or 0.

	   Enum	choices	must be	specified by the "choice" parameter.

	   Enable positive or negative integer

	   The value can be a decimal number

	   A one line string. I.e without "\n" in it.

	   Actually, no	check is performed with	this type.

	   Like	an "enum" where	the possible values (aka choice) is defined by
	   another location if the configuration tree. See "Value Reference".

	   A file name or path.	A warning is issued if the file	does not
	   exists (or is a directory)

	   A directory name or path. A warning is issued if the	directory does
	   not exists (or is a plain file)

Warp: dynamic value configuration
       The Warp	functionality enable a "Value" object to change	its properties
       (i.e. default value or its type)	dynamically according to the value of
       another "Value" object locate elsewhere in the configuration tree. (See
       Config::Model::Warper for an explanation	on warp	mechanism).

       For instance if you declare 2 "Value" element this way:

	$model ->create_config_class (
	    name => "TV_config_class",
	    element => [
		country	=> {
		    type => 'leaf',
		    value_type => 'enum',
		    choice => [qw/US Europe Japan/]
		} ,
		tv_standard => { # this	example	is getting old...
		    type => 'leaf',
		    value_type => 'enum',
		    choice => [	qw/PAL NTSC SECAM/ ]
		    warp => {
			follow => {
			    # this points to the warp master
			    c => '- country'
			rules => {
			    '$c	eq "US"' => {
				 default => 'NTSC'
			    '$c	eq "France"' =>	{
				 default => 'SECAM'
			    '$c	eq "Japan"' => {
				 default => 'NTSC'
			    '$c	eq "Europe"' =>	{
				 default => 'PAL'
		} ,

       Setting "country" element to "US" means that "tv_standard" has a
       default value set to "NTSC" by the warp mechanism.

       Likewise, the warp mechanism enables you	to dynamically change the
       possible	values of an enum element:

	state => {
	    type => 'leaf',
	    value_type => 'enum', # example is admittedly silly
	    warp => {
		follow => {
		    c => '- country'
		rules => {
		    '$c	eq "US"'	=> {
			 choice	=> ['Kansas', 'Texas' ]
		    '$c	eq "Europe"' =>	{
			 choice	=> ['France', 'Spain' ]
		    '$c	eq "Japan"' => {
			 choice	=> ['Honshu', 'Hokkaido' ]

   Cascaded warping
       Warping value can be cascaded: "A" can be warped	by "B" which can be
       warped by "C". But this feature should be avoided since it can lead to
       a model very hard to debug. Bear	in mind	that:

       o   Warp	loops are not detected and end up in "deep recursion
	   subroutine" failures.

       o   avoid "diamond" shaped warp dependencies: the results depends on
	   the order of	the warp algorithm which can be	unpredictable in this

       o   The keys declared in	the warp rules ("US", "Europe" and "Japan" in
	   the example above) cannot be	checked	at start time against the warp
	   master "Value". So a	wrong warp rule	key is silently	ignored	during
	   start up and	fails at run time.

Value Reference
       To set up an enumerated value where the possible	choice depends on the
       key of a	Config::Model::AnyId object, you must:

       o   Set "value_type" to "reference".

       o   Specify the "refer_to" or "computed_refer_to" parameter.  See
	   refer_to parameter.

       In this case, a "IdElementReference" object is created to handle	the
       relation	between	this value object and the referred Id. See
       Config::Model::IdElementReference for details.

Introspection methods
       The following methods returns the current value of the parameter	of the
       value object (as	declared in the	model unless they were warped):


       Returns the object name.

       Returns "leaf".

       Returns true if the value object	can be assigned	to. Return 0 for a
       read-only value (i.e. a computed	value with no override allowed).

       Query legal values (only	for enum types). Return	an array (possibly

       With a parameter, returns the help string applicable to the passed
       value or	undef.

       Without parameter returns a hash	ref that contains all the help

       Returns a list of information related to	the value, like	value type,
       default value. This should be used to provide some debug	information to
       the user.

       For instance, "$val-"get-info> may return:

	[ 'type: string', 'mandatory: yes' ]

       Returns the error messages of this object (if any)

       Returns warning concerning this value. Returns a	list in	list context
       and a string in scalar context.

       Parameters: "( value )"

       Check the consistency of	the value.

       "check_value" also accepts named	parameters:

	   When	non null, check	does not try to	get extra information from the
	   tree. This is required in some cases	to avoid loops in check,
	   get_info, get_warp_info, re-check ...

       In scalar context, return 0 or 1.

       In array	context, return	an empty array when no error was found.	In
       case of errors, returns an array	of error strings that should be	shown
       to the user.

       Returns the number of fixes that	can be applied to the current value.

       Applies the fixes to suppress the current warnings.

       Parameters: "( [	value => foo ] )"

       Like "check_value".

       Also displays warnings on STDOUT	unless "silent"	parameter is set to 1.
       In this case,user is expected to	retrieve them with "warning_msg".

       Without "value" argument, this method checks the	value currently

       Accept a	mode parameter.	This function checks if	the mode is accepted
       by "fetch" method. Returns an error message if not. For instance:

	if (my $err = $val->is_bad_mode('foo'))	{
	   croak "my_function: $err";

       This method is intented as a helper to avoid duplicating	the list of
       accepted	modes for functions that want to wrap fetch methods (like
       Config::Model::Dumper or	Config::Model::DumpAsData)

Information management
       Parameters: "( $value )"	or "value => ...,   check => yes|no|skip ),
       silent => 0|1"

       Store value in leaf element. "check" parameter can be used to skip
       validation check	(default is 'yes').  "silent" can be used to suppress

       Optional	"callback" is now deprecated.

       Clear the stored	value. Further read returns the	default	value (or
       computed	or migrated value).

       Parameters: "( $value )"

       Called with the same parameters are "store" method.

       Load scalar data. Data is forwarded to "store" after checking that the
       passed value is not a reference.

       Returns the stored value	if this	value is different from	a standard
       setting or built	in setting. In other words, returns undef if the
       stored value is identical to the	default	value or the computed value or
       the built in value.

       Returns the standard value as defined by	the configuration model. The
       standard	value can be either a preset value, a layered value, a
       computed	value, a default value or a built-in default value.

       Return true if the value	contains information different from default or
       upstream	default	value.

       Check and fetch value from leaf element.	The method can have one
       parameter (the fetch mode) or several pairs:

	   Whether to fetch default, custom, etc value.	See below for details

	   Whether to check if the value is valid or not before	returning it.
	   Default is 'yes'.  Possible value are

	   yes Perform check and raise an exception for	bad values

	       Perform check and return	undef for bad values. A	warning	is
	       issued when a bad value is skipped.  Set	"check"	to "no"	to
	       avoid warnings.

	   no  Do not check and	return values even if bad

	   When	set to 1, warning are not displayed on STDOUT. User is
	   expected to read warnings with warning_msg method.

       According to the	"mode" parameter, this method returns either:

       empty mode parameter (default)
	   Value entered by user or default value if the value is different
	   from	upstream_default or layered value. Typically this value	is
	   written in a	configuration file.

	   Alias for default mode.

	   The value entered by	the user (if different from built in, preset,
	   computed or default value)

	   The value most useful to user: the value that is used by the

	   The value entered in	preset mode

	   The preset or computed or default or	built in value.

	   The default value (defined by the configuration model)

	   The value found in included files (treated in layered mode: values
	   specified there are handled as upstream default values). E.g. like
	   in multistrap config.

	   The upstream_default	value. (defined	by the configuration model)

	   The custom or preset	or computed or default value. Returns undef if
	   either of this value	is identical to	the upstream_default value.
	   This	feature	is useful to reduce data to write in configuration

	   With	this mode, "fetch()" behaves like in "user" mode, but returns
	   "undef" for mandatory values. Normally, trying to fetch an
	   undefined mandatory value leads to an exception.

       Returns a truncated value when the value	is a string or uniline that is
       too long	to be displayed.

       Returns the value entered by the	user. Does not use the default or
       computed	value. Returns undef unless a value was	actually stored.

       Returns the value entered in preset mode. Does not use the default or
       computed	value. Returns undef unless a value was	actually stored	in
       preset mode.

       Delete the preset value.	(Even out of preset mode). Returns true	if
       other data are still stored in the value	(layered or user data).
       Returns false otherwise.

       Returns the value entered in layered mode. Does not use the default or
       computed	value. Returns undef unless a value was	actually stored	in
       layered mode.

       Delete the layered value. (Even out of layered mode). Returns true if
       other data are still stored in the value	(layered or user data).
       Returns false otherwise.

   get(	path =>	..., mode => ... ,    check => ... )
       Get a value from	a directory like path.

   set(	path , value )
       Set a value from	a directory like path.

   Number with min and max values
	bounded_number => {
	   type	      => 'leaf',
	   value_type => 'number',
	   min	      => 1,
	   max	      => 4,

   Mandatory value
	mandatory_string => {
	   type	      => 'leaf',
	   value_type => 'string',
	   mandatory  => 1,

	mandatory_boolean => {
	   type	      => 'leaf',
	   value_type => 'boolean',
	   mandatory  => 1,

   Enum	with help associated with each value
       Note that the help specification	is optional.

	enum_with_help => {
	   type	      => 'leaf',
	   value_type => 'enum',
	   choice     => [qw/a b c/],
	   help	      => {
	       a => 'a help'

   Migrate old obsolete	enum value
       Legacy values "a1", "c1"	and "foo/.*" are replaced with "a", "c"	and

	with_replace =>	{
	   type	      => 'leaf',
	   value_type => 'enum',
	   choice     => [qw/a b c/],
	   replace    => {
	       a1	=> 'a',
	       c1	=> 'c',
	       'foo/.*'	=> 'foo',

   Enforce value to match a regexp
       An exception is triggered when the value	does not match the "match"
       regular expression.

	match => {
	   type	      => 'leaf',
	   value_type => 'string',
	   match      => '^foo\d{2}$',

   Enforce value to match a Parse::RecDescent grammar
	match_with_parse_recdescent => {
	   type	      => 'leaf',
	   value_type => 'string',
	   grammar    => q{
	       token (oper token)(s?)
	       oper: 'and' | 'or'
	       token: 'Apache' | 'CC-BY' | 'Perl'

   Issue a warning if a	value matches a	regexp
       Issue a warning if the string contains upper case letters. Propose a
       fix that	translate all capital letters to lower case.

	warn_if_capital	=> {
	   type		 => 'leaf',
	   value_type	 => 'string',
	   warn_if_match => {
	       '/A-Z/' => {
		   fix => '$_ =	lc;'

       A specific warning can be specified:

	warn_if_capital	=> {
	   type		 => 'leaf',
	   value_type	 => 'string',
	   warn_if_match => {
	       '/A-Z/' => {
		   fix	=> '$_ = lc;',
		   mesg	=> 'NO UPPER CASE PLEASE'

   Issue a warning if a	value does NOT match a regexp
	warn_unless => {
	   type		     =>	'leaf',
	   value_type	     =>	'string',
	   warn_unless_match =>	{
	       foo => {
		   msg => '',
		   fix => '$_ =	"foo".$_;'

   Always issue	a warning
	always_warn => {
	   type	      => 'leaf',
	   value_type => 'string',
	   warn	      => 'Always warn whenever used',

   Computed values
       See "Examples" in Config::Model::ValueComputer.

       Upgrade is a special case when the configuration	of an application has
       changed.	Some parameters	can be removed and replaced by another one. To
       avoid trouble on	the application	user side, Config::Model offers	a
       possibility to handle the migration of configuration data through a
       special declaration in the configuration	model.

       This declaration	must:

       o   Declare the deprecated parameter with a "status" set	to

       o   Declare the new parameter with the instructions to load the
	   semantic content from the deprecated	parameter. These instructions
	   are declared	in the "migrate_from" parameters (which	is similar to
	   the "compute" parameter)

       Here an example where a URL parameter is	changed	to a set of 2
       parameters (host	and path):

	'old_url' => {
	   type	      => 'leaf',
	   value_type => 'uniline',
	   status     => 'deprecated',
	'host' => {
	   type	      => 'leaf',
	   value_type => 'uniline',

	   # the formula must end with '$1' so the result of the capture is used
	   # as	the host value
	   migrate_from	=> {
	       formula	 => '$old =~ m!http://([\w\.]+)!; $1 ;',
	       variables => {
		    old	=> '- old_url'
	       use_eval	 => 1,
	'path' => {
	   type		=> 'leaf',
	   value_type	=> 'uniline',
	   migrate_from	=> {
	       formula	 => '$old =~ m!http://[\w\.]+(/.*)!; $1	;',
	       variables => {
		    old	=> '- old_url'
	       use_eval	 => 1,

       When an error is	encountered, this module may throw the following

       Config::Model::Exception::Model Config::Model::Exception::Formula

       See Config::Model::Exception for	more details.

       Dominique Dumont, (ddumont at cpan dot org)

       Config::Model, Config::Model::Node, Config::Model::AnyId,
       Config::Model::Warper, Config::Model::Exception

       Dominique Dumont

       This software is	Copyright (c) 2005-2020	by Dominique Dumont.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

perl v5.32.0			  2020-08-28	       Config::Model::Value(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Default values | Constructor | Value model declaration | Warp: dynamic value configuration | Value Reference | Introspection methods | Information management | Examples | Upgrade | EXCEPTION HANDLING | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:

home | help