new

One way or another, the ObjTreeScanner object must be able to find all callback for all the items of the tree. All the possible call-back and hooks are listed below:

leaf callback:

"leaf_cb" is a catch-all generic callback. All other are specialized call-back : "enum_value_cb", "integer_value_cb", "number_value_cb", "boolean_value_cb", "string_value_cb", "uniline_value_cb", "reference_value_cb"

node callback:

"node_content_cb" , "node_dispatch_cb"

node hooks:

"node_content_hook"

element callback:

All these call-backs are called on the elements of a node: "list_element_cb", "check_list_element_cb", "hash_element_cb", "node_element_cb", "node_content_cb".

element hooks:

"list_element_hook", "hash_element_hook".

The user may specify all of them by passing a sub ref to the constructor:

   $scan = Config::Model::ObjTreeScanner-> new
  (
   list_element_cb => sub { ... },
   ...
  )

Or use some default callback using the fallback parameter. Note that at least one callback must be provided: "leaf_cb".

Optional parameter:

fallback

If set to "node", the scanner provides default call-back for node items. If set to "leaf", the scanner sets all leaf callback (like enum_value_cb ...) to string_value_cb or to the mandatory leaf_cb value. "fallback" callback does not override callbacks provided by the user.

If set to "all" , the scanner provides fallbacks for leaf and node. By default, all fallback are provided.

auto_vivify

Whether to create configuration objects while scanning (default is 1).

check

"yes", "no" or "skip".

Leaf callback

"leaf_cb" is called for each leaf of the tree. The leaf callback is called with the following parameters:

 ($scanner, $data_ref,$node,$element_name,$index, $leaf_object)

where:

• $scanner is the scanner object.
• $data_ref is a reference that is first passed to the first call of the scanner. Then $data_ref is relayed through the various call-backs
• $node is the node that contain the leaf.
• $element_name is the element (or attribute) that contain the leaf.
• $index is the index (or hash key) used to get the leaf. This may be undefined if the element type is scalar.
• $leaf_object is a Config::Model::Value object.

List element callback

"list_element_cb" is called on all list element of a node, i.e. call on the list object itself and not in the elements contained in the list.

 ($scanner, $data_ref,$node,$element_name,@indexes)

@indexes is a list containing all the indexes of the list.

Example:

  sub my_list_element_cb {
     my ($scanner, $data_ref,$node,$element_name,@idx) = @_ ;
     # custom code using $data_ref
     # resume exploration (if needed)
     map {$scanner->scan_list($data_ref,$node,$element_name,$_)} @idx ;
     # note: scan_list and scan_hash are equivalent
  }

List element hook

"list_element_hook": Works like the list element callback. Except that the calls to "scan_list" are not required. This is done once the hook returns.

Check list element callback

"check_list_element_cb": Like "list_element_cb", but called on a check_list element.

 ($scanner, $data_ref,$node,$element_name, index, check_list_obj)

"index" is always undef as a check_list cannot be contained in a hash or list (yet)

Hash element callback

"hash_element_cb": Like "list_element_cb", but called on a hash element.

 ($scanner, $data_ref,$node,$element_name,@keys)

@keys is an list containing all the keys of the hash.

Example:

  sub my_hash_element_cb {
     my ($scanner, $data_ref,$node,$element_name,@keys) = @_ ;
     # custom code using $data_ref
     # resume exploration
     map {$scanner->scan_hash($data_ref,$node,$element_name,$_)} @keys ;
  }

Hash element hook

"hash_element_hook": Works like the hash element callback. Except that the calls to "scan_hash" are not required. This is done once the hook returns.

Node content callback

"node_content_cb": This call-back is called foreach node (including root node).

 ($scanner, $data_ref,$node,@element_list)

@element_list contains all the element names of the node.

Example:

  sub my_content_cb {
     my ($scanner, $data_ref,$node,@element) = @_ ;
     # custom code using $data_ref
     # resume exploration
     map {$scanner->scan_element($data_ref, $node,$_)} @element ;
  }

Node content hook

"node_content_hook": This hook is called foreach node (including root node). Works like the node content call-back. Except that the calls to "scan_element" are not required. This is done once the hook returns.

Dispatch node callback

"node_dispatch_cb": Any callback specified in the hash is called for each instance of the specified configuration class. (this may include the root node).

For instance, if you have:

  node_dispach_cb => {
    ClassA => \&my_class_a_dispatch_cb,
    ClassB => \&my_class_b_dispatch_cb,
  }

&my_class_a_dispatch_cb is called for each instance of "ClassA" and &my_class_b_dispatch_cb is called for each instance of "ClassB".

They is called with the following parameters:

 ($scanner, $data_ref,$node,@element_list)

@element_list contains all the element names of the node.

Example:

  sub my_class_a_dispatch_cb = {
     my ($scanner, $data_ref,$node,@element) = @_ ;
     # custom code using $data_ref
     # resume exploration
     map {$scanner->scan_element($data_ref, $node,$_)} @element ;
  }

Node element callback

"node_element_cb" is called for each node contained within a node (i.e not with root node). This node can be held by a plain element or a hash element or a list element:

 ($scanner, $data_ref,$node,$element_name,$key, $contained_node)

$key may be undef if $contained_node is not a part of a hash or a list. $element_name and $key specifies the element name and key of the the contained node you want to scan. (passed with $contained_node) Note that $contained_node may be undef if "auto_vivify" is 0.

Example:

  sub my_node_element_cb {
    my ($scanner, $data_ref,$node,$element_name,$key, $contained_node) = @_;
    # your custom code using $data_ref
    # explore next node
    $scanner->scan_node($data_ref,$contained_node);
  }

scan_node

Parameters: "($data_r,$node)"

Explore the node and call either "node_dispatch_cb" (if the node class name matches the dispatch_node hash) or (e.g. xor) "node_element_cb" passing all element names.

"up_cb" is called once the first callback returns.

scan_element

Parameters: "($data_r,$node,$element_name)"

Explore the element and call either "hash_element_cb", "list_element_cb", "node_content_cb" or a leaf call-back (the leaf call-back called depends on the Value object properties: enum, string, integer and so on)

scan_hash

Parameters: "($data_r,$node,$element_name,$key)"

Explore the hash member (or hash value) and call either "node_content_cb" or a leaf call-back.

scan_list

Parameters: "($data_r,$node,$element_name,$index)"

Just like "scan_hash": Explore the list member and call either "node_content_cb" or a leaf call-back.

get_keys

Parameters: "($node, $element_name)"

Returns an list containing the sorted keys of a hash element or returns an list containing (0.. last_index) of an list element.

Throws an exception if element is not an list or a hash element.