textmate_grammar.elements

Module Contents

Classes

Capture

A captured matching group.

ContentElement

The parsed grammar element.

ContentBlockElement

A parsed element with a begin and a end

Data

TOKEN_DICT

API

textmate_grammar.elements.TOKEN_DICT = None
class textmate_grammar.elements.Capture(handler: textmate_grammar.handler.ContentHandler, pattern: textmate_grammar.handler.Pattern, matching: textmate_grammar.handler.Match, parsers: dict[int, textmate_grammar.parser.GrammarParser], starting: tuple[int, int], boundary: tuple[int, int], key: str = '', **kwargs)

A captured matching group.

After mathing, any pattern can have a number of capture groups for which subsequent parsers can be defined. The Capture object stores this subsequent parse to be dispatched at a later moment.

Initialization

Initialize a new instance of the Element class.

Parameters:

  • handler – The content handler for the element.

  • pattern – The pattern used for matching.

  • matching – The match object.

  • parsers – A dictionary of grammar parsers.

  • starting – The starting position of the element.

  • boundary – The boundary position of the element.

  • key – The key for the element. Defaults to “”.

  • **kwargs –

    Additional keyword arguments.

Returns:

None

dispatch() → list[textmate_grammar.elements.Capture | textmate_grammar.elements.ContentElement]

Dispatches the remaining parse of the capture group.

This method iterates over the defined parsers for the capture group and dispatches the remaining parse based on the captured elements. It returns a list of captured elements or captures.

Returns:

A list of Capture or ContentElement objects representing the parsed elements.

class textmate_grammar.elements.ContentElement(token: str, grammar: dict, content: str, characters: dict[textmate_grammar.handler.POS, str], children: list[textmate_grammar.elements.Capture | textmate_grammar.elements.ContentElement] | None = None)

The parsed grammar element.

Initialization

Initialize a new instance of the Element class.

Parameters:

  • token – The token associated with the element.

  • grammar – The grammar associated with the element.

  • content – The content associated with the element.

  • characters – The characters associated with the element.

  • children – The children associated with the element. Defaults to None.

property children: list[textmate_grammar.elements.ContentElement]

Returns a list of children elements.

If the elements have not been dispatched yet, this method will dispatch them before returning.

Returns:

A list of ContentElement objects representing the children elements.

find(tokens: str | list[str], start_tokens: str | list[str] = '', hide_tokens: str | list[str] = '', stop_tokens: str | list[str] = '', depth: int = -1, attribute: str = '_subelements') → Generator[tuple[textmate_grammar.elements.ContentElement, list[str]], None, None]

Find content elements based on the given criteria.

The find method will return a generator that globs though the element-tree, searching for the next subelement that matches the given token.

Parameters:

  • tokens – The tokens to search for. Can be a single token or a list of tokens.

  • start_tokens – The tokens that mark the start of the search. Can be a single token or a list of tokens.

  • hide_tokens – The tokens to hide from the search results. Can be a single token or a list of tokens.

  • stop_tokens – The tokens that mark the end of the search. Can be a single token or a list of tokens.

  • depth – The maximum depth to search. Defaults to -1 (unlimited depth).

  • attribute – The attribute name to access the subelements. Defaults to “_subelements”.

Yield:

A tuple containing the found content element and the stack of tokens encountered.

Raises:

ValueError – If the input tokens and stop_tokens are not disjoint.

Returns:

None if no matching content elements are found.

findall(tokens: str | list[str], start_tokens: str | list[str] = '', hide_tokens: str | list[str] = '', stop_tokens: str | list[str] = '', depth: int = -1, attribute: str = '_subelements') → list[tuple[textmate_grammar.elements.ContentElement, list[str]]]

Find all occurrences of the specified tokens within the content element.

Parameters:

  • tokens – The tokens to search for.

  • start_tokens – The tokens that must appear before the found tokens. Defaults to “”.

  • hide_tokens – The tokens that should be hidden from the search. Defaults to “”.

  • stop_tokens – The tokens that, if found, should stop the search. Defaults to “”.

  • depth – The maximum depth to search. Defaults to -1 (unlimited depth).

  • attribute – The attribute to search within. Defaults to “_subelements”.

Returns:

A list of tuples containing the content element and the found tokens.

to_dict(depth: int = -1, all_content: bool = False, **kwargs) → dict

Converts the object to a dictionary.

Parameters:

  • depth – The depth of the conversion. Defaults to -1.

  • all_content – Whether to include all content or only the top-level content. Defaults to False.

Returns:

The converted dictionary representation of the object.

flatten() → list[tuple[tuple[int, int], str, list[str]]]

Converts the object to a flattened array of tokens per index, similarly to vscode-textmate.

Returns:

A list of tuples representing the flattened tokens. Each tuple contains: - A tuple representing the starting and ending index of the token. - The content of the token. - A list of keys associated with the token.

print(flatten: bool = False, depth: int = -1, all_content: bool = False, **kwargs) → None

Prints the current object recursively by converting it to a dictionary or a flattened array.

Parameters:

  • flatten – If True, flattens the object before printing. Defaults to False.

  • depth – The maximum depth to print. Defaults to -1 (unlimited depth).

  • all_content – If True, includes all content in the printout. Defaults to False.

  • **kwargs –

    Additional keyword arguments to be passed to the pprint function.

Returns:

None

class textmate_grammar.elements.ContentBlockElement(*args, begin: list[textmate_grammar.elements.Capture | textmate_grammar.elements.ContentElement] | None = None, end: list[textmate_grammar.elements.Capture | textmate_grammar.elements.ContentElement] | None = None, **kwargs)

Bases: textmate_grammar.elements.ContentElement

A parsed element with a begin and a end

Initialization

Initialize a new instance of the Element class.

Parameters:

  • begin – A list of Capture or ContentElement objects representing the beginning captures of the element. Defaults to None.

  • end – A list of Capture or ContentElement objects representing the ending captures of the element. Defaults to None.

  • **kwargs –

    Additional keyword arguments to be passed to the parent class constructor.

Returns:

None

property begin: list[textmate_grammar.elements.ContentElement]

Returns the list of begin elements.

If the elements have not been dispatched yet, this method will dispatch them before returning.

Returns:

The list of begin elements.

property end: list[textmate_grammar.elements.ContentElement]

Returns the end elements.

If the elements have not been dispatched yet, this method will dispatch them before returning.

Returns:

A list of end elements.

to_dict(depth: int = -1, all_content: bool = False, **kwargs) → dict

Converts the element to a dictionary representation.

Parameters:

  • depth – The depth of the conversion. Defaults to -1.

  • all_content – Whether to include all content. Defaults to False.

  • **kwargs –

    Additional keyword arguments.

Returns:

The dictionary representation of the element.