hio.base.hier.needing
=====================

.. py:module:: hio.base.hier.needing

.. autoapi-nested-parse::

   hio.base.hier.needing Module

   Provides hierarchical action support





Module Contents
---------------

.. py:class:: Need(*, expr='True', hold=None, **kwa)

   Bases: :py:obj:`hio.hioing.Mixin`


   Need is conditional callable class whose callable returns a boolean.
   The calling it evaluates a need expression. May be used as the transition
   condition of a Gact.

   Attributes::

       hold (Hold): data shared by boxwork

   Properties:
       expr (str): evaluable boolean expression.
       compiled (bool): True means ._code holds compiled ._expr; False means not yet compiled


   Hidden:
       _expr (str): evaluable boolean expression.
       _code (None|CodeType): compiled evaluable boolean expression .expr; None means not yet compiled from .expr



   Compilation Notes:
       The need returned by an ``on()`` call keeps the string expression because
       compiled code objects are not pickleable. In multiprocessing, the child
       process recompiles the expression from the string form. Keeping the string
       representation also helps debugging and introspection.

   Expression Syntax Notes:
       ``H`` is a local reference to ``self.hold`` during evaluation. Need
       expressions can use dotted hold paths directly, for example,
       ``H.root_dog.value``. This is equivalent to either
       ``self.hold["root_dog"].value`` or ``self.hold[("root", "dog")].value``.

       The expression ``H.root_dog.value > 5`` compiles and evaluates directly
       as long as ``H`` is present in locals and references a ``Hold`` instance.
       No substitution shorthand is required. Hierarchy in ``.hold`` uses
       underscore-separated keys, so Box/Boxer/Actor names may not contain
       ``_`` (enforced by the ``Renam`` regex).



   .. py:property:: expr

      Property getter for ._expr

      :returns: evaluable boolean expression.
      :rtype: expr (str)


   .. py:property:: compiled

      Property compiled

      Returns::

          compiled (bool): True means ._code holds compiled ._expr
                           False means not yet compiled


   .. py:method:: compile()

      Compile evaluable boolean expression str ._expr into compiled code
      object ._code to be evaluated at run time.
      Because code objects are not pickleable the compilation must happen
      at prep (enter) time not init time.