Dominique Dumont > Config-Model-2.059 > Config::Model::ValueComputer

Download:
Config-Model-2.059.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  1
View/Report Bugs
Module Version: 2.059   Source   Latest Release: Config-Model-2.061

NAME ^

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

VERSION ^

version 2.059

SYNOPSIS ^

 use Config::Model;
 use Log::Log4perl qw(:easy);
 Log::Log4perl->easy_init($WARN);

 # 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( step => '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:

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:

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 will be 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

The following arguments will be a set of key => value to define the variables used in the formula. The key is a variable name used in the computation string. The value is a string that will be 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.

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 will be 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 will yield an undefined value if one variable is undefined.

You may change this behavior with undef_is parameter. Depending on your formula and whether use_eval is true or not, you may specify a "fallback" value that will be used in your formula.

The most useful will probably be:

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

Example:

        Source => {
            value_type   => 'string',
            mandatory    => 1,
            migrate_from => {
                use_eval  => 1,
                formula   => '$old || $older ;',
                undef_is => "''",
                variables => {
                    older => '- Original-Source-Location',
                    old   => '- Upstream-Source'
                }
            },
            type => 'leaf',
        },
        [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) 2014 by Dominique Dumont.

This is free software, licensed under:

  The GNU Lesser General Public License, Version 2.1, February 1999
syntax highlighting: