Provided by: libconfig-model-perl_2.133-1_all bug

NAME

       Config::Model::ValueComputer - Provides configuration value computation

VERSION

       version 2.133

SYNOPSIS

        use Config::Model;

        # define configuration tree object
        my $model = Config::Model->new;
        $model ->create_config_class (
           name => "MyClass",

           element => [
              [qw/av bv/] => {
                  type => 'leaf',
                  value_type => 'integer',
              },
              compute_int => {
                      type => 'leaf',
                      value_type => 'integer',
                      compute    => {
                          formula   => '$a + $b',
                          variables => { a => '- av', b => '- bv'}
                      },
              },
           ],
        );

        my $inst = $model->instance(root_class_name => 'MyClass' );

        my $root = $inst->config_root ;

        # put data
        $root->load( steps => 'av=33 bv=9' );

        print "Computed value is ",$root->grab_value('compute_int'),"\n";
        # Computed value is 42

DESCRIPTION

       This class provides a way to compute a configuration value. This computation uses a
       formula and some other configuration values from the configuration tree.

       The computed value can be overridden, in other words, the computed value can be used as a
       default value.

Computed value declaration

       A computed value must be declared in a 'leaf' element. The leaf element must have a
       "compute" argument pointing to a hash ref.

       This array ref contains:

       ·   A string formula that use variables and replace function.

       ·   A set of variable and their relative location in the tree (using the notation
           explained in grab method

       ·   An optional set of replace rules.

       ·   An optional parameter to force a Perl eval of a string.

       Note: A variable must point to a valid location in the configuration tree. Even when
       "&index()" or $replace{} is used. After substitution of these functions, the string is
       used as a path (See grab) starting from the computed value. Hence the path must begin with
       "!" to go back to root node, or "-" to go up a level.

   Compute formula
       The first element of the "compute" array ref must be a string that contains the
       computation algorithm (i.e. a formula for arithmetic computation for integer values or a
       string template for string values).

       This string or formula should contain variables (like $foo or $bar). Note that these
       variables are not interpolated by Perl.

       For instance:

         'My cat has $nb legs'
         '$m * $c**2'

       This string or formula may also contain:

       ·   The index value of the current object : &index or "&index()".

       ·   The index value of a parent object: "&index(-)". Ancestor index value can be retrieved
           with "&index(-2)" or "&index(-3)" or "&index(- -)" or "&index(- - -)"

       ·   The element name of the current object: &element or "&element()".

       ·   The element name of a parent object: "&element(-)". Likewise, ancestor element name
           can be retrieved with "&element(-2)" or "&element(-3)".

       ·   The full location (path) of the current object: &location or "&location()".

       For instance, you could have this template string:

          'my element is &element, my index is &index' .
           'upper element is &element(-), upper index is &index(-)',

       If you need to perform more complex operations than substitution, like extraction with
       regular expressions, you can force an eval done by Perl with "use_eval => 1". In this
       case, the result of the eval is used as the computed value.

       For instance:

         # extract host from url
         compute => {
             formula => '$old =~ m!http://[\w\.]+(?::\d+)?(/.*)!; $1 ;',
             variables => { old => '- url' } ,
                 use_eval => 1 ,
         },

         # capitalize
         compute => {
             formula => 'uc($old)',
                 variables => { old => '- small_caps' } ,
                 use_eval => 1
         }

   Compute variables
       Compute variables are a set of "key => value" pairs that define the variables used in the
       specified formula. The key is a variable name used in the string that represents the
       formula. The value is a string that is used to get the correct Value object.

       In this numeric example, "result" default value is "av + bv":

        element => [
           av => {
               type => 'leaf',
               value_type => 'integer'
           },
           bv => {
               type => 'leaf',
               value_type => 'integer'
           },
           result => {
               type => 'leaf',
               value_type => 'integer',
               compute => {
                   formula => '$a + $b' ,
                   variables => { a => '- av', b => '- bv' },
               }
           }
        ]

       In this string example, the default value of the "Comp" element is actually a string made
       of ""macro is "" and the value of the ""macro"" element of the object located 2 nodes
       above:

        comp => {
           type => 'leaf',
           value_type => 'string',
           compute => {
               formula => '"macro is $m"' ,
               variables => { m => '- - macro' }
           }
        }

   Compute replace
       Sometime, using the value of a tree leaf is not enough and you need to substitute a
       replacement for any value you can get. This replacement can be done using a hash like
       notation within the formula using the %replace hash.

       For instance, if you want to display a summary of a config, you can do :

        compute_with_replace => {
            formula => '$replace{$who} is the $replace{$what} of $replace{$country}',
            variables => {
                who   => '! who' ,
                what  => '! what' ,
                country => '- country',
            },
            replace => {
                chief => 'president',
                America => 'USA'
            }
        }

   Complex formula
       &index, &element, and replace can be combined. But the argument of &element or &index can
       only be a value object specification (I.e. something like '"- - foo"'), it cannot be a
       value replacement of another &element or &index.

       I.e. "&element($foo)" is ok, but "&element(&index($foo))" is not allowed.

   computed variable
       Compute variables can themselves be computed :

        compute => {
           formula => 'get_element is $replace{$s}, indirect value is \'$v\'',
           variables => {
               s => '! $where',
               where => '! where_is_element',
               v => '! $replace{$s}',
           }
           replace => {
               m_value_element => 'm_value',
               compute_element => 'compute'
           }
        }

       Be sure not to specify a loop when doing recursive computation.

       The function &index &element and &location are also allowed.

   compute override
       In some case, a computed value must be interpreted as a default value and the user must be
       able to override this computed default value.  In this case, you must use "allow_override
       => 1" with the compute parameter:

        computed_value_with_override => {
           type => 'leaf',
           value_type => 'string',
           compute => {
               formula => '"macro is $m"' ,
               variables => { m => '- - macro' } ,
               allow_override => 1,
           }
        }

       This computed default value is written to the configuration file.

       This default value may be already known by the application so the computed value should
       not be written to the configuration file. The computed value is interesting because it cab
       be shown to the user. In this case, use the "use_as_upstream_default" parameter:

        compute_known_upstream => {
           type => 'leaf',
           value_type => 'string',
           compute => {
               formula => '"macro is $m"' ,
               variables => { m => '- - macro' } ,
               use_as_upstream_default => 1,
           }
        }

       "use_as_upstream_default" implies "allow_override".

   Undefined variables
       You may need to compute value where one of the variables (i.e. other configuration
       parameter) is undefined. By default, any formula yields an undefined value if one variable
       is undefined.

       You may change this behavior with "undef_is" parameter. With this parameter, you can
       specify a "fallback" value that is used in your formula instead of an undefined variable.

       The most useful fallback values are:

        undef_is => "''", # for string values
        undef_is => 0   , # for integers, boolean values

       Example:

        Source => {
           type => 'leaf',
           value_type   => 'string',
           mandatory    => 1,
           migrate_from => {
               use_eval  => 1,
               formula   => '$old || $older ;',
               undef_is => "''",
               variables => {
                   older => '- Original-Source-Location',
                   old   => '- Upstream-Source'
               }
           },
        },
        [qw/Upstream-Source Original-Source-Location/] => {
           value_type => 'string',
           status     => 'deprecated',
           type       => 'leaf'
        }

Examples

   String substitution
        [qw/sav sbv/] => {
            type       => 'leaf',
            value_type => 'string',
          },
        compute_string => {
            type       => 'leaf',
            value_type => 'string',
            compute    => {
                formula   => 'meet $a and $b',
                variables => { '- sav', b => '- sbv' }
            },
        },

   Computation with on-the-fly replacement
        compute_with_replace => {
            type       => 'leaf',
            value_type => 'string',
            compute    => {
                formula =>
                  '$replace{$who} is the $replace{$what} of $replace{$country}',
                variables => {
                    who     => '! who',
                    what    => '! what',
                    country => '- country',
                },
                replace => {
                    chief   => 'president',
                    America => 'USA'
                },
            },
          },

   Extract data from a value using a Perl regexp
       Extract the host name from an URL:

        url => {
            type       => 'leaf',
            value_type => 'uniline'
        },
        extract_host_from_url => {
            type       => 'leaf',
            value_type => 'uniline',
            compute    => {
                formula   => '$old =~ m!http://([\w\.]+)!; $1 ;',
                variables => { old => '- url' },
                use_eval  => 1,
            },
        },

   simple copy hash example
       Copying a hash may not be useful, but the using "&index()" in a variable can be. Here's an
       example where the hashes contain leaves.

       The model is set up so that the content of "copy_from" is copied into "copy_to" hash:

               copy_from => {
                   'type' => 'hash',
                   'index_type' => 'string',
                   'cargo' => {
                       'config_class_name' => 'From',
                       'type' => 'node'
                   },
               },
               copy_to => {
                   'type' => 'hash',
                   'index_type' => 'string',
                   'cargo' => {
                       'type' => 'leaf',
                       'value_type' => 'uniline',
                       'compute' => {
                           'formula' => '$copied',
                           'variables' => {
                               'copied' => '- copy_from:&index()'
                           }
                       },
                   },
               },

       Hash copy is also possible when the hash contains node. Here's an example where the data
       to be copied is stored within a node. The main class has 2 hash elements:

               copy_from => {
                   'type' => 'hash',
                   'index_type' => 'string',
                   'cargo' => {
                       'config_class_name' => 'From',
                       'type' => 'node'
                   },
               },
               copy_to => {
                   'type' => 'hash',
                   'index_type' => 'string',
                   'cargo' => {
                       'config_class_name' => 'To',
                       'type' => 'node'
                   },
               },

       The Class to copy from is quite simple:

           'name' => 'From',
           'element' => [
               name =>  {
                   'type' => 'leaf',
                   'value_type' => 'uniline',
               }
           ]

       Here the class to copy to:

           'name' => 'To',
           'element' => [
               name =>  {
                   'type' => 'leaf',
                   'value_type' => 'uniline',
                   'compute' => {
                       'formula' => '$copied',
                       'variables' => {
                           'copied' => '! copy_from:&index(-) name'
                       }
                   },
               }
           ]

AUTHOR

       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

       Config::Model, Config::Model::Instance, Config::Model::Value

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

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

       This is free software, licensed under:

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