Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CONFIG::MODEL::VALUE (3)

.ds Aq ’


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



version 2.082


 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( step => 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 will be written in the target configuration file. (default parameter)
o 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)
o mandatory value: reading a mandatory value will raise 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 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.


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, file, dir. 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 <B>mustB> 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 =>  value $_ contains foo
   BAR => {
        fix =>lc;,
        msg =>  value $_ contains BAR

The tests will be done in alphabetical order. In the example above, BAR test will be done before foo test.

$_ will be substituted with the bad value when the message is generated.

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_if 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 true.

$_ will contains the value to check. $self will contain the Config::Model::Value object.

The example below will warn if value contaims a number:

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

warn_unless Like warn_if, but issue a warning when the code returns false.

The example below will warn unless the value points to an existing directory:

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

assert Like warn_if. Except that returned value will trigger an error if false:

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

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.
file A file name or path. A warning will be issued if the file does not exists (or is a directory)
dir A directory name or path. A warning will be 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 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:
o Warp loop are not detected and will end up in deep recursion subroutine failures.
o If you declare diamond shaped warp dependencies, the results will depend on the order of the warp algorithm and can be unpredictable.
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 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:
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 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.


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.

    check_value ( value )

Check the consistency of the value.

check_value also accepts named parameters:
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.


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


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( CW$value )

Can be called as value => ...,  check => yes|no|skip ), silent => 0|1

Store value in leaf element. check parameter can be used to skip validation check (default ies ’yes’). silent cane be used to suppress warnings.

Optional callback is now deprecated.


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

load_data( CW$value )

Load scalar data. Data is forwarded to store( $value ).

Called with load_data( $value ) or load_data( data = $value )> or with the same parameters are store method.


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.


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. 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
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.


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 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 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 deprecated
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 exceptions:

Config::Model::Exception::Model Config::Model::Exception::Formula Config::Model::Exception::WrongValue Config::Model::Exception::WarpError

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 Config::Model::ValueComputer,


Dominique Dumont


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

This is free software, licensed under:

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

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 CONFIG::MODEL::VALUE (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.