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

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::Warper(User Contributed Perl DocumentatConfig::Model::Warper(3)

NAME
       Config::Model::Warper - Warp tree properties

VERSION
       version 2.140

SYNOPSIS
	# internal class

DESCRIPTION
       Depending on the	value of a warp	master (In fact	a Config::Model::Value
       or a Config::Model::CheckList object), this class changes the
       properties of a node (Config::Model::WarpedNode), a hash
       (Config::Model::HashId),	a list (Config::Model::ListId),	a checklist
       (Config::Model::CheckList) or another value.

Warper and warped
       Warping an object means that the	properties of the object is changed
       depending on the	value of another object.

       The changed object is referred as the warped object.

       The other object	that holds the important value is referred as the warp
       master or the warper object.

       You can also set	up several warp	master for one warped object. This
       means that the properties of the	warped object is changed according to
       a combination of	values of the warp masters.

Warp arguments
       Warp arguments are passed in a hash ref whose keys are "follow" and and
       "rules":

   Warp	follow argument
       Grab string leading to the "Config::Model::Value" or
       Config::Model::CheckList	warp master. E.g.:

	follow => '! tree_macro'

       In case of several warp master, "follow"	is set to an array ref of
       several grab string:

	follow => [ '! macro1',	'- macro2' ]

       You can also use	named parameters:

	follow => { m1 => '! macro1', m2 => '- macro2' }

       Note: By	design "follow"	argument of warper module is a plain path to
       keep warp mechanism (relatively)	simple.	"follow" argument of
       Config::Model::ValueComputer has	more features and is documented	there

   Warp	rules argument
       String, hash ref	or array ref that specify the warped object property
       changes.	 These rules specifies the actual property changes for the
       warped object depending on the value(s) of the warp master(s).

       E.g. for	a simple case (rules is	a hash ref) :

	follow => '! macro1' ,
	rules => { A =>	{ <effect when macro1 is A> },
		   B =>	{ <effect when macro1 is B> }
		 }

       In case of similar effects, you can use named parameters	and a boolean
       expression to specify the effect. The first match is applied. In	this
       case, rules is a	list ref:

	 follow	=> { m => '! macro1' } ,
	 rules => [ '$m	eq "A"'		      => { <effect for macro1 == A> },
		    '$m	eq "B" or $m eq"C "'  => { <effect for macro1 == B|C > }
		  ]

       In case of several warp masters,	"follow" must use named	parameters,
       and rules must use boolean expression:

	follow => { m1 => '! macro1', m2 => '- macro2' } ,
	rules => [
		  '$m1 eq "A" && $m2 eq	"C"' =>	{ <effect for A	C> },
		  '$m1 eq "A" && $m2 eq	"D"' =>	{ <effect for A	D> },
		  '$m1 eq "B" && $m2 eq	"C"' =>	{ <effect for B	C> },
		  '$m1 eq "B" && $m2 eq	"D"' =>	{ <effect for B	D> },
		 ]

       Of course some combinations of warp master values can have the same
       effect:

	follow => { m1 => '! macro1', m2 => '- macro2' } ,
	rules => [
		  '$m1 eq "A" && $m2 eq	"C"' =>	{ <effect X> },
		  '$m1 eq "A" && $m2 eq	"D"' =>	{ <effect Y> },
		  '$m1 eq "B" && $m2 eq	"C"' =>	{ <effect Y> },
		  '$m1 eq "B" && $m2 eq	"D"' =>	{ <effect Y> },
		 ]

       In this case, you can use different boolean expression to save typing:

	follow => { m1 => '! macro1', m2 => '- macro2' } ,
	rules => [
		  '$m1 eq "A" && $m2 eq	"C"' =>	{ <effect X> },
		  '$m1 eq "A" && $m2 eq	"D"' =>	{ <effect Y> },
		  '$m1 eq "B" && ( $m2 eq "C" or $m2 eq	"D") ' => { <effect Y> },
		 ]

       Note that the boolean expression	is sanitized and used in a Perl	eval,
       so you can use most Perl	syntax and regular expressions.

       Functions (like &foo) are called	like "$self->foo" before evaluation of
       the boolean expression.

       The rules must be declared with a slightly different way	when a
       check_list is used as a warp master: a check_list has not a simple
       value. The rule must check whether a value is checked or	not amongs all
       the possible items of a check list.

       For example, let's say that $cl in the rule below point to a check list
       whose items are "A" and "B". The	rule must verify if the	item is	set or
       not:

	 rules => [
	      '$cl.is_set(A)' =>  { <effect when A is set> },
	      '$cl.is_set(B)' =>  { <effect when B is set> },
	      #	can be combined
	      '$cl.is_set(B) and $cl.is_set(A)'	=>  { <effect when A and B are set> },
	  ],

       With this feature, you can control with a check list whether some
       element must be shown or	not (assuming "FooClass" and "BarClass"
       classes are declared):

	   element => [
	       # warp master
	       my_check_list =>	{
		   type	      => 'check_list',
		   choice     => ['has_foo','has_bar']
	       },
	       # controlled element that show up only when has_foo is set
	       foo => {
		   type	=> 'warped_node',
		   level => 'hidden',
		   config_class_name =>	'FooClass',
		   follow => {
		       selected	=> '- my_check_list'
		   },
		   'rules' => [
		       '$selected.is_set(has_foo)' => {
			   level => 'normal'
		       }
		   ]
	       },
	       # controlled element that show up only when has_bar is set
	       bar => {
		   type	=> 'warped_node',
		   level => 'hidden',
		   config_class_name =>	'BarClass',
		   follow => {
		       selected	=> '- my_check_list'
		   },
		   'rules' => [
		       '$selected.is_set(has_bar)' => {
			   level => 'normal'
		       }
		   ]
	       }
	   ]

Methods
   warp_error
       This method returns a string describing:

       o   The location(s) of the warp master

       o   The current value(s)	of the warp master(s)

       o   The other values accepted by	the warp master	that can be tried (if
	   the warp master is an enumerated type)

How does this work ?
       Registration
	   o   When a warped object is created,	the constructor	registers to
	       the warp	masters. The warp master are found by using the
	       special string passed to	the "follow" parameter.	As explained
	       in grab method, the string provides the location	of the warp
	       master in the configuration tree	using a	symbolic form.

	   o   Then the	warped object retrieve the value(s) of the warp
	       master(s)

	   o   Then the	warped object warps itself using the above value(s).
	       Depending on these value(s), the	properties of the warped
	       object are modified.

       Master update
	   o   When a warp master value	is updated, the	warp master calls all
	       its warped object and pass them the new master value.

	   o   Then each warped	object modifies	properties according to	the
	       new warp	master value.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO
       Config::Model::AnyThing,	Config::Model::HashId, Config::Model::ListId,
       Config::Model::WarpedNode, 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::Warper(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Warper and warped | Warp arguments | Methods | How does this work ? | 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::Warper&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help