new

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

 ($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

 ($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

Check list element callback

 ($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

 ($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

Node content callback

 ($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

Dispatch node callback

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

 ($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

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

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

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

scan_list

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

get_keys

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.