myst_parser.parsers.options#

Parser for directive options.

This is a highly restricted parser for YAML, which only allows a subset of YAML to be used for directive options:

  • Only block mappings are allowed at the top level

  • Mapping keys are parsed as strings (plain or quoted)

  • Mapping values are parsed as strings (plain, quoted, literal |, folded >)

  • # Comments are allowed and blank lines

Adapted from: yaml/pyyaml

For a good description of multi-line YAML strings, see: https://stackoverflow.com/a/21699210/5033292

1.  Module Contents#

1.1.  Classes#

Position

Position of a character in a stream.

StreamBuffer

A buffer for a stream of characters.

Token

A parsed token from a directive option stream.

KeyToken

ValueToken

ColonToken

1.2.  Functions#

to_items

Parse a directive option block into (key, value) tuples.

to_tokens

Parse a directive option, and yield key/value token pairs.

tokenize

Yield tokens from a directive option stream.

1.3.  API#

class myst_parser.parsers.options.Position[source]#

Position of a character in a stream.

index: int = None#
line: int = None#
column: int = None#
class myst_parser.parsers.options.StreamBuffer(stream: str)[source]#

A buffer for a stream of characters.

Initialization

property index: int#
property line: int#
property column: int#
peek(index: int = 0) str[source]#
prefix(length: int = 1) str[source]#
forward(length: int = 1) None[source]#
get_position() myst_parser.parsers.options.Position[source]#
class myst_parser.parsers.options.Token[source]#

A parsed token from a directive option stream.

id: ClassVar[str] = '<unknown>'#
start: myst_parser.parsers.options.Position = None#
end: myst_parser.parsers.options.Position = None#
class myst_parser.parsers.options.KeyToken[source]#

Bases: myst_parser.parsers.options.Token

id: ClassVar[str] = '<key>'#
value: str = None#
style: Literal[None, ', "] = None#

The original style of the string.

class myst_parser.parsers.options.ValueToken[source]#

Bases: myst_parser.parsers.options.Token

id: ClassVar[str] = '<value>'#
value: str = None#
style: Literal[None, ', ", |, >] = None#

The original style of the string.

class myst_parser.parsers.options.ColonToken[source]#

Bases: myst_parser.parsers.options.Token

id: ClassVar[str] = '<colon>'#
exception myst_parser.parsers.options.TokenizeError(problem: str, problem_mark: myst_parser.parsers.options.Position, context: str | None = None, context_mark: myst_parser.parsers.options.Position | None = None)[source]#

Bases: Exception

clone(line_offset: int, column_offset: int) myst_parser.parsers.options.TokenizeError[source]#

Clone the error with the given line and column offsets.

myst_parser.parsers.options.to_items(text: str, line_offset: int = 0, column_offset: int = 0) Iterable[tuple[str, str]][source]#

Parse a directive option block into (key, value) tuples.

Parameters:
  • text – The directive option text.

  • line_offset – The line offset to apply to the error positions.

  • column_offset – The column offset to apply to the error positions.

Raises:

TokenizeError

myst_parser.parsers.options.to_tokens(text: str, line_offset: int = 0, column_offset: int = 0) Iterable[tuple[myst_parser.parsers.options.KeyToken, myst_parser.parsers.options.ValueToken | None]][source]#

Parse a directive option, and yield key/value token pairs.

Parameters:
  • text – The directive option text.

  • line_offset – The line offset to apply to the error positions.

  • column_offset – The column offset to apply to the error positions.

Raises:

TokenizeError

myst_parser.parsers.options.tokenize(text: str) Iterable[myst_parser.parsers.options.Token][source]#

Yield tokens from a directive option stream.