NAME

       Config::Model::Warper - Warp tree properties

VERSION

       version 2.047

SYNOPSIS

        # internal class

DESCRIPTION

       Depending on the value of a warp master (In fact a Config::Model::Value object), this
       class will change 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 will be 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 will be 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" warp master. E.g.:

        follow => '! tree_macro'

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

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

       You can also use named parameters:

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

   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 for macro1 == A> },
                   B => { <effect for macro1 == B> }
                 }

       In case of similar effects, you can use named parameters and a boolean expression to
       specify the effect. The first match will be 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 will be sanitized and used in a Perl eval, so you can use
       most Perl syntax and regular expressions.

       Function (like &foo) will be called like "$self->foo" before evaluation\ of the boolean
       expression.

Methods

   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)

How does this work ?

       Registration
           •   When a warped object is created, the constructor will register 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 will be modified.

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

           •   Then each warped object will modify its 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) 2013 by Dominique Dumont.

       This is free software, licensed under:

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