The formatter module

The Formatter uses a Theme to highlight text according to the token’s action attribute. The action is mapped to a TextFormat by the theme.

When a MetaTheme is used, a Formatter is capable of switching Theme as the MetaTheme provides a special theme for a certain embedded language.

All kinds of text formatting and/or highlighting can be implemented by using or inheriting of Formatter. If you need to convert the TextFormats from the theme to something else, you can provide a factory to Formatter to do that.

If you need more special behaviour, you can inherit from Formatter and reimplement format_ranges(), to do other things or to use a different FormatContext.

class FormatRange(pos, end, textformat)

Bases: tuple

property end

Alias for field number 1

property pos

Alias for field number 0

property textformat

Alias for field number 2

class FormatCache(theme, factory, add_window=True)

Bases: object

A FormatCache caches conversions from TextFormat to something else.

It can keep a window() TextFormat into account for sub-themes (themes that are invoked on a per-language basis), and it can adjust the formats for the sub-themed tokens with the window() format for that theme.

The factory that was given to the Formatter is used by the FormatCache to convert the TextFormat of the theme to something used by the formatter.

A Formatter keeps a FormatCache for its theme, and in the case of a MetaTheme, a FormatCache is used for every sub-theme. The FormatContext is used to switch theme, and in its default implementation it switches the FormatCache it uses.

format(action)

Return our text format for the action, caching it for later reuse.

class FormatContext(formatter)

Bases: object

A FormatContext is used during a formatting job.

It maintains the state needed to format using a MetaTheme. The only API used is the push() and pop() method, which are called by the tokens() method of MetaTheme.

The default Formatter uses the window property and format method to get the window style for the current theme and the factory that turns a standard action if the format we want.

push(language)

pop()

class Formatter(theme, factory=None)

Bases: object

A Formatter is used to format or highlight text according to a theme.

Supply the theme, and an optional factory that converts a TextFormat to something else.

theme()

Return the Theme we were instantiated with.

baseformat(role='window', state='default')

Return our textformat for the current line.

format_cache(theme)

Return a FormatCache for the Theme.

The FormatCache caches the converted textformat, optionally taking the default window style into account. And the Formatter caches the FormatCaches :-)

format_ranges(tree, start=0, end=None)

Yield FormatRange(pos, end, format) three-tuples.

The format is the value returned by Theme.textformat() for the token’s action, converted by our factory (and cached of course). Ranges with a TextFormat for which our factory returns None are skipped.