.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::Model::ObjTreeScanner 3pm"
.TH Config::Model::ObjTreeScanner 3pm "2023-08-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Model::ObjTreeScanner \- Scan config tree and perform call\-backs for each element or node
.SH "VERSION"
.IX Header "VERSION"
version 2.153
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Config::Model ;
\&
\& # define configuration tree object
\& my $model = Config::Model\->new ;
\& $model \->create_config_class (
\&    name => "MyClass",
\&    element => [
\&        [qw/foo bar/] => {
\&            type => \*(Aqleaf\*(Aq,
\&            value_type => \*(Aqstring\*(Aq
\&        },
\&        baz => {
\&            type => \*(Aqhash\*(Aq,
\&            index_type => \*(Aqstring\*(Aq ,
\&            cargo => {
\&                type => \*(Aqleaf\*(Aq,
\&                value_type => \*(Aqstring\*(Aq,
\&            },
\&        },
\&
\&    ],
\& ) ;
\&
\& my $inst = $model\->instance(root_class_name => \*(AqMyClass\*(Aq );
\&
\& my $root = $inst\->config_root ;
\&
\& # put some data in config tree the hard way
\& $root\->fetch_element(\*(Aqfoo\*(Aq)\->store(\*(Aqyada\*(Aq) ;
\& $root\->fetch_element(\*(Aqbar\*(Aq)\->store(\*(Aqbla bla\*(Aq) ;
\& $root\->fetch_element(\*(Aqbaz\*(Aq)\->fetch_with_id(\*(Aqen\*(Aq)\->store(\*(Aqhello\*(Aq) ;
\&
\& # put more data the easy way
\& my $steps = \*(Aqbaz:fr=bonjour baz:hr="dobar dan"\*(Aq;
\& $root\->load( steps => $steps ) ;
\&
\& # define leaf call back
\& my $disp_leaf = sub {
\&      my ($scanner, $data_ref, $node,$element_name,$index, $leaf_object) = @_ ;
\&      $$data_ref .= "disp_leaf called for \*(Aq". $leaf_object\->name.
\&        "\*(Aq value \*(Aq".$leaf_object\->fetch."\*(Aq\en";
\&    } ;
\&
\& # simple scanner, (print all values)
\& my $scan = Config::Model::ObjTreeScanner\-> new (
\&   leaf_cb => $disp_leaf, # only mandatory parameter
\& ) ;
\&
\& my $result = \*(Aq\*(Aq;
\& $scan\->scan_node(\e$result, $root) ;
\& print $result ;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module creates an object that explores (depth first) a
configuration tree.
.PP
For each part of the configuration tree, ObjTreeScanner object calls
one of the subroutine reference passed during construction. (a call-back
or a hook)
.PP
Call-back and hook routines are called:
.IP "\(bu" 4
For each node containing elements (including root node)
.IP "\(bu" 4
For each element of a node. This element can be a list, hash, node or
leaf element.
.IP "\(bu" 4
For each item contained in a node, hash or list. This item can be a
leaf or another node.
.PP
To continue the exploration, these call-backs must also call the
scanner. (i.e. perform another call-back). In other words the user's
subroutine and the scanner play a game of ping-pong until the tree is
completely explored.
.PP
Hooks routines are not required to resume the exploration, i.e. to call
the scanner. This is done once the hook routine has returned.
.PP
The scanner provides a set of default callback for the nodes. This
way, the user only have to provide call-backs for the leaves.
.PP
The scan is started with a call to \f(CW\*(C`scan_node\*(C'\fR. The first parameter
of scan_node is a ref that is passed untouched to all call-back. This
ref may be used to store whatever result you want.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "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:
.IP "leaf callback:" 4
.IX Item "leaf callback:"
\&\f(CW\*(C`leaf_cb\*(C'\fR is a catch-all generic callback. All other are specialized
call-back : \f(CW\*(C`enum_value_cb\*(C'\fR, \f(CW\*(C`integer_value_cb\*(C'\fR, \f(CW\*(C`number_value_cb\*(C'\fR,
\&\f(CW\*(C`boolean_value_cb\*(C'\fR, \f(CW\*(C`string_value_cb\*(C'\fR, \f(CW\*(C`uniline_value_cb\*(C'\fR,
\&\f(CW\*(C`reference_value_cb\*(C'\fR
.IP "node callback:" 4
.IX Item "node callback:"
\&\f(CW\*(C`node_content_cb\*(C'\fR , \f(CW\*(C`node_dispatch_cb\*(C'\fR
.IP "node hooks:" 4
.IX Item "node hooks:"
\&\f(CW\*(C`node_content_hook\*(C'\fR
.IP "element callback:" 4
.IX Item "element callback:"
All these call-backs are called on the elements of a node:
\&\f(CW\*(C`list_element_cb\*(C'\fR, \f(CW\*(C`check_list_element_cb\*(C'\fR, \f(CW\*(C`hash_element_cb\*(C'\fR,
\&\f(CW\*(C`node_element_cb\*(C'\fR, \f(CW\*(C`node_content_cb\*(C'\fR.
.IP "element hooks:" 4
.IX Item "element hooks:"
\&\f(CW\*(C`list_element_hook\*(C'\fR, \f(CW\*(C`hash_element_hook\*(C'\fR.
.PP
The user may specify all of them by passing a sub ref to the
constructor:
.PP
.Vb 5
\&   $scan = Config::Model::ObjTreeScanner\-> new
\&  (
\&   list_element_cb => sub { ... },
\&   ...
\&  )
.Ve
.PP
Or use some default callback using the fallback parameter. Note that
at least one callback must be provided: \f(CW\*(C`leaf_cb\*(C'\fR.
.PP
Optional parameter:
.IP "fallback" 4
.IX Item "fallback"
If set to \f(CW\*(C`node\*(C'\fR, the scanner provides default call-back for node
items. If set to \f(CW\*(C`leaf\*(C'\fR, the scanner sets all leaf callback (like
enum_value_cb ...) to string_value_cb or to the mandatory leaf_cb
value. \*(L"fallback\*(R" callback does not override callbacks provided by the
user.
.Sp
If set to \f(CW\*(C`all\*(C'\fR , the scanner provides fallbacks for leaf and node. 
By default, all fallback are provided.
.IP "auto_vivify" 4
.IX Item "auto_vivify"
Whether to create configuration objects while scanning (default is 1).
.IP "check" 4
.IX Item "check"
\&\f(CW\*(C`yes\*(C'\fR, \f(CW\*(C`no\*(C'\fR or \f(CW\*(C`skip\*(C'\fR.
.SH "Callback prototypes"
.IX Header "Callback prototypes"
.SS "Leaf callback"
.IX Subsection "Leaf callback"
\&\f(CW\*(C`leaf_cb\*(C'\fR is called for each leaf of the tree. The leaf callback is
called with the following parameters:
.PP
.Vb 1
\& ($scanner, $data_ref,$node,$element_name,$index, $leaf_object)
.Ve
.PP
where:
.IP "\(bu" 4
\&\f(CW$scanner\fR is the scanner object.
.IP "\(bu" 4
\&\f(CW$data_ref\fR is a reference that is first passed to the first call of
the scanner. Then \f(CW$data_ref\fR is relayed through the various
call-backs
.IP "\(bu" 4
\&\f(CW$node\fR is the node that contain the leaf.
.IP "\(bu" 4
\&\f(CW$element_name\fR is the element (or attribute) that contain the leaf.
.IP "\(bu" 4
\&\f(CW$index\fR is the index (or hash key) used to get the leaf. This may
be undefined if the element type is scalar.
.IP "\(bu" 4
\&\f(CW$leaf_object\fR is a Config::Model::Value object.
.SS "List element callback"
.IX Subsection "List element callback"
\&\f(CW\*(C`list_element_cb\*(C'\fR 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.
.PP
.Vb 1
\& ($scanner, $data_ref,$node,$element_name,@indexes)
.Ve
.PP
\&\f(CW@indexes\fR is a list containing all the indexes of the list.
.PP
Example:
.PP
.Vb 2
\&  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
\&  }
.Ve
.SS "List element hook"
.IX Subsection "List element hook"
\&\f(CW\*(C`list_element_hook\*(C'\fR: Works like the list element callback. Except that the calls to
\&\f(CW\*(C`scan_list\*(C'\fR are not required. This is done once the hook returns.
.SS "Check list element callback"
.IX Subsection "Check list element callback"
\&\f(CW\*(C`check_list_element_cb\*(C'\fR: Like \f(CW\*(C`list_element_cb\*(C'\fR, but called on a
check_list element.
.PP
.Vb 1
\& ($scanner, $data_ref,$node,$element_name, index, check_list_obj)
.Ve
.PP
\&\f(CW\*(C`index\*(C'\fR is always undef as a check_list cannot be contained in a hash or list (yet)
.SS "Hash element callback"
.IX Subsection "Hash element callback"
\&\f(CW\*(C`hash_element_cb\*(C'\fR: Like \f(CW\*(C`list_element_cb\*(C'\fR, but called on a
hash element.
.PP
.Vb 1
\& ($scanner, $data_ref,$node,$element_name,@keys)
.Ve
.PP
\&\f(CW@keys\fR is an list containing all the keys of the hash.
.PP
Example:
.PP
.Vb 2
\&  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 ;
\&  }
.Ve
.SS "Hash element hook"
.IX Subsection "Hash element hook"
\&\f(CW\*(C`hash_element_hook\*(C'\fR: Works like the hash element callback. Except that the calls to
\&\f(CW\*(C`scan_hash\*(C'\fR are not required. This is done once the hook returns.
.SS "Node content callback"
.IX Subsection "Node content callback"
\&\f(CW\*(C`node_content_cb\*(C'\fR: This call-back is called foreach node (including
root node).
.PP
.Vb 1
\& ($scanner, $data_ref,$node,@element_list)
.Ve
.PP
\&\f(CW@element_list\fR contains all the element names of the node.
.PP
Example:
.PP
.Vb 2
\&  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 ;
\&  }
.Ve
.SS "Node content hook"
.IX Subsection "Node content hook"
\&\f(CW\*(C`node_content_hook\*(C'\fR: This hook is called foreach node (including
root node). Works like the node content call-back. Except that the calls to
\&\f(CW\*(C`scan_element\*(C'\fR are not required. This is done once the hook returns.
.SS "Dispatch node callback"
.IX Subsection "Dispatch node callback"
\&\f(CW\*(C`node_dispatch_cb\*(C'\fR: Any callback specified in the hash is called for
each instance of the specified configuration class.
(this may include the  root node).
.PP
For instance, if you have:
.PP
.Vb 4
\&  node_dispach_cb => {
\&    ClassA => \e&my_class_a_dispatch_cb,
\&    ClassB => \e&my_class_b_dispatch_cb,
\&  }
.Ve
.PP
\&\f(CW&my_class_a_dispatch_cb\fR is called for each instance of \f(CW\*(C`ClassA\*(C'\fR and
\&\f(CW&my_class_b_dispatch_cb\fR is called for each instance of \f(CW\*(C`ClassB\*(C'\fR.
.PP
They is called with the following parameters:
.PP
.Vb 1
\& ($scanner, $data_ref,$node,@element_list)
.Ve
.PP
\&\f(CW@element_list\fR contains all the element names of the node.
.PP
Example:
.PP
.Vb 2
\&  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 ;
\&  }
.Ve
.SS "Node element callback"
.IX Subsection "Node element callback"
\&\f(CW\*(C`node_element_cb\*(C'\fR 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:
.PP
.Vb 1
\& ($scanner, $data_ref,$node,$element_name,$key, $contained_node)
.Ve
.PP
\&\f(CW$key\fR may be undef if \f(CW$contained_node\fR is not a part of a hash or
a list. \f(CW$element_name\fR and \f(CW$key\fR specifies the element name and
key of the the contained node you want to scan. (passed with
\&\f(CW$contained_node\fR) Note that \f(CW$contained_node\fR may be undef if
\&\f(CW\*(C`auto_vivify\*(C'\fR is 0.
.PP
Example:
.PP
.Vb 2
\&  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);
\&  }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "scan_node"
.IX Subsection "scan_node"
Parameters: \f(CW\*(C`($data_r,$node)\*(C'\fR
.PP
Explore the node and call either \f(CW\*(C`node_dispatch_cb\*(C'\fR (if the node class
name matches the dispatch_node hash) \fBor\fR (e.g. xor) \f(CW\*(C`node_element_cb\*(C'\fR passing
all element names.
.PP
\&\f(CW\*(C`up_cb\*(C'\fR is called once the first callback returns.
.SS "scan_element"
.IX Subsection "scan_element"
Parameters: \f(CW\*(C`($data_r,$node,$element_name)\*(C'\fR
.PP
Explore the element and call either \f(CW\*(C`hash_element_cb\*(C'\fR,
\&\f(CW\*(C`list_element_cb\*(C'\fR, \f(CW\*(C`node_content_cb\*(C'\fR or a leaf call-back (the leaf
call-back called depends on the Value object properties: enum, string,
integer and so on)
.SS "scan_hash"
.IX Subsection "scan_hash"
Parameters: \f(CW\*(C`($data_r,$node,$element_name,$key)\*(C'\fR
.PP
Explore the hash member (or hash value) and call either \f(CW\*(C`node_content_cb\*(C'\fR or
a leaf call-back.
.SS "scan_list"
.IX Subsection "scan_list"
Parameters: \f(CW\*(C`($data_r,$node,$element_name,$index)\*(C'\fR
.PP
Just like \f(CW\*(C`scan_hash\*(C'\fR: Explore the list member and call either
\&\f(CW\*(C`node_content_cb\*(C'\fR or a leaf call-back.
.SS "get_keys"
.IX Subsection "get_keys"
Parameters: \f(CW\*(C`($node, $element_name)\*(C'\fR
.PP
Returns an list containing the sorted keys of a hash element or returns
an list containing (0.. last_index) of an list element.
.PP
Throws an exception if element is not an list or a hash element.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, (ddumont at cpan dot org)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Model,Config::Model::Node,Config::Model::Instance,
Config::Model::HashId,
Config::Model::ListId,
Config::Model::CheckList,
Config::Model::Value
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2005\-2022 by Dominique Dumont.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve