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: 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 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 {}, all of which appears exclusively within the option section of Command.

children: List[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. It appears exclusively within the option section of PaxterApply.

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, at_prefix: bool = False)

Bases: paxter.core.data.Fragment

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 right after the @-symbol within the option section of the Command node or as a Fragment node within the FragmentList. It may also appear as the main argument of a Command node.

at_prefix: bool = False

Boolean indicating whether this fragment list begins with @-symbol (i.e. whether it is a part of @-expression)

children: List[Fragment]

List of Fragment instances

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, at_prefix: bool = False)

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 right after the @-symbol within the option section of the Command node or as a Fragment node within the FragmentList. It may also appear as the main argument of a Command node.

at_prefix: bool = False

Boolean indicating whether this fragment list begins with @-symbol (i.e. whether it is a part of @-expression)

enclosing: EnclosingPattern

Information of the enclosing quote pattern

inner: str

Inner string content

class paxter.core.Command(start_pos: int, end_pos: int, intro: str, intro_enclosing: paxter.core.enclosing.EnclosingPattern, 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 @,

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

• Next, it may optionally be followed by an option section surrounded by square brackets: [...].

• Finally, it may optionally be followed by a main argument section which can either be a Fragment or a Text. Note that the former would be surrounded by the enclosing brace pattern such as {...} whereas the latter by the enclosing quote pattern such as "...".

intro: str

Command introduction section

intro_enclosing: EnclosingPattern

Information of the enclosing bar pattern over the introduction section

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

Bases: Exception

Base exception specific to Paxter language ecosystem.

message: str

Error message

positions: Dict[str, 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)

Data regarding the enclosing (left and right) scope patterns.

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 starting or ending position of a token within the input text.

col: int

1-index column index value

line: int

1-index line number