Config...lement(3pm)

🌸 NAME 🌸

Config::Model::SearchElement — bestie, this is the module that goes looking for an element inside a configuration model. You want it, you found it, it's your manual page from the User Contributed Perl Documentation, and it's serving 💅

---

✨ VERSION ✨

version 2.166 — that's the one, no cap 👑

---

🎀 SYNOPSIS 🎀

Okay so here's the whole vibe in one go, literally the code, verbatim, don't touch a character:

use Config::Model;

# define configuration tree object
my $model = Config::Model->new;
 $model->create_config_class(
   name    => "Foo",
   element => [
       foo => {
           type       => 'leaf',
           value_type => 'string'
       },
       bar => '*foo',
   ]
);
$model ->create_config_class (
   name => "MyClass",

   element => [
       foo => {
           type       => 'leaf',
           value_type => 'string'
       },
       bar => '*foo',
       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 🌈

So this module is literally your tour guide through a configuration tree 🔦 It hands you a way to search for a configuration element by exploring the configuration model itself.

Picture this: you've got an xorg.conf model, and you know you need to tune the MergedXinerama parameter, but bestie — you have zero clue where in the configuration tree that thing lives. This module walks you through the tree straight to the(s) node(s) that contain that parameter. It's giving personal assistant energy fr fr 🧚

The docs are like: this class should be invaluable to construct interactive user interfaces. Iconic. 👑

It gives you 2 search modes:

• A manual search — where you get guided step by step to the element you're looking for. At each step, the module hands you the possible paths to choose from, and you pick the right one. Most of the time only one possibility comes back, so your choice is basically a no-brainer. Other times (more than one choice) you gotta decide the next step yourself. 🫶
• An automatic search — where you supply a call-back that resolves the ambiguity whenever there are multiple paths. ✨

---

🦋 CONSTRUCTOR 🦋

Heads up: the constructor should only ever be used by Config::Model::Node. Like, stay in your lane, bestie. 💅

💜 Methods 💜

get_searchable_elements

Returns the list of elements found in the model that can actually be searched in the configuration tree. Your whole searchable menu, basically. 🍓

prepare

Parameters: (element => ...)

Gets the searcher ready to look for the element you passed as the argument. Returns the searcher object (i.e. $self). Slay, chainable. ✨

reset

Re-initialize the search engine so you can redo the search from start. Fresh start energy 🔄

searched

Returns the searched element name. Simple as that, no notes. 💅

🔍 Manual search 🔍

next_step

Returns an array (or a ref, depending on context) holding the next possible step to find the element you're looking for. That 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 grab the target element with current_object. Same deal as above 💖

choose

Parameters: ( <chosen_element_name> )

Tell the search engine your choice. And listen — the chosen element name must be one of the possibilities given by next_step. Don't go rogue, bestie. 🙈

current_object

Returns the object where the search engine currently is. It can be a node, a list, a hash, or a leaf element. All the flavors 🌈

🤖 Automatic search 🤖

auto_choose

Parameters: ( element_callback, id_call_back)

Finds the searched element with minimal user interaction. Like, the laziest possible path to victory and honestly? Valid. 💅

element_callback gets called when the search engine finds a node where more than one element can lead to the searched item.

id_call_back gets called when the search engine finds a hash element or a list element which contain no elements or more than 1 element. In that case the call-back returns an id that the search engine uses 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

---

🌸 AUTHOR 🌸

Dominique Dumont, (ddumont at cpan dot org) — legend behavior 👑

---

⭐ SEE ALSO ⭐

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

(go read them, iykyk 🫶)

---

💖 AUTHOR 💖

Dominique Dumont — yes, again. Deserved, we're obsessed. ✨

---

👑 COPYRIGHT AND LICENSE 👑

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

---

and that's the whole page bestie, everything in it, nothing skipped, periodt 💅

perl v5.42.3 · 2026-07-23 · that's your source, version and date, mwah 😘 🎀🦋✨