NAME¶

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

VERSION¶

version 2.155

SYNOPSIS¶

 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

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 is written in the target configuration file. ("default" parameter)
• 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)
• mandatory value: reading a mandatory value raises an exception if the value is not specified (i.e is "undef" or empty string) 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 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 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", "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

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.

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

warn_if_match

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 uppercase:

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

warn_unless_match

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.

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 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'
     }
    

warn_unless

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

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

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

assert

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.

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 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]}}".

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

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'"}

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'
 }
    

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' ]
             }
         }
     }
 }

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

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

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

Information management¶

Examples¶

 bounded_number => {
    type       => 'leaf',
    value_type => 'number',
    min        => 1,
    max        => 4,
 },

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

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

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

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

 match_with_parse_recdescent => {
    type       => 'leaf',
    value_type => 'string',
    grammar    => q{
        token (oper token)(s?)
        oper: 'and' | 'or'
        token: 'Apache' | 'CC-BY' | 'Perl'
    },
 },

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

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

 warn_unless => {
    type              => 'leaf',
    value_type        => 'string',
    warn_unless_match => {
        foo => {
            msg => '',
            fix => '$_ = "foo".$_;'
        }
    },
 },

 always_warn => {
    type       => 'leaf',
    value_type => 'string',
    warn       => 'Always warn whenever used',
 },

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

AUTHOR¶

Dominique Dumont

COPYRIGHT AND LICENSE¶

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

This is free software, licensed under:

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