1Config::Model::SearchElUesmeerntC(o3n)tributed Perl DocuCmoennftiagt:i:oMnodel::SearchElement(3)
2
6 Config::Model::SearchElement - Search an element in a configuration
7 model
8
10 version 2.138
11
13 use Config::Model;
14 # define configuration tree object
16 my $model = Config::Model->new;
17 $model->create_config_class(
18 name => "Foo",
19 element => [
20 [qw/foo bar/] => {
21 type => 'leaf',
22 value_type => 'string'
23 },
24 ]
25 );
26 $model ->create_config_class (
27 name => "MyClass",
28 element => [
30 [qw/foo bar/] => {
32 type => 'leaf',
33 value_type => 'string'
34 },
35 hash_of_nodes => {
36 type => 'hash', # hash id
37 index_type => 'string',
38 cargo => {
39 type => 'node',
40 config_class_name => 'Foo'
41 },
42 },
43 ],
44 ) ;
45 my $inst = $model->instance(root_class_name => 'MyClass' );
47 my $root = $inst->config_root ;
49 # put data
51 my $step = 'foo=FOO hash_of_nodes:fr foo=bonjour -
52 hash_of_nodes:en foo=hello ';
53 $root->load( step => $step );
54 # create searcher for manual search
56 my $searcher = $root->searcher();
57 # looking for foo element in the tree
59 $searcher -> prepare (element => 'foo') ;
60 my @next = $searcher->next_step() ;
61 print "next possible steps: @next\n";
63 # next possible steps: foo hash_of_nodes
64 # Looking for foo below hash_of_nodes
66 $searcher->choose('hash_of_nodes') ;
67 @next = $searcher->next_step() ;
68 print "next possible steps: @next\n";
70 # next possible steps: en fr
71 # Looking for foo below fr
73 $searcher->choose('fr') ;
74 @next = $searcher->next_step() ;
75 print "next possible steps: @next\n";
77 # next possible steps: foo
78 # last step
80 $searcher->choose('foo') ;
81 my $target = $searcher->current_object;
82 print "Found '",$target->location,"'\n";
84 # Found 'hash_of_nodes:fr foo'
85 # automatic search setup
87 my $element_call_back = sub { return 'hash_of_nodes' ;} ;
88 my $id_call_back = sub { return 'en' ;} ;
89 $searcher->reset ;
91 $target = $searcher->auto_choose($element_call_back, $id_call_back) ;
92 print "Automatic search found '",$target->location,"'\n";
93 # Automatic search found 'hash_of_nodes:en foo'
94
96 This modules provides a way to search for a configuration element in a
97 configuration tree by exploring the configuration model.
98 For instance, suppose that you have a xorg.conf model and you know that
100 you need to tune the "MergedXinerama" parameter, but you don't remember
101 where is this parameter in the configuration tree. This module guides
102 you through the tree to the(s) node(s) that contain this parameter.
103 This class should be invaluable to construct interactive user
105 interfaces.
106 This module provides 2 search modes:
108 · A manual search where you are guided step by step to the element
110 you're looking for. At each step, the module returns you the
111 possible paths to choose from. The user has to choose the correct
112 path from the available paths. Most of the time, only one
113 possibility is returned, so the user choice should be
114 straightforward. In other case (more that one choice), the user has
115 to decide the next step.
116 · An automatic search where you provide call-back that resolves the
118 ambiguities in case of multiple paths.
119
121 The constructor should be used only by Config::Model::Node.
122
124 get_searchable_elements
125 Return the list of elements found in model that can be searched in the
126 configuration tree.
127 prepare
129 Parameters: "(element => ...)"
130 Prepare the searcher to look for the element passed in the argument.
132 Returns the searcher object (i.e. $self).
133 reset
135 Re-initialize the search engine to redo the search from start
136 searched
138 Returns the searched element name.
139
141 next_step
142 Returns an array (or a ref depending on context) containing the next
143 possible step to find the element you're looking for. The array ref can
144 contain 1 or more elements.
145 If the array ref is empty, you can get the target element with
147 "current_object".
148 next_choice
150 Returns an array ref containing the next non-obvious choice to find the
151 element you're looking for.
152 If the array ref is empty, you can get the target element with
154 "current_object".
155 choose
157 Parameters: "( <chosen_element_name> )"
158 Tell the search engine your choice. The chosen element name must be one
160 of the possibilities given by "next_step".
161 current_object
163 Returns the object where the search engine is. It can be a node, a
164 list, a hash, or a leaf element.
165
167 auto_choose
168 Parameters: "( element_callback, id_call_back)"
169 Finds the searched element with minimal user interaction.
171 "element_callback" is called when the search engine finds a node where
173 more than one element can lead to the searched item.
174 "id_call_back" is called when the search engine finds a hash element or
176 a list element which contain no or more than 1 elements. In this case
177 the call-back returns an id that is used by the search engine to get
178 the target element.
179 Both call-back arguments are:
181 · The current object (as returned by "current_object")
183 · A list of possible choices
185 For instance, your callback can be :
187 my $id_cb = sub {
189 my ($object,@choices) = @_ ;
190 ....
191 return $choice[1] ;
192 }
193 Both call-back are expected to return a scalar value that is either:
195 · An element name
197 · An id valid for the list or hash element returned by
199 "current_object".
200
202 Dominique Dumont, (ddumont at cpan dot org)
203
205 Config::Model, Config::Model::Node, Config::Model::AnyId,
206 Config::Model::ListId, Config::Model::HashId, Config::Model::Value,
207
209 Dominique Dumont
210
212 This software is Copyright (c) 2005-2019 by Dominique Dumont.
213 This is free software, licensed under:
215 The GNU Lesser General Public License, Version 2.1, February 1999
217perl v5.30.1 2020-01-29 Config::Model::SearchElement(3)