Config::Model::Warper(3pm)

1Config::Model::Warper(3U)ser Contributed Perl DocumentatiCoonnfig::Model::Warper(3)
2
3
4

NAME

6       Config::Model::Warper - Warp tree properties
7

VERSION

9       version 2.136
10

SYNOPSIS

12        # internal class
13

DESCRIPTION

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

Warper and warped

22       Warping an object means that the properties of the object is changed
23       depending on the value of another object.
24
25       The changed object is referred as the warped object.
26
27       The other object that holds the important value is referred as the warp
28       master or the warper object.
29
30       You can also set up several warp master for one warped object. This
31       means that the properties of the warped object is changed according to
32       a combination of values of the warp masters.
33

Warp arguments

35       Warp arguments are passed in a hash ref whose keys are "follow" and and
36       "rules":
37
38   Warp follow argument
39       Grab string leading to the "Config::Model::Value" or
40       Config::Model::CheckList warp master. E.g.:
41
42        follow => '! tree_macro'
43
44       In case of several warp master, "follow" is set to an array ref of
45       several grab string:
46
47        follow => [ '! macro1', '- macro2' ]
48
49       You can also use named parameters:
50
51        follow => { m1 => '! macro1', m2 => '- macro2' }
52
53       Note: By design "follow" argument of warper module is a plain path to
54       keep warp mechanism (relatively) simple. "follow" argument of
55       Config::Model::ValueComputer has more features and is documented there
56
57   Warp rules argument
58       String, hash ref or array ref that specify the warped object property
59       changes.  These rules specifies the actual property changes for the
60       warped object depending on the value(s) of the warp master(s).
61
62       E.g. for a simple case (rules is a hash ref) :
63
64        follow => '! macro1' ,
65        rules => { A => { <effect when macro1 is A> },
66                   B => { <effect when macro1 is B> }
67                 }
68
69       In case of similar effects, you can use named parameters and a boolean
70       expression to specify the effect. The first match is applied. In this
71       case, rules is a list ref:
72
73         follow => { m => '! macro1' } ,
74         rules => [ '$m eq "A"'               => { <effect for macro1 == A> },
75                    '$m eq "B" or $m eq"C "'  => { <effect for macro1 == B|C > }
76                  ]
77
78       In case of several warp masters, "follow" must use named parameters,
79       and rules must use boolean expression:
80
81        follow => { m1 => '! macro1', m2 => '- macro2' } ,
82        rules => [
83                  '$m1 eq "A" && $m2 eq "C"' => { <effect for A C> },
84                  '$m1 eq "A" && $m2 eq "D"' => { <effect for A D> },
85                  '$m1 eq "B" && $m2 eq "C"' => { <effect for B C> },
86                  '$m1 eq "B" && $m2 eq "D"' => { <effect for B D> },
87                 ]
88
89       Of course some combinations of warp master values can have the same
90       effect:
91
92        follow => { m1 => '! macro1', m2 => '- macro2' } ,
93        rules => [
94                  '$m1 eq "A" && $m2 eq "C"' => { <effect X> },
95                  '$m1 eq "A" && $m2 eq "D"' => { <effect Y> },
96                  '$m1 eq "B" && $m2 eq "C"' => { <effect Y> },
97                  '$m1 eq "B" && $m2 eq "D"' => { <effect Y> },
98                 ]
99
100       In this case, you can use different boolean expression to save typing:
101
102        follow => { m1 => '! macro1', m2 => '- macro2' } ,
103        rules => [
104                  '$m1 eq "A" && $m2 eq "C"' => { <effect X> },
105                  '$m1 eq "A" && $m2 eq "D"' => { <effect Y> },
106                  '$m1 eq "B" && ( $m2 eq "C" or $m2 eq "D") ' => { <effect Y> },
107                 ]
108
109       Note that the boolean expression is sanitized and used in a Perl eval,
110       so you can use most Perl syntax and regular expressions.
111
112       Functions (like &foo) are called like "$self->foo" before evaluation of
113       the boolean expression.
114
115       The rules must be declared with a slightly different way when a
116       check_list is used as a warp master: a check_list has not a simple
117       value. The rule must check whether a value is checked or not amongs all
118       the possible items of a check list.
119
120       For example, let's say that $cl in the rule below point to a check list
121       whose items are "A" and "B". The rule must verify if the item is set or
122       not:
123
124         rules => [
125              '$cl.is_set(A)' =>  { <effect when A is set> },
126              '$cl.is_set(B)' =>  { <effect when B is set> },
127              # can be combined
128              '$cl.is_set(B) and $cl.is_set(A)' =>  { <effect when A and B are set> },
129          ],
130
131       With this feature, you can control with a check list whether some
132       element must be shown or not (assuming "FooClass" and "BarClass"
133       classes are declared):
134
135           element => [
136               # warp master
137               my_check_list => {
138                   type       => 'check_list',
139                   choice     => ['has_foo','has_bar']
140               },
141               # controlled element that show up only when has_foo is set
142               foo => {
143                   type => 'warped_node',
144                   level => 'hidden',
145                   config_class_name => 'FooClass',
146                   follow => {
147                       selected => '- my_check_list'
148                   },
149                   'rules' => [
150                       '$selected.is_set(has_foo)' => {
151                           level => 'normal'
152                       }
153                   ]
154               },
155               # controlled element that show up only when has_bar is set
156               bar => {
157                   type => 'warped_node',
158                   level => 'hidden',
159                   config_class_name => 'BarClass',
160                   follow => {
161                       selected => '- my_check_list'
162                   },
163                   'rules' => [
164                       '$selected.is_set(has_bar)' => {
165                           level => 'normal'
166                       }
167                   ]
168               }
169           ]
170

Methods

172   warp_error
173       This method returns a string describing:
174
175       ·   The location(s) of the warp master
176
177       ·   The current value(s) of the warp master(s)
178
179       ·   The other values accepted by the warp master that can be tried (if
180           the warp master is an enumerated type)
181

How does this work ?

183       Registration
184           ·   When a warped object is created, the constructor registers to
185               the warp masters. The warp master are found by using the
186               special string passed to the "follow" parameter. As explained
187               in grab method, the string provides the location of the warp
188               master in the configuration tree using a symbolic form.
189
190           ·   Then the warped object retrieve the value(s) of the warp
191               master(s)
192
193           ·   Then the warped object warps itself using the above value(s).
194               Depending on these value(s), the properties of the warped
195               object are modified.
196
197       Master update
198           ·   When a warp master value is updated, the warp master calls all
199               its warped object and pass them the new master value.
200
201           ·   Then each warped object modifies properties according to the
202               new warp master value.
203

AUTHOR

205       Dominique Dumont, (ddumont at cpan dot org)
206

AUTHOR

212       Dominique Dumont
213

COPYRIGHT AND LICENSE

215       This software is Copyright (c) 2005-2019 by Dominique Dumont.
216
217       This is free software, licensed under:
218
219         The GNU Lesser General Public License, Version 2.1, February 1999
220
221
222
223perl v5.30.0                      2019-08-04          Config::Model::Warper(3)