View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Dominique Dumont > Config-Model > Config::Model::SearchElement



Annotate this POD


View/Report Bugs
Module Version: 2.123   Source  


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


version 2.123


 use Config::Model;

 # define configuration tree object
 my $model = Config::Model->new;
    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'


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:


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

Methods ^


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).


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


Returns the searched element name.

Manual search ^


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()".


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( <chosen_element_name> )

Tell the search engine your choice. The chosen element name must be one of the possibilities given by "next_step()".


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 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:

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:


Dominique Dumont, (ddumont at cpan dot org)


Config::Model, Config::Model::Node, Config::Model::AnyId, Config::Model::ListId, Config::Model::HashId, Config::Model::Value,


Dominique Dumont


This software is Copyright (c) 2005-2018 by Dominique Dumont.

This is free software, licensed under:

  The GNU Lesser General Public License, Version 2.1, February 1999
syntax highlighting: