.. _functions:

****************
Functions Syntax
****************

The DSL contains several functions that can be used to perform non-search operations. For example, functions can be used to check if an object exist, or to automatically extract categories from a piece of text. 

.. note::
   The DSL supports `UTF-8 <https://en.wikipedia.org/wiki/UTF-8>`_ encoded search terms. See also the :ref:`FAQs <faq-queries-encoding>`.


.. jinja:: fun_expression_specs

    .. _function-syntax:

    Basic functions structure
    =========================

    Each function call starts with a function name followed by parenthesis, in between which arguments are placed, separated by commas.

    For example, calling function `extract_grants` looks like this:

    .. code-block:: none

      extract_grants  ("R01HL117329", fundref="100000050")
      -------------------------------------------------------
      <function name>:(positional arguments, named arguments)

    The DSL supports two types of arguments:

        Positional Arguments
            These are placed without any name. They are just values. These are completely optional and can be replaced by
            named arguments. Their purpose is mainly to simplify calling functions with just one or two arguments,
            by omitting the argument name.

        Named Arguments
            Named arguments are always put *after* positional arguments and their order is not important.
            In the example above, one could also write `extract_grants(fundref="100000050", grant_number="R01HL117329")`.


    Arguments can be of various type, for example string or integer. See below for the full list of supported functions.


    .. _supported-call-functions:

    {% for name, (spec_args, description, deprecated) in CALL_FUN_EXPRESSIONS_DOCS|dictsort %}
    {% if not deprecated %}

    .. _{{ name }}:

    Function: `{{ name }}`
    ==============================================

    {{ description }}

    Arguments
    ---------

    .. list-table::
      :widths: auto
      :header-rows: 1

      * - Argument Name
        - Argument Type
        - Optional?
        {% for arg in spec_args %}
      * - ``{{ arg.name }}``
        - ``{{ arg.type }}``
        - {% if arg.optional %}**✓**{% endif %}
        {% endfor %}

    {% endif %}
    {% endfor %}