.. -*- mode: rst -*-

=====================
Write your own filter
=====================

*New in Pygments 0.7.*

Writing own filters is very easy. All you have to do is to subclass
the `Filter` class and override the `filter` method. Additionally a
filter is instanciated with some keyword arguments you can use to
adjust the behavior of your filter.


Subclassing Filters
===================

As an example, we write a filter that converts all `Name.Function` tokens
to normal `Name` tokens to make the output less colorful.

.. sourcecode:: python

    from pygments.util import get_bool_opt
    from pygments.token import Name
    from pygments.filter import Filter

    class UncolorFilter(Filter):

        def __init__(self, **options):
            Filter.__init__(self, **options)
            self.class_too = get_bool_opt(options, 'classtoo')

        def filter(self, lexer, stream):
            for ttype, value in stream:
                if ttype is Name.Function or (self.class_too and
                                              ttype is Name.Class):
                    ttype = Name
                yield ttype, value

Some notes on the `lexer` argument: that can be quite confusing since it doesn't
need to be a lexer instance. If a filter was added by using the `add_filter()`
function of lexers, that lexer is registered for the filter. In that case
`lexer` will refer to the lexer that has registered the filter. It *can* be used
to access options passed to a lexer. Because it could be `None` you always have
to check for that case if you access it.


Using a decorator
=================

You can also use the `simplefilter` decorator from the `pygments.filter` module:

.. sourcecode:: python

    from pygments.util import get_bool_opt
    from pygments.token import Name
    from pygments.filter import simplefilter


    @simplefilter
    def uncolor(lexer, stream, options):
        class_too = get_bool_opt(options, 'classtoo')
        for ttype, value in stream:
            if ttype is Name.Function or (class_too and
                                          ttype is Name.Class):
                ttype = Name
            yield ttype, value

The decorator automatically subclasses an internal filter class and uses the
decorated function for filtering.