Skip to content

Python API reference#

If you want to interact with the interpreter programmatically from Python, you can do so using the public interfaces of the classes below. If you just want to write and execute SPL plays, the command line interface is likely easier.

shakespearelang.shakespeare.Shakespeare #

Interpreter for the Shakespeare Programming Language.

__init__(self, play, input_style='basic', output_style='basic') special #

Parameters:

Name Type Description Default
play Union[str, tatsu.ast.AST]

The AST or source code of the SPL play to be interpreted. Must be provided and cannot be changed after initialization of the interpreter.

required
input_style Literal['basic', 'interactive']

'basic' is the default and best for piped input. 'interactive' is nicer when getting input from a human. This is passed directly along to the Settings instance for this interpreter. To change after initialization, modify that instance at the .settings property of the interpreter.

'basic'
output_style Literal['basic', 'verbose', 'debug']

The output style to initialize the interpreter with. 'basic' is the default and outputs exactly what the SPL play generated. 'verbose' prefixes output and shows visible representations of whitespace characters. 'debug' is like 'verbose' but with debug output from the interpreter. This is passed directly along to the Settings instance for this interpreter. To change after initialization, modify that instance at the .settings property of the interpreter.

'basic'
Source code in shakespearelang/shakespeare.py
def __init__(
    self,
    play: Union[str, AST],
    input_style: Literal["basic", "interactive"] = "basic",
    output_style: Literal["basic", "verbose", "debug"] = "basic",
):
    """
    Arguments:
        play: The AST or source code of the SPL play to be interpreted. Must
            be provided and cannot be changed after initialization of the
            interpreter.
        input_style: 'basic' is the default and best for piped input.
            'interactive' is nicer when getting input from a human.
            This is passed directly along to the [Settings][shakespearelang.Settings]
            instance for this interpreter. To change after initialization,
            modify that instance at the .settings property of the interpreter.
        output_style: The output style to initialize the interpreter with.
            'basic' is the default and outputs exactly what the SPL play generated.
            'verbose' prefixes output and shows visible representations of
            whitespace characters. 'debug' is like 'verbose' but with debug output
            from the interpreter.
            This is passed directly along to the [Settings][shakespearelang.Settings]
            instance for this interpreter. To change after initialization,
            modify that instance at the .settings property of the interpreter.
    """
    self.settings = Settings(input_style, output_style)
    self.parser = shakespeareParser()
    ast = self._parse_if_necessary(play, "play")
    self.play = Play(ast)
    self.state = State(ast.dramatis_personae)

    self.current_position = 0

run(self, breakpoint_callback=<function Shakespeare.<lambda> at 0x7fead3ee7280>) #

Execute the entire SPL play, optionally pausing at breakpoints.

Parameters:

Name Type Description Default
breakpoint_callback Callable[[], NoneType]

An optional callback, to be called if a debug breakpoint is hit. After the callback returns, execution continues. The default is to do nothing.

<function Shakespeare.<lambda> at 0x7fead3ee7280>
Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
def run(self, breakpoint_callback: Callable[[], None] = lambda: None) -> None:
    """
    Execute the entire SPL play, optionally pausing at breakpoints.

    Arguments:
        breakpoint_callback: An optional callback, to be called if a debug
            breakpoint is hit. After the callback returns, execution
            continues. The default is to do nothing.
    """
    while not self.play_over():
        if isinstance(self._next_operation(), Breakpoint):
            self._advance_position()
            breakpoint_callback()
        else:
            self.step_forward()

play_over(self) #

Returns:

Type Description
bool

Whether the play has finished.

Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
def play_over(self) -> bool:
    """
    Returns:
        Whether the play has finished.
    """
    return self.current_position >= len(self.play.operations)

step_forward(self) #

Run the next event in the play.

Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
def step_forward(self) -> None:
    """
    Run the next event in the play.
    """
    operation_to_run = self._next_operation()
    if isinstance(operation_to_run, Breakpoint):
        self._advance_position()
        return

    if self.settings.output_style == "debug":
        print(
            f"----------\nat line {operation_to_run.ast_node.parseinfo.line}\n-----\n"
            + parseinfo_context(operation_to_run.ast_node.parseinfo)
            + "-----\n"
            + str(self.state)
            + "\n----------"
        )

    pos_before_operation = self.current_position
    self._run_operation(operation_to_run)
    if self.current_position == pos_before_operation:
        self._advance_position()

next_operation_text(self) #

Returns:

Type Description
str

The SPL source code of the next operation (sentence or event) to run in the play, with context before and after.

Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
def next_operation_text(self) -> str:
    """
    Returns:
        The SPL source code of the next operation (sentence or event)
        to run in the play, with context before and after.
    """
    current_operation = self._next_operation()
    return parseinfo_context(current_operation.ast_node.parseinfo)

run_event(self, event) #

Run an event in the current execution context.

Parameters:

Name Type Description Default
event Union[str, tatsu.ast.AST]

A string or AST representation of an event (line, entrance, exit, etc).

required
Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
@_parse_first_argument("event")
def run_event(self, event: Union[str, AST]) -> None:
    """
    Run an event in the current execution context.

    Arguments:
        event: A string or AST representation of an event (line, entrance,
            exit, etc).
    """
    operations = operations_from_event(event)
    for operation in operations:
        self._run_operation(operation)

run_sentence(self, sentence, character) #

Run a sentence in the current execution context.

Parameters:

Name Type Description Default
sentence Union[str, tatsu.ast.AST]

A string or AST representation of a sentence.

required
character str

The name of the character speaking the sentence.

required
Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
@_parse_first_argument("sentence")
def run_sentence(self, sentence: Union[str, AST], character: str):
    """
    Run a sentence in the current execution context.

    Arguments:
        sentence: A string or AST representation of a sentence.
        character: The name of the character speaking the sentence.
    """
    operation = operation_from_sentence(sentence, character)
    self._run_operation(operation)

evaluate_expression(self, expression, character) #

Evaluate an expression in the current execution context.

Parameters:

Name Type Description Default
expression Union[str, tatsu.ast.AST]

A string or AST representation of an expression.

required
character str

The name of the character speaking the expression.

required

Returns:

Type Description
int

The integer value of the expression.

Source code in shakespearelang/shakespeare.py
@_add_interpreter_context_to_errors
@_parse_first_argument("value")
def evaluate_expression(self, expression: Union[str, AST], character: str) -> int:
    """
    Evaluate an expression in the current execution context.

    Arguments:
        expression: A string or AST representation of an expression.
        character: The name of the character speaking the expression.

    Returns:
        The integer value of the expression.
    """
    expression = expression_from_ast(expression, character)
    return expression.evaluate(self.state)

shakespearelang.settings.Settings #

The settings of a Shakespeare interpreter. Controls how and when the interpreter does input and output.

input_style property writable #

Input style of the interpreter. 'basic' is the best for piped input. 'interactive' is nicer when getting input from a human.

output_style property writable #

Output style of the interpreter. 'basic' outputs exactly what the SPL play generated. 'verbose' prefixes output and shows visible representations of whitespace characters. 'debug' is like 'verbose' but with debug output from the interpreter.

shakespearelang.errors.ShakespeareError #

The base class for errors caused by problems in Shakespeare Programming Language code.

shakespearelang.errors.ShakespeareParseError #

An error caused by malformed Shakespeare Programming Language code. Inherits from ShakespeareError.

shakespearelang.errors.ShakespeareRuntimeError #

An error caused by Shakespeare Programming Language code that is well-formed but does some illegal operation at runtime. Inherits from ShakespeareError.