Provided by: libconfig-model-perl_2.152-1_all 
NAME
Config::Model::SearchElement - Search an element in a configuration model
VERSION
version 2.152
SYNOPSIS
use Config::Model;
# define configuration tree object
my $model = Config::Model->new;
$model->create_config_class(
name => "Foo",
element => [
[qw/foo bar/] => {
type => 'leaf',
value_type => 'string'
},
]
);
$model ->create_config_class (
name => "MyClass",
element => [
[qw/foo bar/] => {
type => 'leaf',
value_type => 'string'
},
hash_of_nodes => {
type => 'hash', # hash id
index_type => 'string',
cargo => {
type => 'node',
config_class_name => 'Foo'
},
},
],
) ;
my $inst = $model->instance(root_class_name => 'MyClass' );
my $root = $inst->config_root ;
# put data
my $step = 'foo=FOO hash_of_nodes:fr foo=bonjour -
hash_of_nodes:en foo=hello ';
$root->load( step => $step );
# create searcher for manual search
my $searcher = $root->searcher();
# looking for foo element in the tree
$searcher -> prepare (element => 'foo') ;
my @next = $searcher->next_step() ;
print "next possible steps: @next\n";
# next possible steps: foo hash_of_nodes
# Looking for foo below hash_of_nodes
$searcher->choose('hash_of_nodes') ;
@next = $searcher->next_step() ;
print "next possible steps: @next\n";
# next possible steps: en fr
# Looking for foo below fr
$searcher->choose('fr') ;
@next = $searcher->next_step() ;
print "next possible steps: @next\n";
# next possible steps: foo
# last step
$searcher->choose('foo') ;
my $target = $searcher->current_object;
print "Found '",$target->location,"'\n";
# Found 'hash_of_nodes:fr foo'
# automatic search setup
my $element_call_back = sub { return 'hash_of_nodes' ;} ;
my $id_call_back = sub { return 'en' ;} ;
$searcher->reset ;
$target = $searcher->auto_choose($element_call_back, $id_call_back) ;
print "Automatic search found '",$target->location,"'\n";
# Automatic search found 'hash_of_nodes:en foo'
DESCRIPTION
This modules provides a way to search for a configuration element in a configuration tree
by exploring the configuration model.
For instance, suppose that you have a xorg.conf model and you know that you need to tune
the "MergedXinerama" parameter, but you don't remember where is this parameter in the
configuration tree. This module guides you through the tree to the(s) node(s) that contain
this parameter.
This class should be invaluable to construct interactive user interfaces.
This module provides 2 search modes:
• A manual search where you are guided step by step to the element you're looking for.
At each step, the module returns you the possible paths to choose from. The user has
to choose the correct path from the available paths. Most of the time, only one
possibility is returned, so the user choice should be straightforward. In other case
(more that one choice), the user has to decide the next step.
• An automatic search where you provide call-back that resolves the ambiguities in case
of multiple paths.
CONSTRUCTOR
The constructor should be used only by Config::Model::Node.
Methods
get_searchable_elements
Return the list of elements found in model that can be searched in the configuration tree.
prepare
Parameters: "(element => ...)"
Prepare the searcher to look for the element passed in the argument. Returns the searcher
object (i.e. $self).
reset
Re-initialize the search engine to redo the search from start
searched
Returns the searched element name.
Manual search
next_step
Returns an array (or a ref depending on context) containing the next possible step to find
the element you're looking for. The array ref can contain 1 or more elements.
If the array ref is empty, you can get the target element with "current_object".
next_choice
Returns an array ref containing the next non-obvious choice to find the element you're
looking for.
If the array ref is empty, you can get the target element with "current_object".
choose
Parameters: "( <chosen_element_name> )"
Tell the search engine your choice. The chosen element name must be one of the
possibilities given by "next_step".
current_object
Returns the object where the search engine is. It can be a node, a list, a hash, or a leaf
element.
Automatic search
auto_choose
Parameters: "( element_callback, id_call_back)"
Finds the searched element with minimal user interaction.
"element_callback" is called when the search engine finds a node where more than one
element can lead to the searched item.
"id_call_back" is called when the search engine finds a hash element or a list element
which contain no or more than 1 elements. In this case the call-back returns an id that is
used by the search engine to get the target element.
Both call-back arguments are:
• The current object (as returned by "current_object")
• A list of possible choices
For instance, your callback can be :
my $id_cb = sub {
my ($object,@choices) = @_ ;
....
return $choice[1] ;
}
Both call-back are expected to return a scalar value that is either:
• An element name
• An id valid for the list or hash element returned by "current_object".
AUTHOR
Dominique Dumont, (ddumont at cpan dot org)
SEE ALSO
Config::Model, Config::Model::Node, Config::Model::AnyId, Config::Model::ListId,
Config::Model::HashId, Config::Model::Value,
AUTHOR
Dominique Dumont
COPYRIGHT AND LICENSE
This software is Copyright (c) 2005-2022 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999