Config::Model::ObjTreeScanner(3pm)

1Config::Model::ObjTreeSUcsaenrneCro(n3t)ributed Perl DocCuomnefnitga:t:iMoondel::ObjTreeScanner(3)
2
3
4

NAME

6       Config::Model::ObjTreeScanner - Scan config tree and perform call-backs
7

VERSION

9       version 1.205
10

SYNOPSIS

12        use Config::Model::ObjTreeScanner ;
13
14        # define configuration tree object
15        my $root = ... ;
16
17        # define leaf call back
18        my disp_leaf = sub {
19             my ($scanner, $data_ref, $node,$element_name,$index, $leaf_object) = @_ ;
20             $$data_ref .= "$element_name = ", $leaf_object->fetch ;
21           } ;
22
23        # simple scanner, (print all values with 'beginner' experience
24        $scan = Config::Model::ObjTreeScanner-> new
25         (
26          leaf_cb               => \&disp_leaf, # only mandatory parameter
27         ) ;
28
29        my $result = '';
30
31        $scan->scan_node(\$result, $root) ;
32
33
34        # For a more complex scanner
35
36        $scan = Config::Model::ObjTreeScanner-> new
37         (
38          fallback => 'none',     # all callback must be defined
39          experience => 'master', # consider all values
40
41          # node callback
42          node_content_cb               => \&disp_obj_elt ,
43
44          # element callback
45          list_element_cb       => \&disp_hash    ,
46          check_list_element_cb => \&disp_hash    ,
47          hash_element_cb       => \&disp_hash    ,
48          node_element_cb       => \&disp_obj     ,
49
50          # leaf callback
51          leaf_cb               => \&disp_leaf,
52          enum_value_cb         => \&disp_leaf,
53          integer_value_cb      => \&disp_leaf,
54          number_value_cb       => \&disp_leaf,
55          boolean_value_cb      => \&disp_leaf,
56          string_value_cb       => \&disp_leaf,
57          uniline_value_cb      => \&disp_leaf,
58          reference_value_cb    => \&disp_leaf,
59
60          # call-back when going up the tree
61          up_cb                 => sub {} ,
62         ) ;
63
64        $scan->scan_node(\$result, $root) ;
65

DESCRIPTION

67       This module creates an object that will explore (depth first) a
68       configuration tree.
69
70       For each part of the configuration tree, ObjTreeScanner object will
71       call-back one of the subroutine reference passed during construction.
72
73       Call-back routines will be called:
74
75       ·   For each node containing elements (including root node)
76
77       ·   For each element of a node. This element can be a list, hash, node
78           or simple leaf element.
79
80       ·   For each item contained in a node, hash or list. This item can be a
81           simple leaf or another node.
82
83       To continue the exploration, these call-backs must also call the
84       scanner. (i.e. perform another call-back). In other words the user's
85       subroutine and the scanner plays a game of ping-pong until the tree is
86       completely explored.
87
88       The scanner provides a set of default callback for the nodes. This way,
89       the user only have to provide call-backs for the leaves.
90
91       The scan is started with a call to "scan_node". The first parameter of
92       scan_node is a ref that is passed untouched to all call-back. This ref
93       may be used to store whatever result you want.
94

CONSTRUCTOR

96   new ( ... )
97       One way or another, the ObjTreeScanner object must be able to find all
98       callback for all the items of the tree. All the possible call-back are
99       listed below:
100
101       leaf callback:
102           "leaf_cb" is a catch-all generic callback. All other are
103           specialized call-back : "enum_value_cb", "integer_value_cb",
104           "number_value_cb", "boolean_value_cb", "string_value_cb",
105           "uniline_value_cb", "reference_value_cb"
106
107       node callback:
108           "node_content_cb"
109
110       element callback:
111           All these call-backs are called on the elements of a node:
112           "list_element_cb", "check_list_element_cb", "hash_element_cb",
113           "node_element_cb", "node_content_cb".
114
115       The user may specify all of them by passing the sub ref to the
116       constructor:
117
118          $scan = Config::Model::ObjTreeScanner-> new
119         (
120          # node callback
121          list_element_cb => sub ,
122          ...
123         )
124
125       Or use some default callback using the fallback parameter. Note that at
126       least one callback must be provided: "leaf_cb".
127
128       Optional parameter:
129
130       fallback
131           If set to 'node', the scanner will provide default call-back for
132           node items. If set to 'leaf', the scanner will set all leaf
133           callback (like enum_value_cb ...) to string_value_cb or to the
134           mandatory leaf_cb value. "fallback" callback will not override
135           callbacks provided by the user.
136
137           If set to 'all', equivalent to 'node' and 'leaf'. By default, no
138           fallback is provided.
139
140       experience
141           Set the privilege level used for the scan (default 'beginner').
142
143       auto_vivify
144           Whether to create the configuration items while scan (default is
145           1).
146

Callback prototypes

148   Leaf callback
149       "leaf_cb" is called for each leaf of the tree. The leaf callback will
150       be called with the following parameters:
151
152        ($scanner, $data_ref,$node,$element_name,$index, $leaf_object)
153
154       where:
155
156       ·   $scanner is the scanner object.
157
158       ·   $data_ref is a reference that is first passed to the first call of
159           the scanner. Then $data_ref is relayed through the various call-
160           backs
161
162       ·   $node is the node that contain the leaf.
163
164       ·   $element_name is the element (or attribute) that contain the leaf.
165
166       ·   $index is the index (or hash key) used to get the leaf. This may be
167           undefined if the element type is scalar.
168
169       ·   $leaf_object is a Config::Model::Value object.
170
171   List element callback
172       "list_element_cb" is called on all list element of a node, i.e. call on
173       the list object itself and not in the elements contained in the list.
174
175        ($scanner, $data_ref,$node,$element_name,@indexes)
176
177       @indexes is a list containing all the indexes of the list.
178
179       Example:
180
181         sub my_list_element_cb {
182            my ($scanner, $data_ref,$node,$element_name,@idx) = @_ ;
183
184            # custom code using $data_ref
185
186            # resume exploration (if needed)
187            map {$scanner->scan_list($data_ref,$node,$element_name,$_)} @idx ;
188
189            # note: scan_list and scan_hash are equivalent
190         }
191
192   Check list element callback
193       "check_list_element_cb": Like "list_element_cb", but called on a
194       check_list element.
195
196        ($scanner, $data_ref,$node,$element_name,@check_items)
197
198       @check_items is a list containing all the items of the check_list.
199
200   Hash element callback
201       "hash_element_cb": Like "list_element_cb", but called on a hash
202       element.
203
204        ($scanner, $data_ref,$node,$element_name,@keys)
205
206       @keys is an list containing all the keys of the hash.
207
208       Example:
209
210         sub my_hash_element_cb {
211            my ($scanner, $data_ref,$node,$element_name,@keys) = @_ ;
212
213            # custom code using $data_ref
214
215            # resume exploration
216            map {$scanner->scan_hash($data_ref,$node,$element_name,$_)} @keys ;
217         }
218
219   Node content callback
220       "node_content_cb": This call-back is called foreach node (including
221       root node).
222
223        ($scanner, $data_ref,$node,@element_list)
224
225       @element_list contains all the element names of the node.
226
227       Example:
228
229         sub my_node_element_cb = {
230            my ($scanner, $data_ref,$node,@element) = @_ ;
231
232            # custom code using $data_ref
233
234            # resume exploration
235            map {$scanner->scan_element($data_ref, $node,$_)} @element ;
236         }
237
238   Node element callback
239       "node_element_cb" is called for each node contained within a node (i.e
240       not with root node). This node can be held by a plain element or a hash
241       element or a list element:
242
243        ($scanner, $data_ref,$node,$element_name,$key, $contained_node)
244
245       $key may be undef if $contained_node is not a part of a hash or a list.
246       $element_name and $key specifies the element name and key of the the
247       contained node you want to scan. (passed with $contained_node) Note
248       that $contained_node may be undef if "auto_vivify" is 0.
249
250       Example:
251
252         sub my_node_content_cb {
253           my ($scanner, $data_ref,$node,$element_name,$key, $contained_node) = @_;
254
255           # your custom code using $data_ref
256
257           # explore next node
258           $scanner->scan_node($data_ref,$contained_node);
259         }
260

METHODS

262   scan_node ($data_r,$node)
263       Explore the node and call "node_element_cb" passing all element names.
264
265   scan_element($data_r,$node,$element_name)
266       Explore the element and call either "hash_element_cb",
267       "list_element_cb", "node_content_cb" or a leaf call-back (the leaf
268       call-back called depends on the Value object properties: enum, string,
269       integer and so on)
270
271   scan_hash ($data_r,$node,$element_name,$key)
272       Explore the hash member (or hash value) and call either
273       "node_content_cb" or a leaf call-back.
274
275   scan_list ($data_r,$node,$element_name,$index)
276       Just like "scan_hash": Explore the list member and call either
277       "node_content_cb" or a leaf call-back.
278
279   get_keys ($node, $element_name)
280       Returns an list containing the sorted keys of a hash element or returns
281       an list containning (0.. last_index) of an list element.
282
283       Throws an exception if element is not an list or a hash element.
284
285   experience ( [ new_experience ] )
286       Set or query the experience level of the scanner
287
288   get_experience_ref ( )
289       Get a SCALAR reference on experience. Use with care.
290

AUTHOR

292       Dominique Dumont, (ddumont at cpan dot org)
293