.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::Model::SearchElement 3pm"
.TH Config::Model::SearchElement 3pm "2023-08-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Model::SearchElement \- Search an element in a configuration model
.SH "VERSION"
.IX Header "VERSION"
version 2.153
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Config::Model;
\&
\& # define configuration tree object
\& my $model = Config::Model\->new;
\&  $model\->create_config_class(
\&    name    => "Foo",
\&    element => [
\&        [qw/foo bar/] => {
\&            type       => \*(Aqleaf\*(Aq,
\&            value_type => \*(Aqstring\*(Aq
\&        },
\&    ]
\& );
\& $model \->create_config_class (
\&    name => "MyClass",
\&
\&    element => [
\&
\&        [qw/foo bar/] => {
\&            type       => \*(Aqleaf\*(Aq,
\&            value_type => \*(Aqstring\*(Aq
\&        },
\&        hash_of_nodes => {
\&            type       => \*(Aqhash\*(Aq,     # hash id
\&            index_type => \*(Aqstring\*(Aq,
\&            cargo      => {
\&                type              => \*(Aqnode\*(Aq,
\&                config_class_name => \*(AqFoo\*(Aq
\&            },
\&        },
\&    ],
\& ) ;
\&
\& my $inst = $model\->instance(root_class_name => \*(AqMyClass\*(Aq );
\&
\& my $root = $inst\->config_root ;
\&
\& # put data
\& my $step = \*(Aqfoo=FOO hash_of_nodes:fr foo=bonjour \-
\&   hash_of_nodes:en foo=hello \*(Aq;
\& $root\->load( step => $step );
\&
\& # create searcher for manual search
\& my $searcher = $root\->searcher();
\&
\& # looking for foo element in the tree
\& $searcher \-> prepare (element => \*(Aqfoo\*(Aq) ;
\& my @next = $searcher\->next_step() ;
\&
\& print "next possible steps: @next\en";
\& # next possible steps: foo hash_of_nodes
\&
\& # Looking for foo below hash_of_nodes
\& $searcher\->choose(\*(Aqhash_of_nodes\*(Aq) ;
\& @next = $searcher\->next_step() ;
\&
\& print "next possible steps: @next\en";
\& # next possible steps: en fr
\&
\& # Looking for foo below fr
\& $searcher\->choose(\*(Aqfr\*(Aq) ;
\& @next = $searcher\->next_step() ;
\&
\& print "next possible steps: @next\en";
\& # next possible steps: foo
\&
\& # last step
\& $searcher\->choose(\*(Aqfoo\*(Aq) ;
\& my $target = $searcher\->current_object;
\&
\& print "Found \*(Aq",$target\->location,"\*(Aq\en";
\& # Found \*(Aqhash_of_nodes:fr foo\*(Aq
\&
\& # automatic search setup
\& my $element_call_back = sub { return \*(Aqhash_of_nodes\*(Aq ;} ;
\& my $id_call_back      = sub { return \*(Aqen\*(Aq ;} ;
\&
\& $searcher\->reset ;
\& $target = $searcher\->auto_choose($element_call_back, $id_call_back) ;
\&  print "Automatic search found \*(Aq",$target\->location,"\*(Aq\en";
\& # Automatic search found \*(Aqhash_of_nodes:en foo\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules provides a way to search for a configuration element in a
configuration tree by exploring the configuration model.
.PP
For instance, suppose that you have a xorg.conf model and you know
that you need to tune the \f(CW\*(C`MergedXinerama\*(C'\fR 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.
.PP
This class should be invaluable to construct interactive user interfaces.
.PP
This module provides 2 search modes:
.IP "\(bu" 4
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.
.IP "\(bu" 4
An automatic search where you provide call-back that resolves the
ambiguities in case of multiple paths.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
The constructor should be used only by Config::Model::Node.
.SH "Methods"
.IX Header "Methods"
.SS "get_searchable_elements"
.IX Subsection "get_searchable_elements"
Return the list of elements found in model that can be searched in the
configuration tree.
.SS "prepare"
.IX Subsection "prepare"
Parameters: \f(CW\*(C`(element => ...)\*(C'\fR
.PP
Prepare the searcher to look for the element passed in the argument.
Returns the searcher object (i.e. \f(CW$self\fR).
.SS "reset"
.IX Subsection "reset"
Re-initialize the search engine to redo the search from start
.SS "searched"
.IX Subsection "searched"
Returns the searched element name.
.SH "Manual search"
.IX Header "Manual search"
.SS "next_step"
.IX Subsection "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.
.PP
If the array ref is empty, you can get the target element with
\&\*(L"current_object\*(R".
.SS "next_choice"
.IX Subsection "next_choice"
Returns an array ref containing the next non-obvious choice to find
the element you're looking for.
.PP
If the array ref is empty, you can get the target element with
\&\*(L"current_object\*(R".
.SS "choose"
.IX Subsection "choose"
Parameters: \f(CW\*(C`( <chosen_element_name> )\*(C'\fR
.PP
Tell the search engine your choice. The chosen element name must be
one of the possibilities given by \*(L"next_step\*(R".
.SS "current_object"
.IX Subsection "current_object"
Returns the object where the search engine is. It can be
a node,
a list,
a hash, or
a leaf element.
.SH "Automatic search"
.IX Header "Automatic search"
.SS "auto_choose"
.IX Subsection "auto_choose"
Parameters: \f(CW\*(C`( element_callback, id_call_back)\*(C'\fR
.PP
Finds the searched element with minimal user interaction.
.PP
\&\f(CW\*(C`element_callback\*(C'\fR is called when the search engine finds a node
where more than one element can lead to the searched item.
.PP
\&\f(CW\*(C`id_call_back\*(C'\fR is called when the search engine finds a hash
element or a list element which contain \fBno\fR or \fBmore than 1\fR
elements. In this case the call-back returns an id that is
used by the search engine to get the target element.
.PP
Both call-back arguments are:
.IP "\(bu" 4
The current object (as returned by \*(L"current_object\*(R")
.IP "\(bu" 4
A list of possible choices
.PP
For instance, your callback can be :
.PP
.Vb 5
\& my $id_cb = sub {
\&    my ($object,@choices) = @_ ;
\&    ....
\&    return $choice[1] ;
\& }
.Ve
.PP
Both call-back are expected to return a scalar value that is either:
.IP "\(bu" 4
An element name
.IP "\(bu" 4
An id valid for the list or hash element returned by \*(L"current_object\*(R".
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, (ddumont at cpan dot org)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Model,
Config::Model::Node,
Config::Model::AnyId,
Config::Model::ListId,
Config::Model::HashId,
Config::Model::Value,
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2005\-2022 by Dominique Dumont.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve