NAME

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

VERSION

       version 2.153

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

perl v5.36.0                                       2023-08-19                     Config::Model::Role::Grab(3pm)