Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::ValueCoUsereContributed Perl DocConfig::Model::ValueComputer(3)

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

VERSION
       version 2.140

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:

       o   A string formula that use variables and replace function.

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

       o   An optional set of replace rules.

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

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

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

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

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

       o   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,
	    },
	},

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

	   '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-2020	by Dominique Dumont.

       This is free software, licensed under:

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

perl v5.32.0			  2020-08-28   Config::Model::ValueComputer(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Computed value declaration | Examples | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::ValueComputer&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help