1Config::Model::SearchElUesmeerntC(o3n)tributed Perl DocuCmoennftiagt:i:oMnodel::SearchElement(3)
2
3
4

NAME

6       Config::Model::SearchElement - Search an element in a configuration
7       model
8

VERSION

10       version 2.150
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/foo bar/] => {
21                   type       => 'leaf',
22                   value_type => 'string'
23               },
24           ]
25        );
26        $model ->create_config_class (
27           name => "MyClass",
28
29           element => [
30
31               [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
46        my $inst = $model->instance(root_class_name => 'MyClass' );
47
48        my $root = $inst->config_root ;
49
50        # 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
55        # create searcher for manual search
56        my $searcher = $root->searcher();
57
58        # looking for foo element in the tree
59        $searcher -> prepare (element => 'foo') ;
60        my @next = $searcher->next_step() ;
61
62        print "next possible steps: @next\n";
63        # next possible steps: foo hash_of_nodes
64
65        # Looking for foo below hash_of_nodes
66        $searcher->choose('hash_of_nodes') ;
67        @next = $searcher->next_step() ;
68
69        print "next possible steps: @next\n";
70        # next possible steps: en fr
71
72        # Looking for foo below fr
73        $searcher->choose('fr') ;
74        @next = $searcher->next_step() ;
75
76        print "next possible steps: @next\n";
77        # next possible steps: foo
78
79        # last step
80        $searcher->choose('foo') ;
81        my $target = $searcher->current_object;
82
83        print "Found '",$target->location,"'\n";
84        # Found 'hash_of_nodes:fr foo'
85
86        # automatic search setup
87        my $element_call_back = sub { return 'hash_of_nodes' ;} ;
88        my $id_call_back      = sub { return 'en' ;} ;
89
90        $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

DESCRIPTION

96       This modules provides a way to search for a configuration element in a
97       configuration tree by exploring the configuration model.
98
99       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
104       This class should be invaluable to construct interactive user
105       interfaces.
106
107       This module provides 2 search modes:
108
109       •   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
117       •   An automatic search where you provide call-back that resolves the
118           ambiguities in case of multiple paths.
119

CONSTRUCTOR

121       The constructor should be used only by Config::Model::Node.
122

Methods

124   get_searchable_elements
125       Return the list of elements found in model that can be searched in the
126       configuration tree.
127
128   prepare
129       Parameters: "(element => ...)"
130
131       Prepare the searcher to look for the element passed in the argument.
132       Returns the searcher object (i.e. $self).
133
134   reset
135       Re-initialize the search engine to redo the search from start
136
137   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
146       If the array ref is empty, you can get the target element with
147       "current_object".
148
149   next_choice
150       Returns an array ref containing the next non-obvious choice to find the
151       element you're looking for.
152
153       If the array ref is empty, you can get the target element with
154       "current_object".
155
156   choose
157       Parameters: "( <chosen_element_name> )"
158
159       Tell the search engine your choice. The chosen element name must be one
160       of the possibilities given by "next_step".
161
162   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
170       Finds the searched element with minimal user interaction.
171
172       "element_callback" is called when the search engine finds a node where
173       more than one element can lead to the searched item.
174
175       "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
180       Both call-back arguments are:
181
182       •   The current object (as returned by "current_object")
183
184       •   A list of possible choices
185
186       For instance, your callback can be :
187
188        my $id_cb = sub {
189           my ($object,@choices) = @_ ;
190           ....
191           return $choice[1] ;
192        }
193
194       Both call-back are expected to return a scalar value that is either:
195
196       •   An element name
197
198       •   An id valid for the list or hash element returned by
199           "current_object".
200

AUTHOR

202       Dominique Dumont, (ddumont at cpan dot org)
203

SEE ALSO

205       Config::Model, Config::Model::Node, Config::Model::AnyId,
206       Config::Model::ListId, Config::Model::HashId, Config::Model::Value,
207

AUTHOR

209       Dominique Dumont
210
212       This software is Copyright (c) 2005-2022 by Dominique Dumont.
213
214       This is free software, licensed under:
215
216         The GNU Lesser General Public License, Version 2.1, February 1999
217
218
219
220perl v5.34.1                      2022-05-09   Config::Model::SearchElement(3)
Impressum