Config::Model::Warper - Warp tree properties

       Dominique Dumont

       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

perl v5.40.0                                       2024-11-30                         Config::Model::Warper(3pm)

       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.

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

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

           •   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
           •   When a warp master value is updated, the warp master calls all its warped object  and  pass  them
               the new master value.

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

warp_error
       This method returns a string describing:

       •   The location(s) of the warp master

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

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

       Config::Model::Warper - Warp tree properties

       Config::Model::AnyThing,    Config::Model::HashId,    Config::Model::ListId,   Config::Model::WarpedNode,
       Config::Model::Value

        # internal class

       version 2.155

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

   Warpfollowargument
       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

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

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