.. _substitution:

************
Substitution
************

Substitution allows a Snippet Argument to be updated with
context-aware information. This features enables a Snippet
Argument writer to develop more generic steps and have
the Snippet Framework perform the required substitution to
successfully query the data.

Substitution can be identified by the prefix ``$``. These
variables will be replaced before any steps
execute to ensure all of the relevant information is
populated. If the Snippet Argument contains a substitution
key that is not present in the substitution dictionary, it
will be ignored. For example, if you had a regular expression
that utilized ``$``, you will not have to make any modifications
for it to be considered valid. It is best practice to encapsulate
your substitution within curly brackets, ``{}``. If you needed
to use the component distinguished name as part of a URI, the
snippet argument would be ``/path/${silo_comp_dn}/endpoint``.


.. list-table::
    :header-rows: 1
    :class: td-word-wrap

    * - Argument
      - Usage
    * - ${silo_app_id}
      - The application ID of the Dynamic Application
    * - ${silo_gmtime}
      - The timestamp for the data when saving to the database
        for the Dynamic Application
    * - ${silo_freq}
      - The poll frequency of the Dynamic Application
    * - ${silo_did}
      - The Device ID (DID) of this device/component device
    * - ${silo_ip}
      - The IP address of this component device
    * - ${silo_guid}
      - The Globally Unique Identifier (GUID) of this component device
    * - ${silo_comp_name}
      - The name of this component device
    * - ${silo_comp_dn}
      - The Unique identifier for the DCM tree of this component device
    * - ${silo_comp_uid}
      - The Unique ID of this component device
    * - ${silo_root_did}
      - The root Device ID of this component device
    * - ${silo_root_name}
      - The root Device name of this component device
    * - ${silo_root_dn}
      - The root Device DN of this component device
    * - ${silo_root_uid}
      - The root Device UID of this component device
    * - ${silo_parent_did}
      - The parent Device ID of this component device
    * - ${silo_parent_name}
      - The parent Device name of this component device
    * - ${silo_parent_dn}
      - The parent Device DN of this component device
    * - ${silo_parent_uid}
      - The parent Device UID of this component device


.. _sub_custom:

Custom Substitution
===================

.. note::

   The usage of ``self`` within custom substitution is deprecated
   and can yield unexpected results. Data accessed from ``self``
   can instead be retrieved with substitution functions utilizing
   out-of-the-box parameters.

You can write your custom substitution in the snippet code. An empty
dictionary, called ``custom_substitution``, lets you build your own
custom substitutions. Custom Substitution must utilize alpha-numeric
and underscore values as the keys or the substitution will not
occur successfully. The substitution values should either be a string
or a function that returns a string.

Custom substitution can also include functions. These functions
have the ability to request any of the out-of-the-box substitution
variables. This enables more control over how substitution works
and allows for it to be more dynamic across collections. The
substitution function must return a string or the collection
will not be processed. For example, if you need to extract
information out of ``silo_comp_dn`` for your substitution,
you would write a function that requested ``silo_comp_dn`` and
return the processed result.

.. note::

   Parameters in the function signature should only use non-special
   characters for the substitution. If ``$`` and ``{}``
   are included in the function signature a syntax error will
   prevent any collections that utilize the snippet from
   collecting.


Example: String Substitution
----------------------------
In this example we want to add the substitution key, ``sub_key``
with a substitution value of ``sub value``. An example Snippet
Argument to consume this would be

.. code-block:: yaml

   low_code:
     version: 2
     steps:
      - static_value: ${sub_key}


.. literalinclude:: ../_static/example_snippet_sub_str.txt
   :language: python
   :emphasize-lines: 11


Example: Function Substitution
------------------------------
In this example we want to add the substitution key, ``new_sub_func``
that performs an operation against ``silo_comp_dn`` and returns
the computed value. An example Snippet Argument to consume this
would be

.. code-block:: yaml

   low_code:
     version: 2
     steps:
      - static_value: ${new_sub_func}

.. literalinclude:: ../_static/example_snippet_sub_func.txt
   :language: python
   :emphasize-lines: 11-12,15