``template`` / ``process_template`` section
===========================================

Configuration templates are reusable snippets of config lines. They are mainly
used to avoid repeating common process settings.

syntax::

  TEMPLATE_SECTION := ("template " | "process_template ") + TEMPLATE_NAME + "\n" + TEMPLATE_LINE*
  TEMPLATE_NAME := NAME | NAME "(" ARGUMENT_DEF* ")"

example:

.. code-block:: lnc

  template shell_with_home(home_dir, cmd="")
  environment: HOME=%(home_dir)
  command: %(cmd)

  process demo
  use_template: shell_with_home("/tmp/demo", "echo hello")

Both section headers, ``template`` and ``process_template``, are accepted by
the parser and currently behave the same.

Template contents
-----------------

The body of a template is not interpreted when the template is defined. Instead,
its ``key: value`` lines are stored verbatim and replayed later when another
configuration object uses the template via ``use_template: ...``.

This means a template can contain the same kinds of lines that the target
object would normally accept. In practice this is primarily useful for process
settings, but the mechanism itself is generic.

Template arguments
------------------

Templates may declare positional parameters:

.. code-block:: lnc

  template run_on(node_name, cmd)
  node: %(node_name)
  command: %(cmd)

Within the template body, occurrences of ``%(argument_name)`` are replaced by
the bound argument values when the template is applied.

Default values are supported:

.. code-block:: lnc

  template shell_with_home(home_dir="/tmp", cmd="")

If a call provides fewer values than the template declares, the remaining
parameters use their defaults.

Using templates
---------------

Templates are applied with ``use_template: ...``. This is documented in more
detail in :doc:`config_process`, but the important behavior is:

* the referenced template name is resolved relative to the current
  ``push_name_prefix`` scope
* applying a template replays its stored config lines as if they had been
  written directly at the point of use
* later config lines can still overwrite settings introduced by a template
* templates can be applied indirectly through
  ``add_process_default_template: ...`` directives or host-local
  ``add_process_default_template: ...`` host settings