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

       Dominique Dumont

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  morethan1 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".

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

       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

perl v5.40.0                                       2024-11-30                  Config::Model::SearchElement(3pm)

       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.

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.

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.

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

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

        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'

       version 2.155