NAME
Config::Model::Value - Strongly typed configuration value
SYNOPSIS
my $model = Config::Model->new() ;
$model ->create_config_class
(
name => "SomeClass",
element => [
country => { type => 'leaf',
value_type => 'enum',
choice => [qw/France US/]
},
president => { type => 'leaf',
value_type => 'string',
warp => [ '- country',
France => { default => 'Chirac' },
US => { default => 'Bush' }]
},
]
);
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.
built-in default parameter: specifies the default value that is built in the application to be configured. This built-in default value will not written in the configuration files. Only the
fetch_standard
method will return the built-in default value. This may be used for audit purpose.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".
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
,enum_integer
,number
,string
. Mandatory. See "Value types". - default
-
Specify the default value (optional)
- built_in
-
Specify a built in default value (optional)
- 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.
- 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 or enum_integer)
- max
-
Specify the maximum value (optional, only for integer, number or enum_integer)
- 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/]
- refer_to
-
See "Value reference".
- warp
-
See section below: </"Warp: dynamic value configuration">.
- help
-
You may provide detailed description on possible values of this tied scalar 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
or0
,yes
orno
,true
orfalse
. The value read back is always1
or0
. enum
-
Enum choices must be specified by the
choice
parameter. integer
-
Enable positive or negative integer
enum_integer
-
enum_integer
authorise the value to be an integer or a value specified by thechoice
parameter. This type is used to specify a value which can be an integer or be disabled. number
-
The value can be a decimal number
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::WarpedThing 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 => '- country', # this points to the warp master
rules => { US => { default => 'NTSC' },
France => { default => 'SECAM' },
Japan => { default => 'NTSC' },
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 => '- country',
rules => { US => { choice => ['Kansas', 'Texas' ]},
Europe => { choice => ['France', 'Spain' ]},
Japan => { choice => ['Honshu', 'Hokkaido' ]}
}
]
}
Note that the state
element is not available while country
is undefined.
As syntactic sugar, similar rules can be grouped within an array ref instead of a hash ref. I.e., you can specify
rules => [
[qw/UK Germany Italy/] => { default => 'PAL' },
US => { default => 'NTSC' },
]
instead of : rules => { UK => { default => 'PAL' }, Germany => { default => 'PAL' }, Italy => { default => 'PAL' }, US => { default => 'NTSC' }, }
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
andJapan
in the example above) cannot be checked at start time against the warp masterValue
. 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
.
When value_type
is a reference, you must also set the refer_to
parameter.
The first argument of
refer_to
points to an array or hash element in the configuration tree using the path syntax (See "grab" in Config::Model::Node for details). This path is treated like a computaion formula. Hence it can contain variable and substitution like a computation formula.The following arguments of
refer_to
define the variable used in the path formula.The available choice of this reference value is made from the available keys of the refered_to hash element or the range of the refered_to array element.
The example means the the value must correspond to an existing host:
value_type => 'reference',
refer_to => '! host'
This example means the the value must correspond to an existing lan within the host whose Id is specified by hostname:
value_type => 'reference',
refer_to => ['! host:$a lan', a => '- hostname' ]
If you need to combine possibilities from several hash, use the "+
" token to separate 2 paths:
value_type => 'reference',
refer_to => ['! host:$a lan + ! host:foobar lan',
a => '- hostname' ]
You can specify refer_to
with a choice
argument so the possible enum value will be the combination of the specified choice and the refered_to values.
Value reference example
## FIXME: get an example...
Introspection methods
The following methods returns the current value of the Id object (as declared in the model unless they were warped):
- min
- max
- mandatory
- choice
- convert
- value_type
- default
- built_in
- 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.
Information management
store( value )
Store value in leaf element.
fetch_custom
Returns the stored value if this value is different from a standard setting. In other words, returns undef if the stored value is identical to the default value or the computed value.
fetch_standard
Returns the standard value as defined by the configuration model. The standard value can be either a computed value, a default value or a built-in default value.
fetch()
Fetch value from leaf element
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.
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, domi@komarr.grenoble.hp.com
SEE ALSO
Config::Model, Config::Model::Node, Config::Model::AnyId, Config::Model::WarpedThing, Exception::Class