1Config::Model::Warper(3Upsme)r Contributed Perl DocumentaCtoinofnig::Model::Warper(3pm)
2
6 Config::Model::Warper - Warp tree properties
7
9 version 2.153
10
12 # internal class
13
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
22 Warping an object means that the properties of the object is changed
23 depending on the value of another object.
24 The changed object is referred as the warped object.
26 The other object that holds the important value is referred as the warp
28 master or the warper object.
29 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
35 Warp arguments are passed in a hash ref whose keys are "follow" and and
36 "rules":
37 Warp follow argument
39 Grab string leading to the "Config::Model::Value" or
40 Config::Model::CheckList warp master. E.g.:
41 follow => '! tree_macro'
43 In case of several warp master, "follow" is set to an array ref of
45 several grab string:
46 follow => [ '! macro1', '- macro2' ]
48 You can also use named parameters:
50 follow => { m1 => '! macro1', m2 => '- macro2' }
52 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 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 E.g. for a simple case (rules is a hash ref) :
63 follow => '! macro1' ,
65 rules => { A => { <effect when macro1 is A> },
66 B => { <effect when macro1 is B> }
67 }
68 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 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 In case of several warp masters, "follow" must use named parameters,
79 and rules must use boolean expression:
80 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 Of course some combinations of warp master values can have the same
90 effect:
91 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 In this case, you can use different boolean expression to save typing:
101 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 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 Functions (like &foo) are called like "$self->foo" before evaluation of
113 the boolean expression.
114 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 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 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 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 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
172 warp_error
173 This method returns a string describing:
174 • The location(s) of the warp master
176 • The current value(s) of the warp master(s)
178 • The other values accepted by the warp master that can be tried (if
180 the warp master is an enumerated type)
181
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 • Then the warped object retrieve the value(s) of the warp
191 master(s)
192 • 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 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 • Then each warped object modifies properties according to the
202 new warp master value.
203
205 Dominique Dumont, (ddumont at cpan dot org)
206
208 Config::Model::AnyThing, Config::Model::HashId, Config::Model::ListId,
209 Config::Model::WarpedNode, Config::Model::Value
210
212 Dominique Dumont
213
215 This software is Copyright (c) 2005-2022 by Dominique Dumont.
216 This is free software, licensed under:
218 The GNU Lesser General Public License, Version 2.1, February 1999
220perl v5.38.0 2023-07-25 Config::Model::Warper(3pm)