Config...Scanner(3pm)

📦

version 2.166 · 8 versions

💖 Config::Model::ObjTreeScanner 💖

okay bestie, welcome to the manual page for Config::Model::ObjTreeScanner (it lives in the Config...Scanner(3pm) slot, User Contributed Perl Documentation, and yes we're about to make it make sense). This is the little object that walks your whole config tree and pings your call-backs on every single thing it finds. so unserious of it, so useful. 💅

✨ NAME ✨

Config::Model::ObjTreeScanner — scan a config tree and fire off call-backs for each element or node. it's giving personal tour guide for your config. 🧚

🌈 VERSION 🌈

version 2.166 ✨

🦋 SYNOPSIS 🦋

okay so first you set up a model, then you build an instance, then you poke data into it, then you scan it. look:

use Config::Model ;

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

   ],
) ;

my $inst = $model->instance(root_class_name => 'MyClass' );

my $root = $inst->config_root ;

# put some data in config tree the hard way
$root->fetch_element('foo')->store('yada') ;
$root->fetch_element('bar')->store('bla bla') ;
$root->fetch_element('baz')->fetch_with_id('en')->store('hello') ;

# put more data the easy way
my $steps = 'baz:fr=bonjour baz:hr="dobar dan"';
$root->load( steps => $steps ) ;

# define leaf call back
my $disp_leaf = sub {
     my ($scanner, $data_ref, $node,$element_name,$index, $leaf_object) = @_ ;
     $$data_ref .= "disp_leaf called for '". $leaf_object->name.
       "' value '".$leaf_object->fetch."'\n";
   } ;

# simple scanner, (print all values)
my $scan = Config::Model::ObjTreeScanner-> new (
  leaf_cb => $disp_leaf, # only mandatory parameter
) ;

my $result = '';
$scan->scan_node(\$result, $root) ;
print $result ;

no cap, that's the whole vibe. define a leaf call-back, hand it over, scan the root, get your result back. periodt. 👑

🌸 DESCRIPTION 🌸

so this module builds an object that explores a configuration tree depth first. it's literally just a very thorough lil explorer. 🗺️

for every part of the config tree, the ObjTreeScanner object calls one of the subroutine references you handed it when you constructed it. (we call those a call-back or a hook, iykyk.)

call-back and hook routines get called:

for each node containing elements (which includes the root node, bestie)
for each element of a node — and that element can be a list, hash, node or leaf element
for each item contained in a node, hash or list. that item can be a leaf or another node.

to keep the exploration going, these call-backs have to call the scanner back. (like, perform another call-back.) in other words, your subroutine and the scanner are playing a little game of ping-pong 🏓 until the whole tree is fully explored. it's honestly kind of iconic.

hook routines do not have to resume the exploration, i.e. they don't need to call the scanner. that part gets handled for you once the hook routine has returned. 🫶

the scanner ships with a whole set of default call-backs for the nodes. so you literally only have to provide call-backs for the leaves. king behavior. 👑

the scan starts with a call to scan_node. the first parameter of scan_node is a ref that gets passed untouched to all call-backs. use that ref to stash whatever result you want in there. ✨

🎀 CONSTRUCTOR 🎀

new

one way or another, the ObjTreeScanner object has to be able to find all call-backs for all the items of the tree. all the possible call-backs and hooks are listed right here, bestie:

leaf callback: leaf_cb is a catch-all generic callback. all the others are specialized call-backs: enum_value_cb, integer_value_cb, number_value_cb, boolean_value_cb, string_value_cb, uniline_value_cb, reference_value_cb, file_value_cb, dir_value_cb
node callback: node_content_cb, node_dispatch_cb
node hooks: node_content_hook
element callback: all these call-backs are called on the elements of a node: list_element_cb, check_list_element_cb, hash_element_cb, node_element_cb, node_content_cb.
element hooks: list_element_hook, hash_element_hook.

you can specify your callbacks by passing a sub ref to the constructor:

$scan = Config::Model::ObjTreeScanner-> new
(
 list_element_cb => sub { ... },
 ...
)

leaf_cb callback is mandatory. the other callbacks are provided by default. so don't stress, you're covered. 💜

optional parameters:

fallback — deprecated with version 2.159. this parameter is now ignored and default callbacks are always provided. (rip to a real one, it's simply not doing anything anymore. 💀)
auto_vivify — whether to create configuration objects while scanning (default is 1).
check — "yes", "no" or "skip".

Callback prototypes

okay here's the fun part, the actual shapes of every callback. buckle up. 🎀

Leaf callback

leaf_cb is called for each leaf of the tree. the leaf callback gets called with these parameters:

($scanner, $data_ref,$node,$element_name,$index, $leaf_object)

where:

$scanner is the scanner object.
$data_ref is a reference that is first passed to the first call of the scanner. then $data_ref is relayed through the various call-backs.
$node is the node that contain the leaf.
$element_name is the element (or attribute) that contain the leaf.
$index is the index (or hash key) used to get the leaf. this may be undefined if the element type is scalar.
$leaf_object is a Config::Model::Value object.

List element callback

list_element_cb is called on all list element of a node, i.e. call on the list object itself and not in the elements contained in the list.

($scanner, $data_ref,$node,$element_name,@indexes)

@indexes is a list containing all the indexes of the list.

example:

sub my_list_element_cb {
   my ($scanner, $data_ref,$node,$element_name,@idx) = @_ ;

   # custom code using $data_ref

   # resume exploration (if needed)
   foreach my $i (@idx){
       $scanner->scan_list($data_ref,$node,$element_name,$i);
   }

   # note: scan_list and scan_hash are equivalent
}

List element hook

list_element_hook: works like the list element callback. except that the calls to scan_list are not required. this is done once the hook returns. 🫶

Check list element callback

check_list_element_cb: like list_element_cb, but called on a check_list element.

($scanner, $data_ref,$node,$element_name, index, check_list_obj)

index is always undef as a check_list cannot be contained in a hash or list (yet). (not yet bestie, not yet. 🙈)

Hash element callback

hash_element_cb: like list_element_cb, but called on a hash element.

($scanner, $data_ref,$node,$element_name,@keys)

@keys is an list containing all the keys of the hash.

example:

sub my_hash_element_cb {
   my ($scanner, $data_ref,$node,$element_name,@keys) = @_ ;

   # custom code using $data_ref

   # resume exploration
   foreach my $k (@keys) {
       $scanner->scan_hash($data_ref,$node,$element_name,$key);
   }
}

Hash element hook

hash_element_hook: works like the hash element callback. except that the calls to scan_hash are not required. this is done once the hook returns. 💅

Node content callback

node_content_cb: this call-back is called foreach node (including root node).

($scanner, $data_ref,$node,@element_list)

@element_list contains all the element names of the node.

example:

sub my_content_cb {
   my ($scanner, $data_ref,$node,@elements) = @_ ;

   # custom code using $data_ref

   # resume exploration
   foreach my $elt (@elements) {
       $scanner->scan_element($data_ref, $node,$elt);
   }
}

Node content hook

node_content_hook: this hook is called foreach node (including root node). works like the node content call-back. except that the calls to scan_element are not required. this is done once the hook returns. ✨

Dispatch node callback

node_dispatch_cb: any callback specified in the hash is called for each instance of the specified configuration class. (this may include the root node).

for instance, if you have:

node_dispach_cb => {
  ClassA => \&my_class_a_dispatch_cb,
  ClassB => \&my_class_b_dispatch_cb,
}

&my_class_a_dispatch_cb is called for each instance of ClassA and &my_class_b_dispatch_cb is called for each instance of ClassB.

they're called with the following parameters:

($scanner, $data_ref,$node,@element_list)

@element_list contains all the element names of the node.

example:

sub my_class_a_dispatch_cb = {
   my ($scanner, $data_ref,$node,@element) = @_ ;

   # custom code using $data_ref

   # resume exploration
   foreach my $elt (@elements) {
       $scanner->scan_element($data_ref, $node,$elt);
   }
}

Node element callback

node_element_cb is called for each node contained within a node (i.e not with root node). this node can be held by a plain element or a hash element or a list element:

($scanner, $data_ref,$node,$element_name,$key, $contained_node)

$key may be undef if $contained_node is not a part of a hash or a list. $element_name and $key specifies the element name and key of the the contained node you want to scan. (passed with $contained_node) note that $contained_node may be undef if auto_vivify is 0. (heads up bestie, that's a real gotcha. 👀)

example:

sub my_node_element_cb {
  my ($scanner, $data_ref,$node,$element_name,$key, $contained_node) = @_;

  # your custom code using $data_ref

  # explore next node
  $scanner->scan_node($data_ref,$contained_node);
}

💅 METHODS 💅

scan_node

parameters: ($data_r,$node)

explore the node and call either node_dispatch_cb (if the node class name matches the dispatch_node hash) or (e.g. xor) node_element_cb passing all element names.

up_cb is called once the first callback returns.

scan_element

parameters: ($data_r,$node,$element_name)

explore the element and call either hash_element_cb, list_element_cb, node_content_cb or a leaf call-back (the leaf call-back called depends on the Value object properties: enum, string, integer and so on).

scan_hash

parameters: ($data_r,$node,$element_name,$key)

explore the hash member (or hash value) and call either node_content_cb or a leaf call-back.

scan_list

parameters: ($data_r,$node,$element_name,$index)

just like scan_hash: explore the list member and call either node_content_cb or a leaf call-back.

get_keys

parameters: ($node, $element_name)

returns an list containing the sorted keys of a hash element, or returns an list containing (0.. last_index) of an list element.

throws an exception if element is not an list or a hash element. 😭 so like, be normal about it.

🌟 AUTHOR 🌟

Dominique Dumont, (ddumont at cpan dot org)

💫 SEE ALSO 💫

Config::Model, Config::Model::Node, Config::Model::Instance, Config::Model::HashId, Config::Model::ListId, Config::Model::CheckList, Config::Model::Value

🌈 AUTHOR 🌈

Dominique Dumont

okay bestie, that's part 1 wrapped up — but we're not done, there's more coming, so don't go anywhere. 🫶✨

💖 COPYRIGHT AND LICENSE 💖

okay bestie, legal era, but it's literally two sentences so we're fine 💅

This software is Copyright (c) 2005-2022 by Dominique Dumont.

periodt. that's the author, that's the years, that's the whole vibe ✨

and the licensing tea: this is free software, and it's licensed under:

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

not the regular GPL bestie, the LGPL — the Lesser one, version 2.1, dated February 1999, exactly as written, don't paraphrase it 💜

that's it!! you read the whole entire page 😭🫶 go forth and configure things, main character 🎀

source + version check, since you always ask: this is Config...Scanner(3pm) as packaged with perl v5.42.3, dated 2026-07-23 🌸 and that's the last line of the page, so we're officially done, no cap 💖

📦 where this page comes from

ubuntu stonking: libconfig-model-perl 2.166-1 · LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms