trusty (3) Config::Model::Value.3pm.gz
NAME
Config::Model::Value - Strongly typed configuration value
VERSION
version 2.047
SYNOPSIS
use Config::Model;
use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($WARN);
# 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( step => 'foo=FOO country=US' );
print $root->report ;
# foo = FOO
# DESCRIPTION: foobar
#
# country = US
# DESCRIPTION: big countries
DESCRIPTION
This class provides a way to specify configuration value with the following properties:
• Strongly typed scalar: the value can either be an enumerated type, a boolean, a number, an integer or
a string
• default parameter: a value can have a default value specified during the construction. This default
value will be written in the target configuration file. ("default" parameter)
• upstream default parameter: specifies a default value that will be used by the application when no
information is provided in the configuration file. This upstream_default value will not written in
the configuration files. Only the "fetch_standard" method will return the builtin value. This
parameter was previously referred as "built_in" value. This may be used for audit purpose.
("upstream_default" parameter)
• mandatory value: reading a mandatory value will raise an exception if the value is not specified and
has no default value.
• 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'.
• 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":
• "upstream_default": The value is known in the application, but is not written in the configuration
file.
• "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.
• "default": The value is known by the model, but not by the application. This value must be written in
the configuration file.
• "computed": The value is computed from other configuration elements. This value must be written in
the configuration file.
• "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 will override all kind of "default" value.
The fetch_standard function will return the "highest" level of default value, but will not return a
custom value, i.e. a value entered by the user.
Constructor
Value object should not be created directly.
Value model declaration
A leaf element must be declared with the following parameters:
value_type
Either "boolean", "enum", "integer", "number", "uniline", "string". Mandatory. See "Value types".
default
Specify the default value (optional)
upstream_default
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.
write_as
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
"['no','yes']".
compute
Will compute 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.
migrate_from
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 will be converted to uppercase (uc) or lowercase (lc).
min Specify the minimum value (optional, only for integer, number)
max Specify the maximum value (optional, only for integer, number)
mandatory
Set to 1 if the configuration value must be set by the configuration user (default: 0)
choice
Array ref of the possible value of an enum. Example :
choice => [ qw/foo bar/]
match
Perl regular expression. The value will be match 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.
warn_if_match
Hash ref. Keys are made of Perl regular expression. The value can specify a warning message (leave
empty or undefined for default warning message) and instructions to fix the value. A warning will be
issued when the value match the passed regular expression. Valid only for "string" or "uniline"
values. The fix instructions will be evaluated when apply_fixes is called. $_ will contain the value
to fix. $_ will be stored as the new value once the instructions are done. $self will contain the
value object. Use with care.
In the example below, any value matching 'foo' will be converted in uppercase:
warn_if_match => { 'foo' => { fix =>'uc;', msg => 'lower foo is not good'}},
warn_unless_match
Hash ref like above. A warning will be issued when the value does not match the passed regular
expression. Valid only for "string" or "uniline" values.
warn
String. Issue a warning to user with the specified string any time a value is set or read.
warn_unless
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 will be issued if the code
returns false.
$_ will contains the value to check. $self will contain the "Config::Model::Value" object.
The example below will warn if a directory is missing:
warn_unless => { 'dir' => { code => '-d' , msg => 'missing dir', fix => "system(mkdir $_);" }}
assert
Like "warn_if_match". Except that returned value will trigger an error if false.
grammar
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 will be modified to add "check" rule and set up this rules 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'
will be 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]}}".
replace
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 will need to 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 will be replaced by "better_foo" if the "/^foo.*$/" regexp matches.
replace_follow
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.
refer_to
Specify a path to an id element used as a reference. See Value Reference for details.
computed_refer_to
Specify a path to an id element used as a computed reference. See "Value Reference" for details.
warp
See section below: "Warp: dynamic value configuration".
help
You may provide detailed description on possible values with a hash ref. Example:
help => { oui => "French for 'yes'", non => "French for 'no'"}
Value types
This modules can check several value types:
"boolean"
Accepts values 1 or 0, "yes" or "no", "true" or "false". The value read back is always 1 or 0.
"enum"
Enum choices must be specified by the "choice" parameter.
"integer"
Enable positive or negative integer
"number"
The value can be a decimal number
"uniline"
A one line string. I.e without "\n" in it.
"string"
Actually, no check is performed with this type.
"reference"
Like an "enum" where the possible values (aka choice) is defined by another location if the
configuration tree. See "Value Reference".
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 => {
type => 'leaf',
value_type => 'enum',
choice => [qw/PAL NTSC SECAM/]
warp => {
follow => { c => '- country' }, # this points to the warp master
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" will mean 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:
• Warp loop are not detected and will end up in "deep recursion subroutine" failures.
• If you declare "diamond" shaped warp dependencies, the results will depend on the order of the warp
algorithm and can be unpredictable.
• 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 will be silently
ignored during start up and will fail 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:
• Set "value_type" to "reference".
• 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):
min
max
mandatory
choice
convert
value_type
default
upstream_default
index_value
element_name
name()
Returns the object name.
get_type
Returns "leaf".
can_store()
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).
get_choice()
Query legal values (only for enum types). Return an array (possibly empty).
get_help ( [ on_value ] )
Returns the help strings passed to the constructor.
With "on_value" parameter, returns the help string dedicated to the passed value or undef.
Without parameter returns a hash ref that contains all the help strings.
error_msg
Returns the error messages of this object (if any)
warning_msg
Returns warning concerning this value. Returns a list in list context and a string in scalar context.
check_value ( value )
Check the consistency of the value.
"check_value" also accepts named parameters:
value
quiet
When non null, check will 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.
has_fixes
Returns the number of fixes that can be applied to the current value.
apply_fixes
Applies the fixes to suppress the current warnings.
check( [ value => foo ] )
Like "check_value".
Will also display 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 will check the value currently stored.
Information management
store( value )
Can be called as "value => ..., check => yes|no|skip, callback => sub {...} )"
Store value in leaf element. "check" parameter can be used to skip validation check.
Optional "callback" is called when store check is done with these named parameters: "value check
notify_change ok".
load_data( scalar_value )
Load scalar data. Data is simply forwarded to store.
fetch_custom
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.
fetch_standard
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.
fetch( ... )
Check and fetch value from leaf element. The method can have one parameter (the fetch mode) or several
pairs:
mode
Whether to fetch default, custom, etc value. See below for details
check
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
skip
Perform check and return undef for bad values
no Do not check and return values even if bad
silent
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 will return 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 will be written in a configuration file.
backend
Alias for default mode.
custom
The value entered by the user (if different from built in, preset, computed or default value)
user
The value most useful to user: the value that will be used by the application.
preset
The value entered in preset mode
standard
The preset or computed or default or built in value.
default
The default value (defined by the configuration model)
layered
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.
upstream_default
The upstream_default value. (defined by the configuration model)
non_upstream_default
The custom or preset or computed or default value. Will return undef if either of this value is
identical to the upstream_default value. This feature is useful to reduce data to write in
configuration file.
allow_undef
This mode will accept to return undef for mandatory values. Normally, trying to fetch an undefined
mandatory value leads to an exception.
user_value
Returns the value entered by the user. Does not use the default or computed value. Returns undef unless a
value was actually stored.
fetch_preset
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.
clear_preset
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.
fetch_layered
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.
clear_layered
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.
Examples
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',
},
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 "foo/".
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 will be triggered if 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
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:
• Declare the deprecated parameter with a "status" set to "deprecated"
• 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 ,
},
},
EXCEPTION HANDLING
When an error is encountered, this module may throw the following exceptions:
Config::Model::Exception::Model
Config::Model::Exception::Formula
Config::Model::Exception::WrongValue
Config::Model::Exception::WarpError
See Config::Model::Exception for more details.
AUTHOR
Dominique Dumont, (ddumont at cpan dot org)
SEE ALSO
Config::Model, Config::Model::Node, Config::Model::AnyId, Config::Model::Warper, Exception::Class
Config::Model::ValueComputer,
AUTHOR
Dominique Dumont
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999