---
name: "Config::Model::Role::Grab"
section: "3pm"
platform: "linux"
package: "libconfig-model-perl"
version: "2.155-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Config::Model::Role::Grab"
---

# Config::Model::Role::Grab(3pm)

Role to grab data from elsewhere in the tree

## NAME

Config::Model::Role::Grab - Role to grab data from elsewhere in the tree

## VERSION

version 2.155

## SYNOPSIS

```
  $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');
```

## DESCRIPTION

Role used to let a tree item (i.e. node, hash, list or leaf) to grab another item or value from the configuration tree using a path (a bit like an xpath path with a different syntax).

## METHODS

### grab

Grab an object from the configuration tree.

Parameters are:

- "steps" (or "step")

  A string indicating the steps to follow in the tree to find the required item. (mandatory)

- "mode"

  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"` is returned. When set to `"loose"`, grab returns undef in case of problem. (default is `"strict"`)

- "type"

  Either `"node"`, `"leaf"`, `"hash"` or `"list"` or an array ref containing these values. Returns only an object of requested type. Depending on `"strict"` value, `"grab"` either throws an exception or returns the last object found with the requested type. (optional, default to `"undef"`, which means any type of object)

  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 element are created when requested by the passed steps. (default is 1).

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

The `"steps"` parameters 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.

- xxx

  Go down using `"xxx"` element.

- xxx:yy

  Go down using `"xxx"` element and id `"yy"` (valid for hash or list elements)

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

### grab\_value

Like "grab", but returns the value of a leaf or check\_list object, not just the leaf object.

`"grab_value"` raises an exception if following the steps ends on anything but a leaf or a check\_list.

### grab\_annotation

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

### grab\_root

Returns the root of the configuration tree.

### 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

## 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
```