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 a recursive descent parser for Paxter language text input.

To utilize this class, provide the input text to the constructor, and the resulting parsed tree node will be generated upon instantiation.

input_text: str

Document source text

tree: paxter.core.data.FragmentList

Root node of the parsed tree

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 direct members 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 matching pair of brackets [], all of which appears only within the option section of Command.

children: List[paxter.core.data.Token]

List of Token instances

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

Bases: paxter.core.data.Token

Node type which represents an identifier, which can appear only within the option section of Command.

name: str

Identifier string name

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

Bases: paxter.core.data.Token

Node type which represents an operator, which can appear only within the option section of Command.

symbols: str

Symbol as a string of characters

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, which can appear only within the option section of Command.

value: Union[int, float]

Numerical value deserialized from the number literal

class paxter.core.FragmentList(start_pos: int, end_pos: int, children: List[paxter.core.data.Fragment], enclosing: paxter.core.enclosing.EnclosingPattern)

Bases: paxter.core.data.Token

Special intermediate node maintaining a list of fragment children nodes. Nodes of this type usually correspond to either the global-level fragments or fragments nested within enclosing brace pattern.

The enclosing brace pattern may appear as the main argument of a Command node or as a token within the option section of a Command node.

children: List[paxter.core.data.Fragment]

List of Fragment instances

enclosing: paxter.core.enclosing.EnclosingPattern

Information of the enclosing braces pattern

class paxter.core.Text(start_pos: int, end_pos: int, inner: str, enclosing: paxter.core.enclosing.EnclosingPattern)

Bases: paxter.core.data.Fragment

Text node type which does not contain nested @-expressions. Nodes of this type usually be presented as an element of FragmentList or as text wrapped within enclosing quoted pattern.

The enclosing quote pattern may appear as the main argument of a Command node, as a token within the option section of a Command node, or as a fragment element of a FragmentList node.

enclosing: paxter.core.enclosing.EnclosingPattern

Information of the enclosing quote pattern

inner: str

Inner string content

class paxter.core.Command(start_pos: int, end_pos: int, starter: str, starter_enclosing: paxter.core.enclosing.EnclosingPattern, option: Optional[paxter.core.data.TokenList], main_arg: Optional[Union[FragmentList, Text]])

Bases: paxter.core.data.Fragment

Node type representing @-expression which has the following form:

• It begins with an @ switch character.

• Then, it is immediately followed by a section called a starter which is simply a string in valid Python identifier form or a string surrounded by enclosing bar pattern: |...|.

• Next, it may optionally be followed by an option section which is a sequence of Token nodes.

• Finally, it may optionally be followed by a main argument section which can either be a FragmentList or a Text.

main_arg: Optional[Union[paxter.core.data.FragmentList, paxter.core.data.Text]]

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

option: Optional[paxter.core.data.TokenList]

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

starter: str

Command starter section

starter_enclosing: paxter.core.enclosing.EnclosingPattern

Information of the enclosing bar pattern over the starter section

Exceptions

Here are the list of exceptions raised from this library.

class paxter.core.exceptions.PaxterBaseException(message: str, **positions: paxter.core.charloc.CharLoc)

Bases: Exception

Base exception specific to Paxter language ecosystem.

message: str

Error message

positions: Dict[str, paxter.core.charloc.CharLoc]

A mapping from position name to LineCol position data

class paxter.core.exceptions.PaxterConfigError(message: str, **positions: paxter.core.charloc.CharLoc)

Bases: paxter.core.exceptions.PaxterBaseException

Exception for configuration error.

class paxter.core.exceptions.PaxterSyntaxError(message: str, **positions: paxter.core.charloc.CharLoc)

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.charloc.CharLoc)

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.EnclosingPattern(left: str, right: str = None)

Information regarding the enclosing (left and right) patterns for a particular scope of string data.

left: str

The left (i.e. opening) pattern enclosing the scope

right: str = None

The right (i.e. closing) pattern enclosing the scope

class paxter.core.GlobalEnclosingPattern

Specialized scope pattern just for global-level fragment list.

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

The position (starting or ending) of a token within the input text useful for line and column information in error messages.

col: int

1-index column index value

line: int

1-index line number