Welcome to pyparsing-highlighting’s documentation!

Syntax highlighting with pyparsing, supporting both HTML output and prompt_toolkit–style terminal output. The PPHighlighter class can also be used as a lexer for syntax highlighting as you type in prompt_toolkit. It is compatible with existing Pygments styles.

Requirements

Installation

pip3 install -U pyparsing-highlighting

Or, after cloning the repository on GitHub:

python3 setup.py install

Examples

The following code demonstrates the use of PPHighlighter:

from pp_highlighting import PPHighlighter
from prompt_toolkit.styles import Style
import pyparsing as pp
from pyparsing import pyparsing_common as ppc

def parser_factory(styler):
    a = styler('class:int', ppc.integer)
    return pp.delimitedList(a)

pph = PPHighlighter(parser_factory)
style = Style([('int', '#528f50')])
pph.print('1, 2, 3', style=style)

This prints out the following to the terminal:

_images/example_ints.png

The following code generates HTML:

pph.highlight_html('1, 2, 3')

The output is:

<span class="highlight"><span class="int">1</span>, <span class="int">2</span>, <span class="int">3</span></span>

There is also a lower-level API: pph.highlight('1, 2, 3') returns the following:

FormattedText([('class:int', '1'), ('', ', '), ('class:int', '2'), ('', ', '), ('class:int', '3')])

A FormattedText instance can be passed to prompt_toolkit.print_formatted_text(), along with a Style mapping the class names to colors, for display on the terminal.

PPHighlighter can also be passed to a prompt_toolkit.PromptSession as the lexer argument, which will perform syntax highlighting as you type. For an example of this, see examples/calc.py and examples/repl.py.

Module pp_highlighting

Syntax highlighting for prompt_toolkit and HTML with pyparsing.

pp_highlighting.dummy_styler(style, expr)

A drop-in replacement for PPHighlighter.styler() which merely returns a copy of the given parse expression without capturing text or applying styles. To simplify testing whether a parser factory has been passed dummy_styler(), bool(dummy_styler) is False.

Parameters:
  • style (Union[str, pygments.token.Token]) – Ignored.
  • expr (Union[str, pyparsing.ParserElement]) – Copied, unless it is a string literal, in which case it will be wrapped by pyparsing.ParserElement._literalStringClass (default pyparsing.Literal).
Returns:

pyparsing.ParserElement – A copy of the input parser element.
class pp_highlighting.PPHighlighter(parser_factory, *, pygments_styles=False)[source]

Syntax highlighting for prompt_toolkit and HTML with pyparsing.

This class can be used to highlight text via its highlight() method (for prompt_toolkit.print_formatted_text()—see the prompt_toolkit documentation for details), its highlight_html() method, and by passing it as the lexer argument to a prompt_toolkit.PromptSession.

__init__(parser_factory, *, pygments_styles=False)[source]

Constructs a new PPHighlighter.

You should supply a parser factory, a function that takes one argument and returns a parse expression. PPHighlighter will pass its styler() method as the argument (see styler() for more details). styler() modifies parse expressions to capture and style the text they match. The style argument to styler() can be either a prompt_toolkit style string or a Pygments token.

Examples

>>> def parser_factory(styler):
>>>     a = styler('class:int', ppc.integer)
>>>     return pp.delimitedList(a)
>>> pph = PPHighlighter(parser_factory)
>>> pph.highlight('1, 2, 3')
FormattedText([('class:int', '1'), ('', ', '), ('class:int', '2'),
('', ', '), ('class:int', '3')])

FormattedText instances can be passed to prompt_toolkit.print_formatted_text().

Parameters:
  • parser_factory (Callable[[Callable], pyparsing.ParserElement]) – The parser factory.
  • pygments_styles (bool) – Whether or not the parser is styled using Pygments tokens.
highlight(s)[source]

Highlights a string, returning a list of fragments suitable for prompt_toolkit.print_formatted_text().

Parameters:s (str) – The input string.
Returns:FormattedText – The resulting list of prompt_toolkit text fragments.
highlight_html(s)[source]

Highlights a string, returning HTML.

Only CSS class names are currently supported. Parts of the style string that do not begin with class: will be ignored. If there are dots in the class name, they will be turned into hyphens.

Parameters:s (str) – The input string.
Returns:str – The generated HTML.
lex_document(document)[source]

Takes a Document and returns a callable that takes a line number and returns a list of (style_str, text) tuples for that line.

XXX: Note that in the past, this was supposed to return a list
of (Token, text) tuples, just like a Pygments lexer.
print(*values, **kwargs)[source]
print(*values, sep=' ', end='\n', file=None, flush=False,
      style=None, output=None, color_depth=None,
      style_transformation=None, include_default_pygments_style=None)

Highlights and prints the values to a stream, or to sys.stdout by default. It calls prompt_toolkit.print_formatted_text() internally and takes the same keyword arguments as it (compatible with the builtin print()).

styler(style, expr)[source]

Wraps a pyparsing parse expression to capture text fragments.

styler() wraps the given parse expression, capturing the original text it matched, and returns the modified parse expression. The style argument can be either a prompt_toolkit style string or a Pygments token.

Parameters:
  • style (Union[str, pygments.token.Token]) – The style to set for this text fragment, as a string or a Pygments token.
  • expr (Union[str, pyparsing.ParserElement]) – The pyparsing parser to wrap. If a literal string is specified, it will be wrapped by pyparsing.ParserElement._literalStringClass (default pyparsing.Literal).
Returns:

pyparsing.ParserElement – The wrapped parser.
class pp_highlighting.PPValidator(parser, *, multiline=True, move_cursor_to_end=False)[source]

A prompt_toolkit Validator for pyparsing.

__init__(parser, *, multiline=True, move_cursor_to_end=False)[source]

Constructs a new PPValidator.

Parameters:
  • parser (pyparsing.ParserElement) – The parser to use for validation.
  • multiline (bool) – Whether to include the line number in the error message.
  • move_cursor_to_end (bool) – Whether to move the cursor to the end of the input if a non-pyparsing exception was raised during parsing.
validate(document)[source]

Validate the input. If invalid, this should raise a ValidationError.

Parameters:document – Document instance.

Indices and tables