48 lines
1.7 KiB
ReStructuredText
48 lines
1.7 KiB
ReStructuredText
.. -*- mode: rst -*-
|
|
|
|
=======
|
|
Filters
|
|
=======
|
|
|
|
.. versionadded:: 0.7
|
|
|
|
Transforming a stream of tokens into another stream is called "filtering" and is
|
|
done by filters. The most common example of filters transform each token by
|
|
applying a simple rules such as highlighting the token if it is a TODO or
|
|
another special word, or converting keywords to uppercase to enforce a style
|
|
guide. More complex filters can transform the stream of tokens, such as removing
|
|
the line indentation or merging tokens together. It should be noted that pygments
|
|
filters are entirely unrelated to Python's `filter
|
|
<https://docs.python.org/3/library/functions.html#filter>`_.
|
|
|
|
An arbitrary number of filters can be applied to token streams coming from
|
|
lexers to improve or annotate the output. To apply a filter, you can use the
|
|
`add_filter()` method of a lexer:
|
|
|
|
.. sourcecode:: pycon
|
|
|
|
>>> from pygments.lexers import PythonLexer
|
|
>>> l = PythonLexer()
|
|
>>> # add a filter given by a string and options
|
|
>>> l.add_filter('codetagify', case='lower')
|
|
>>> l.filters
|
|
[<pygments.filters.CodeTagFilter object at 0xb785decc>]
|
|
>>> from pygments.filters import KeywordCaseFilter
|
|
>>> # or give an instance
|
|
>>> l.add_filter(KeywordCaseFilter(case='lower'))
|
|
|
|
The `add_filter()` method takes keyword arguments which are forwarded to
|
|
the constructor of the filter.
|
|
|
|
To get a list of all registered filters by name, you can use the
|
|
`get_all_filters()` function from the `pygments.filters` module that returns an
|
|
iterable for all known filters.
|
|
|
|
If you want to write your own filter, have a look at :doc:`Write your own filter
|
|
<filterdevelopment>`.
|
|
|
|
|
|
Builtin Filters
|
|
===============
|
|
|
|
.. pygmentsdoc:: filters
|