NAME

Config::Model::Searcher - Search an element in a configuration model

SYNOPSIS

 use Config::Model ;

 # create your config model
 my $model = Config::Model -> new ;
 $model->create_config_class( ... ) ;

 # create instance
 my $inst = $model->instance (root_class_name => 'FooBar', 
                              instance_name => 'test1');

 # create root of config
 my $root = $inst -> config_root ;

 # create searcher for manual search
 my $searcher = $root->searcher();
 $searcher -> prepare (element => 'X') ;
 my $step1 = $searcher->next_step() ; # return possibilities
 my $obj1 = $searcher->choose($step1->[0]) ;
 my $step2 = $searcher->next_step() ; # return possibilities
 my $target = $searcher->choose($step2->[1]) ;

 # automatic search
 my $element_call_back = sub { ... ; return 'foo' ;} ;
 my $id_call_back      = sub { ... ; return 'bar' ;} ;

 $searcher->reset ;
 my $target = $searcher->auto_choose($element_call_back, $id_call_back) ;

DESCRIPTION

This modules provides a way to search for a configuration element in a configuration tree.

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 paramter in the configuration tree. This module will guide you through the tree to the(s) node(s) that contain this parameter.

This class should be invaluable to construct interactive GUIs.

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 will return you the possible paths to choose from. The user will have to choose the correct path from the available paths. Most of the time, only one possibility will be returned, so the user choice should be straightforward. In other case (more that one choice), the user will have to decide the next step.
An automatic search where you provide call-back that will resolve the ambuguities in case of multiple paths.

CONSTRUCTOR

The constructor should be used only by the Config::Model::Node manpage.

Methods

get_searchable_elements

Return the list of elements found in model that can be searched in the configuration tree.

prepare(element => ...)

Prepare the searcher to look for the element passed in the argument. Returns the searcher object (i.e. $self).

reset

Re-initialise the search engine to redo the search from start

searched

Returns the searched element name.

Manual search

`next_step()`

Returns an array ref 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( <choosen_element_name> )

Tell the search engine your choice. The choosen 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 ( element_callback, id_call_back)

Finds the searched element with minimal user interaction.

element_callback will be called when the search engine finds a node where more than one element can lead to the searched item.

id_call_back will be 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 will have return an id that will be used by the search engine to get the target element.

Both call-back arguments will be:

The current object (as returned by current_object())
A list of possible choices

For instances, your callback will 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)