Provided by: libconfig-model-perl_2.047-1_all bug

NAME

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

VERSION

       version 2.047

SYNOPSIS

        use Config::Model;
        use Log::Log4perl qw(:easy);
        Log::Log4perl->easy_init($WARN);

        # 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 will guide 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 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 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(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( <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 ( 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)

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) 2013 by Dominique Dumont.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999