Core API Reference

Paxter language package provides the following core functionality.

Parsing

This class implements the parser for Paxter language.

class paxter.core.ParseContext(input_text: str)

Implements recursive descent parser for Paxter language.

Below is how to utilize this class:

input_text = 'Hello @name'
tree = ParseContext(input_text).parse()

input_text: str

Document source text

parse() → paxter.core.data.FragmentList

Parses the already provided input text starting from the beginning. This method is expensive and should not be called more than once.

Data Definitions

The result of the parsing yields the parsed tree consisting of the following classes.

class paxter.core.Token(start_pos: int, end_pos: int)

Base class for all types of nodes to appear in Paxter document tree.

end_pos: int

The index right after the ending position of the token.

start_pos: int

The index of the starting position of the token.

class paxter.core.Fragment(start_pos: int, end_pos: int)

Bases: paxter.core.data.Token

Subtypes of nodes in Paxter document tree that is allowed to appear as elements of FragmentList.

class paxter.core.TokenList(start_pos: int, end_pos: int, children: List[paxter.core.data.Token])

Bases: paxter.core.data.Token

Node type which represents a sequence of tokens wrapped under a pair of parentheses (), brackets [], or braces {}. It appears exclusively within the option section of PaxterApply.

children: List[Token]

A list of Token.

class paxter.core.Identifier(start_pos: int, end_pos: int, name: str)

Bases: paxter.core.data.Token

Node type which represents an identifier. It can appear at the identifier part of or within the option section of PaxterApply.

name: str

String containing the name of the identifier

class paxter.core.Operator(start_pos: int, end_pos: int, symbol: str)

Bases: paxter.core.data.Token

Node type which represents an operator. It appears exclusively within the option section of PaxterApply.

symbol: str

String containing the operator symbol

class paxter.core.Number(start_pos: int, end_pos: int, value: Union[int, float])

Bases: paxter.core.data.Token

Node type which represents a number recognized by JSON grammar. It appears exclusively within the option section of PaxterApply.

value: Union[int, float]

Numerical value deserialized from the number token

class paxter.core.FragmentList(start_pos: int, end_pos: int, children: List[paxter.core.data.Fragment], scope_pattern: paxter.core.scope_pattern.ScopePattern, is_command: bool = False)

Bases: paxter.core.data.Fragment

Special intermediate node maintaining a list of fragment children nodes. This usually corresponds to global-level fragments or fragments nested within braces following the @-command.

children: List[Fragment]

A list of Fragment

is_command: bool = False

Boolean indicating whether this fragment list begins with @-symbol

scope_pattern: ScopePattern

Information of the enclosing braces pattern

class paxter.core.Text(start_pos: int, end_pos: int, inner: str, scope_pattern: paxter.core.scope_pattern.ScopePattern, is_command: bool = False)

Bases: paxter.core.data.Fragment

Text node type which does not contain nested @-commands. It may be presented as an element of FragmentList, the main argument of PaxterApply and PaxterPhrase, or within the option section of PaxterApply.

inner: str

The string content

is_command: bool = False

Boolean indicating whether this fragment list begins with @-symbol

scope_pattern: ScopePattern

Information of the enclosing quote pattern

class paxter.core.PaxterPhrase(start_pos: int, end_pos: int, inner: str, scope_pattern: paxter.core.scope_pattern.ScopePattern)

Bases: paxter.core.data.Fragment

Node type which represents @-command and has one of the following form:

• It begins with a command switch @ and is immediately followed by a non-empty identifier. It also must unambiguously not be a PaxterApply (i.e. it is not followed by an option section or main argument section).

• It begins with a command switch @ and is immediately followed by a wrapped bar section (e.g. @|...phrase...|, @<#|...phrase...|#>).

• It begins with a command switch @ and is immediately followed by a single symbol character that is unmistakeably not a quote ", a brace {, or a bar |.

inner: str

The string content of the phrase

scope_pattern: ScopePattern

Information of the enclosing bar pattern

class paxter.core.PaxterApply(start_pos: int, end_pos: int, id: paxter.core.data.Identifier, options: Optional[paxter.core.data.TokenList], main_arg: Optional[Union[FragmentList, Text]])

Bases: paxter.core.data.Fragment

Node type which represents @-command which has the following form:

• It begins with a command switch @, and is immediately followed by a non-empty identifier.

• Then it may optionally be followed by an option section surrounded by square brackets.

• If options section is present, then it may be followed by a main argument section; however, if options is not present, then it must be followed by the main argument section.

  The main argument section, if present, can either be a FragmentList (surrounded by wrapped braces such as {...main arg...}) or a Text (surrounded by wrapped quotation marks such as "...text...").

id: Identifier

The identifier part

main_arg: Optional[MainArgument]

The main argument section at the end of expression, or None if this section is not present.

options: Optional[TokenList]

A list of tokens for the option section enclosed by [], or None if this section is not present.

Exceptions

Here are the list of exceptions raised from this library.

class paxter.core.exceptions.PaxterBaseException(message: str, **positions: paxter.core.line_col.LineCol)

Bases: Exception

Base exception specific to Paxter language ecosystem.

message: str

Error message

positions: Dict[str, LineCol]

A mapping from position name to LineCol position data

class paxter.core.exceptions.PaxterConfigError(message: str, **positions: paxter.core.line_col.LineCol)

Bases: paxter.core.exceptions.PaxterBaseException

Exception for configuration error.

class paxter.core.exceptions.PaxterSyntaxError(message: str, **positions: paxter.core.line_col.LineCol)

Bases: paxter.core.exceptions.PaxterBaseException

Exception for syntax error raised while parsing input text in Paxter language. Positional index parameters indicates a mapping from position name to its indexing inside the input text.

class paxter.core.exceptions.PaxterRenderError(message: str, **positions: paxter.core.line_col.LineCol)

Bases: paxter.core.exceptions.PaxterBaseException

Exception for parsed tree transformation error.

Other Utility Classes

Classes in this subsection is for reference only.

class paxter.core.ScopePattern(opening: str, closing: str = None)

Data regarding the opened pattern and the closed pattern of one particular scope.

closing: str = None

The closing pattern enclosing the scope

opening: str

The opening pattern enclosing the scope

class paxter.core.LineCol(input_text: dataclasses.InitVar, pos: dataclasses.InitVar)

The starting or ending position of a token within the input text.

col: int

1-index column index value

line: int

1-index line number