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

After cloning the repository:

python3 setup.py install

Examples

The following code demonstrates the use of PPHighlighter:

from pp_highlighting import PPHighlighter
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)
pph.highlight('1, 2, 3')

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 also has a highlight_html() method which returns the generated HTML as a string.

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 pp_highlighting/examples/calc.py and pp_highlighting/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 if 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.

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. You must add parse actions to the modified parse expression with addParseAction() instead of setParseAction(), or it will stop capturing text. 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