..
   Please, do not edit this file, is is rendered from template-filters.rst.j2,
   and all your changes would be overwritten.

Template filters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When it comes to creating text documents, like
:ref:`custom_templates` or exporting tests, plans
and stories into ReST or Markdown, tmt relies on the well-known
`Jinja`__ package. All Jinja templating features are supported, and, on
top of `filters`__ shipped with Jinja, tmt adds several custom ones.

__ https://palletsprojects.com/p/jinja/
__ https://jinja.palletsprojects.com/en/3.1.x/templates/#filters


basename
--------

Return the last component of the given path.

.. code-block:: jinja

    # "/etc/fstab" -> "fstab"
    {{ "/etc/fstab" | basename }}

    # "/var/log/" -> "log"
    {{ "/var/log/" | basename }}


dedent
------

Remove any common leading whitespace from every line in the string.

.. code-block:: jinja

    # "foo bar" -> "foo bar"
    {{ "foo bar" | dedent }}

    # '''
    #    foo
    #    bar
    #        baz
    # '''
    #  ->
    # '''
    # foo
    # bar
    #    baz
    # '''
    {{ "\n    foo\n    bar\n        baz\n" | dedent }}


listed
------

Return a nice, human readable description of an iterable.

.. code-block:: jinja

    # [0] -> "0"
    {{ [0] | listed }}

    # [0, 1] -> "0 and 1"
    {{ [0, 1] | listed }}

    # [0, 1, 2] -> "0, 1, or 2"
    {{ [0, 1, 2] | listed(join='or') }}

    # [0, 1, 2] -> '"0", "1" and "2"'
    {{ [0, 1, 2] | listed(quote='"') }}

    # [0, 1, 2, 3] -> "0, 1, 2 and 1 more"
    {{ [0, 1, 2, 3] | listed(max=3) }}

    # [0, 1, 2, 3, 4] -> "0, 1, 2 and 2 more numbers"
    {{ [0, 1, 2, 3, 4, 5] | listed('number', max=3) }}

    # [0, 1, 2, 3, 4, 5] -> "6 categories"
    {{ [0, 1, 2, 3, 4, 5] | listed('category') }}

    # [0, 1, 2, 3, 4, 5, 6] -> "7 leaves"
    {{ [0, 1, 2, 3, 4, 5, 6] | listed("leaf", "leaves") }}


match
-----

Return `re.Match`__ if the string matches a given pattern.

Pattern is tested in "match" mode, i.e. it must match from the
beginning of the string. See :ref:`regular-expressions` description
for more details.

__ https://docs.python.org/3.9/library/re.html#match-objects

.. code-block:: jinja

     # 'foo/bar' -> 'foo/bar'
    {{ 'foo/bar' | match('foo/.*').group() }}

    # 'foo/bar' -> ''
    {{ 'foo/bar' | regex_match('foo/(.+?)/(.*)') }}

    # 'foo/bar/baz' -> 'bar'
    {{ 'foo/bar' | regex_match('foo/(.+?)/.*').group(1) }}


regex_findall
-------------

Return a list of all non-overlapping matches in the string.

If one or more capturing groups are present in the pattern, return
a list of groups; this will be a list of tuples if the pattern
has more than one group.

Empty matches are included in the result.

.. code-block:: jinja

    # '/var/log/mail.log' => ['/', '/', '/']
    {{ '/var/log/mail.log' | regex_findall('/') }}


regex_match
-----------

Return string matching a given pattern.

Pattern is tested in "match" mode, i.e. it must match from the
beginning of the string. See :ref:`regular-expressions` description
for more details.

If the string matches and pattern contains capture groups, the
first group is returned. If the string matches, but patterns
contains no capture group, the whole match is returned.
Otherwise, an empty string is returned.

.. code-block:: jinja

    # 'foo/bar' -> 'foo/bar'
    {{ 'foo/bar' | regex_match('foo/.*') }}

    # 'foo/bar' -> ''
    {{ 'foo/bar' | regex_match('foo/(.+?)/(.*)') }}

    # 'foo/bar/baz' -> 'bar'
    {{ 'foo/bar/baz' | regex_match('foo/(.+?)/.*') }}


regex_replace
-------------

Replace a substring defined by a regular expression with another string.

Return the string obtained by replacing the leftmost
non-overlapping occurrences of pattern in string by the replacement.
If the pattern isn't found, string is returned unchanged.

Backreferences in the replacement string are replaced with the
substring matched by a group in the pattern.

.. code-block:: jinja

    # 'foo/bar' -> 'foo/baz'
    {{ 'foo/bar' | regex_replace('(.+)/bar', '
/baz') }}

    # 'foo/bar' -> 'foo/bar'
    {{ 'foo/bar' | regex_replace('(.+)/baz', '
/') }}


regex_search
------------

Return string matching a given pattern.

Pattern is tested in "search" mode, i.e. it can match anywhere
in the string. See :ref:`regular-expressions` description for more
details.

If the string matches and pattern contains capture groups, the
first group is returned. If the string matches, but patterns
contains no capture group, the whole match is returned.
Otherwise, an empty string is returned.

.. code-block:: jinja

    # '  foo/bar' -> 'foo/bar'
    {{ '  foo/bar' | regex_search('foo/.*') }}

    # '  foo/bar' -> ''
    {{ '  foo/bar' | regex_search('foo/(.+?)/(.*)') }}

    # '  foo/bar/baz' -> 'bar'
    {{ '  foo/bar/baz' | regex_search('foo/(.+?)/.*') }}


search
------

Return `re.Match`__ if the string matches a given pattern.

Pattern is tested in "search" mode, i.e. it can match anywhere
in the string. See :ref:`regular-expressions` description for more
details.

__ https://docs.python.org/3.9/library/re.html#match-objects

.. code-block:: jinja

     # '  foo/bar' -> 'foo/bar'
    {{ '  foo/bar' | match('foo/.*').group() }}

    # '  foo/bar' -> ''
    {{ '  foo/bar' | regex_match('foo/(.+?)/(.*)') }}

    # '  foo/bar/baz' -> 'bar'
    {{ '  foo/bar' | regex_match('foo/(.+?)/.*').group(1) }}