.. -*- 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 "normal" AlgPseudocode lexer yields an error token for the code block
below;
`Sphinx`_ warns about this and---as a consequence---suppresses highlighting
for this code block completely:

.. code-block:: none

   \nonexisting{TEST}

With a custom AlgPseudocode lexer that has ``prohibit_raiseonerror_filter``
activated the output in `Sphinx`_ is as:

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

   \nonexisting{TEST}


With the "errortogenericerror" filter the very same block is highlighted
as:

.. code-block:: genericerror-algpseudocode

   \nonexisting{TEST}

The above custom lexer has been defined for `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.


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`_.