Config...e::Grab(3pm)

📦
version 2.166 · 8 versions
, in ubuntu stonking

🎀 Config::Model::Role::Grab — the whole vibe 💅

okay bestie, so this is a role (yes, a Perl role, we love a shared-behaviour moment) and it lives in the Config::Model universe. It's the one that lets any tree item — node, hash, list, or leaf — reach out and grab another item or value from the configuration tree by following a path. And no, it's not xpath, but it's giving xpath's cooler cousin with a different syntax. iykyk ✨

It's documented under the User Contributed Perl Documentation umbrella, so you know it's the people's manpage fr fr. 🫶

✨ VERSION ✨

version 2.166 — the current era of this icon. 👑

🌸 SYNOPSIS 🌸

here's the snack preview, exactly as it goes down:

$root->grab('foo:2 bar');
$root->grab(steps => 'foo:2 bar');
$root->grab(steps => 'foo:2 bar', type => 'leaf');
$root->grab_value(steps => 'foo:2 bar');
$root->grab_value(steps => '"a.string"'); # contains . in name -> quote

see that last one? if your name has a . in it, you quote it, no negotiation. 💅

🦋 DESCRIPTION 🦋

So the whole point: this role lets a tree item (i.e. a node, hash, list or leaf) grab another item or value out of the configuration tree using a path — kinda like an xpath path, but with a different syntax. that's it, that's the premise, and it's lowkey iconic. 🌈

💖 METHODS 💖

🌟 grab

Grab an object from the configuration tree. main character method, honestly.

Parameters are:

  • steps (or step) — a string indicating the steps to follow in the tree to find the required item. (mandatory — you cannot skip this one bestie, it's not optional and it's not cute to try)
  • mode — controls the drama level when things go wrong. When set to strict, grab throws an exception if no object is found using the passed string. When set to adaptative, the object found last is returned — for instance, for the steps good_step wrong_step, only the object held by good_step comes back. When set to loose, grab returns undef in case of problem. (default is strict — yes, it's strict by default, it said what it said 💀)
  • type — either node, leaf, hash or list, or an array ref containing these values. Returns only an object of the requested type. Depending on the strict value, grab either throws an exception or returns the last object found with the requested type. (optional, default is undef, which means any type of object — free spirit behaviour ✨)

Examples:

$root->grab(steps => 'foo:2 bar', type => 'leaf')
$root->grab(steps => 'foo:2 bar', type => ['leaf','check_list'])
  • autoadd — when set to 1, hash or list configuration elements are created when requested by the passed steps. (default is 1 — it's helpful like that 🫶)
  • grab_non_available — when set to 1, grab returns an object even if this one is not available. I.e. even if this element was warped out. (default is 0)

Now, the steps parameter is made of the following items, separated by spaces:

  • - — Go up one node
  • ! — Go to the root node.
  • !Foo — Go up the configuration tree until the Foo configuration class is found. Raise an exception if no Foo class is found when root node is reached. 😭 (like, it will yell.)
  • xxx — Go down using xxx element. Quotes must be used if the element name is not alphanumeric.
  • xxx:yy — Go down using xxx element and id yy (valid for hash or list elements). Quotes must be used if the id is not alphanumeric.
  • ?xxx — Go up the tree until a node containing element xxx is found. Then go down the tree like item xxx.
    • ?xxx:yy goes up the tree the same way. But no check is done to see if id yy key actually exists or not. Only the element xxx is considered when going up the tree. (so, uh, be aware of that ✨)

🌟 grab_value

Like grab, but returns the value of a leaf or check_list object, not just the leaf object. giving actual-data energy 💅

grab_value raises an exception if following the steps ends on anything but a leaf or a check_list. no cap.

🌟 grab_annotation

Like grab, but returns the annotation of an object. 🎀

🌟 grab_root

Returns the root of the configuration tree. short, sweet, iconic.

🌟 grab_ancestor

Parameter: a configuration class name.

Go up the configuration tree until a node using the configuration class is found. Returns the found node or undef.

Example:

# returns a Config::Model::Node object for a Systemd::Service config class
$self->grab('Systemd::Service');

👑 AUTHOR 👑

Dominique Dumont — the legend behind this whole thing. 🫶

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
okay so fr fr, remember: this is the Config...e::Grab(3pm) page, part of the User Contributed Perl Documentation, built for perl v5.42.3 and dated 2026-07-23. that's the whole tea. go grab something (respectfully). 💖✨🦋🌸💅🫶
📦 where this page comes from