Provided by: libconfig-model-perl_2.153-3_all bug

NAME

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

VERSION

       version 2.153

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

   Value types
       This modules can check several value types:

       "boolean"
           Accepts values 1 or 0, "yes" or "no", "true" or "false", and empty string. 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 is issued if the file does not exists (or is a
           directory)

       "dir"
           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:

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

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

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

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

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

   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
       Parameters: "( value )"

       Check the consistency of the value.

       "check_value" also accepts named parameters:

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

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

   is_bad_mode
       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

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

       Optional "callback" is now deprecated.

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

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

   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.

   has_data
       Return true if the value contains information different from default or upstream 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. 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 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.

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

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

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

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

       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