.. -*- coding: utf-8; indent-tabs-mode: nil; -*-

.. _filters:

*********
 Filters
*********

.. only:: html

   .. contents::

The package contains the following filters:

.. raw:: latex

   {\footnotesize

.. include:: filterlist.rst

.. raw:: latex

   }

The :ref:`AlgPseudocode lexer <lexer-algpseudocode>` by default yields an
error token for the code block below because it encounters an unknown command.
When used within `Sphinx`_ it warns about this
and---as a consequence---suppresses highlighting for this code block
completely (see also :ref:`this note <note-raiseonerror-filter>`):

.. code-block:: none

   \nonexisting{TEST}

This may be changed by using a custom AlgPseudocode lexer that has
the ``prohibit_raiseonerror_filter`` lexer option enabled.
Then the the output in `Sphinx`_ is as follows:

.. code-block:: no-raiseonerror-algpseudocode

   \nonexisting{TEST}


Alternatively---with the "errortogenericerror" filter applied the very same
block is highlighted as:

.. code-block:: genericerror-algpseudocode

   \nonexisting{TEST}

The above custom lexer is to be defined in `Sphinx`_ using:

.. code-block:: python

   import functools
   from pygments_lexer_pseudocode2.filters import ErrorToGenericErrorTokenFilter
   from pygments_lexer_pseudocode2.lexers.algpseudocode import AlgPseudocodeLexer

   def setup(app):
       app.add_lexer(
           "genericerror-algpseudocode",
           functools.partial(
               AlgPseudocodeLexer,
               filters=[ErrorToGenericErrorTokenFilter]))


.. _tokenreplacefilter:

TokenReplaceFilter
==================

:Name: tokenreplace
:Filter Options:
   ``replacements``
     **Type:** :py:class:`dict[str | pygments.token._TokenType, str | pygments.token._TokenType]`

     A map from tokens to their replacements.

   ``token_from``
     **Type:** :py:class:`str` or :py:class:`pygments.token._TokenType`

     The name of a token type (like ``Error``) or a token object
     (like :py:class:`pygments.token.Token.Error`).

     If given the `token_to` options is required and `replacements` will be
     augmented with their respective values.

   ``token_to``
     **Type:** :py:class:`str` or :py:class:`pygments.token._TokenType`

     The name of a token type (like ``Generic.Error``) or a token object
     (like :py:class:`pygments.token.Token.Generic.Error`).

     This option is required if `token_from` is given.

Replace all token types given as `replacements` keys or in `token_from`
with the token types given in `replacements` values or in `token_to`.

The values in the token stream are retained.

All :py:class:`str` types in any of the filter options are converted to
real tokens using `Pygments`_  function
:py:func:`pygments.token.string_to_tokentype`.


ErrorToGenericErrorTokenFilter
==============================

:Name: errortogenericerror
:Filter Options: none

Replace all :py:class:`pygments.token.Token.Error` tokens in a stream by
:py:class:`pygments.token.Token.Generic.Error` tokens.

The filter is implemented as an application of the `TokenReplaceFilter`_.