Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::SearchEUsernContributed Perl DocConfig::Model::SearchElement(3)

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

VERSION
       version 2.140

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:

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

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

       o   The current object (as returned by "current_object")

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

       o   An element name

       o   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-2020	by Dominique Dumont.

       This is free software, licensed under:

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

perl v5.32.0			  2020-08-28   Config::Model::SearchElement(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | Methods | Manual search | Automatic search | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::SearchElement&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help