Config::Model::Iterator(3pm)

1Config::Model::IteratorU(s3eprm)Contributed Perl DocumenCtoantfiiogn::Model::Iterator(3pm)
2
3
4

NAME

6       Config::Model::Iterator - Iterates forward or backward a configuration
7       tree
8

VERSION

10       version 2.153
11

SYNOPSIS

13        use Config::Model;
14
15        # define configuration tree object
16        my $model = Config::Model->new;
17        $model->create_config_class(
18           name    => "Foo",
19           element => [
20               [qw/bar baz/] => {
21                   type       => 'leaf',
22                   value_type => 'string',
23                   level => 'important' ,
24               },
25           ]
26        );
27        $model->create_config_class(
28           name    => "MyClass",
29           element => [
30               foo_nodes => {
31                   type       => 'hash',     # hash id
32                   index_type => 'string',
33                   level => 'important' ,
34                   cargo      => {
35                       type              => 'node',
36                       config_class_name => 'Foo'
37                   },
38               },
39           ],
40        );
41
42        my $inst = $model->instance( root_class_name => 'MyClass' );
43        # create some Foo objects
44        $inst->config_root->load("foo_nodes:foo1 - foo_nodes:foo2  ") ;
45
46        my $my_leaf_cb = sub {
47           my ($iter, $data_r,$node,$element,$index, $leaf_object) = @_ ;
48           print "leaf_cb called for ",$leaf_object->location,"\n" ;
49        } ;
50        my $my_hash_cb = sub {
51           my ($iter, $data_r,$node,$element,@keys) = @_ ;
52           print "hash_element_cb called for element $element with keys @keys\n" ;
53        } ;
54
55        my $iterator = $inst -> iterator (
56           leaf_cb         => $my_leaf_cb,
57           hash_element_cb => $my_hash_cb ,
58        );
59
60        $iterator->start ;
61        ### prints
62        # hash_element_cb called for element foo_nodes with keys foo1 foo2
63        # leaf_cb called for foo_nodes:foo1 bar
64        # leaf_cb called for foo_nodes:foo1 baz
65        # leaf_cb called for foo_nodes:foo2 bar
66        # leaf_cb called for foo_nodes:foo2 baz
67

DESCRIPTION

69       This module provides a class that is able to iterate forward or
70       backward a configuration tree.  The iterator stops and calls back user
71       defined subroutines on one of the following condition:
72
73       •   A configuration item contains an error (mostly undefined mandatory
74           values)
75
76       •   A configuration item contains warnings and the constructor's
77           argument "call_back_on_warning" was set.
78
79       •   A configuration item has a "important" level and the constructor's
80           argument "call_back_on_important" was set.. See level parameter for
81           details.
82
83       The iterator supports going forward and backward (to support "back" and
84       "next" buttons on a wizard widget).
85

CONSTRUCTOR

87       The constructor should be used only by Config::Model::Instance with the
88       iterator method.
89

Creating an iterator

91       A iterator requires at least two kind of call-back: a call-back for
92       leaf elements and a call-back for hash elements (which is also used for
93       list elements).
94
95       These call-back must be passed when creating the iterator (the
96       parameters are named "leaf_cb" and "hash_element_cb")
97
98       Here are the the parameters accepted by "iterator":
99
100   call_back_on_important
101       Whether to call back when an important element is found (default 0).
102
103   call_back_on_warning
104       Whether to call back when an item with warnings is found (default 0).
105
106   status
107       Specifies the status of the element scanned by the wizard (default
108       'standard').
109
110   leaf_cb
111       Subroutine called backed for leaf elements. See "Callback prototypes"
112       in Config::Model::ObjTreeScanner for signature and details. (mandatory)
113
114   hash_element_cb
115       Subroutine called backed for hash elements. See "Callback prototypes"
116       in Config::Model::ObjTreeScanner for signature and details. (mandatory)
117

Custom callbacks

119       By default, "leaf_cb" is called for all types of leaf elements (i.e
120       enum. integer, strings, ...). But you can provide dedicated call-back
121       for each type of leaf:
122
123        enum_value_cb, integer_value_cb, number_value_cb, boolean_value_cb,
124        uniline_value_cb, string_value_cb
125
126       Likewise, you can also provide a call-back dedicated to list elements
127       with "list_element_cb"
128

Methods

130   start
131       Start the scan and perform call-back when needed. This function returns
132       when the scan is completely done.
133
134   bail_out
135       When called, a variable is set so that all call_backs returns as soon
136       as possible. Used to abort wizard.
137
138   go_forward
139       Set wizard in forward (default) mode.
140
141   go_backward
142       Set wizard in backward mode.
143

AUTHOR

145       Dominique Dumont, (ddumont at cpan dot org)
146

AUTHOR

153       Dominique Dumont
154

COPYRIGHT AND LICENSE

156       This software is Copyright (c) 2005-2022 by Dominique Dumont.
157
158       This is free software, licensed under:
159
160         The GNU Lesser General Public License, Version 2.1, February 1999
161
162
163
164perl v5.38.0                      2023-07-25      Config::Model::Iterator(3pm)