Shakespearelang

https://github.com/zmbc/shakespearelang
Admin
Shakespearelang is a domain-specific language that allows users to write programs in the style of...
Tokens:3,497
Snippets:21
Trust Score:7.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install shakespearelang

Source: https://github.com/zmbc/shakespearelang/blob/main/README.rst

Installs the shakespearelang interpreter using pip. This is the standard method for installing Python packages.

```shell
pip install shakespearelang
```

--------------------------------

### Install Dependencies with Poetry

Source: https://github.com/zmbc/shakespearelang/blob/main/CONTRIBUTING.md

Installs project dependencies and sets up the virtual environment using Poetry.

```shell
poetry install
```

--------------------------------

### Install shakespearelang

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Installs the shakespearelang package using pip, making the interpreter and its commands available in your Python environment.

```bash
python -m pip install shakespearelang
```

--------------------------------

### First SPL Play Example

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

A basic 'first_play.spl' file demonstrating the structure of a Shakespeare Programming Language play, including character declarations, acts, scenes, and dialogue.

```spl
A New Beginning.

Hamlet, a literary/storage device.
Juliet, an orator.

                    Act I: The Only Act.

                    Scene I: The Prince's Speech.

[Enter Hamlet and Juliet]

Juliet: Thou art the sum of an amazing healthy honest noble peaceful
        fine Lord and a lovely sweet golden summer's day. Speak your
        mind!

[A pause]

Juliet: Thou art the sum of thyself and a King. Speak your mind!

        Thou art the sum of an amazing healthy honest hamster and a golden
        chihuahua. Speak your mind!

[Exeunt]
```

--------------------------------

### Run Tests with Tox for Multiple Python Versions

Source: https://github.com/zmbc/shakespearelang/blob/main/CONTRIBUTING.md

Runs tests across multiple Python versions using tox. Requires all target Python versions to be installed.

```shell
poetry run tox
```

--------------------------------

### Debugger Console: Modifying Character Value

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Example of interacting with the shakespearelang debugger console to modify a character's value.

```bash
>> Juliet: Thou art the sum of thyself and a King.
Hamlet set to 73
>>
```

--------------------------------

### Shakespeare CLI Commands Reference

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/CLI.md

This section details the primary commands and their structure within the shakespeare CLI. It outlines the main entry point and how to access further help.

```APIDOC
shakespeare
  This is a full reference for `shakespeare` commands and usage. The same information is
available by using the option `--help` on the CLI commands themselves.

Usage:
  shakespeare <command> [OPTIONS]

Commands:
  help        Show this program's help message.
  run         Run a shakespeare script.
  test        Test a shakespeare script.
  version     Show the shakespeare version.

Options:
  --install-completion  Install dependencies for completion
  --show-completion     Show completion for this script
  --help                Show this program's help message and exit.
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/zmbc/shakespearelang/blob/main/CONTRIBUTING.md

Executes the project's test suite using pytest.

```shell
poetry run pytest
```

--------------------------------

### Debugger Console Commands

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Lists the available commands within the shakespearelang interactive debugger console: 'next', 'continue', 'quit', and 'exit'.

```markdown
- `next` executes the next sentence or event in the play, returning you to the interactive console afterwards.
- `continue` continues running the play--it will not stop again unless it hits another breakpoint.
- `quit` or `exit` stop execution of the play completely.
```

--------------------------------

### Format Code with Black

Source: https://github.com/zmbc/shakespearelang/blob/main/CONTRIBUTING.md

Applies consistent code formatting to the project using the Black formatter.

```shell
black .
```

--------------------------------

### Reference SPL Implementation (SPL-to-C)

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Details on the reference implementation of SPL, which is an SPL-to-C source-to-source compiler. It notes a dependency on an older version of `flex` for compilation.

```bash
# Download link for the reference implementation
# http://shakespearelang.sf.net/download/spl-1.2.1.tar.gz

# Note on flex dependency:
# On Ubuntu, use the 'flex-old' package to downgrade flex to version 2.5.4.
# Example command (if flex-old is available):
sudo apt-get install flex-old
```

--------------------------------

### Run an SPL Play

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Executes an SPL play file using the shakespearelang interpreter from the command line.

```bash
$ shakespeare run first_play.spl
```

--------------------------------

### Shakespeare Console Usage

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

This snippet demonstrates how to open the ShakespeareLang console for interactive use, either with an existing play or in an empty context.

```bash
shakespeare console
# or simply
shakespeare
```

--------------------------------

### ShakespeareLang Python API Classes

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/API.md

Provides programmatic access to the Shakespeare interpreter's core functionalities. This includes the main Shakespeare class for execution, Settings for configuration, and specific error classes for handling exceptions during parsing and runtime.

```APIDOC
shakespearelang.Shakespeare:
  Description: The main class for interacting with the Shakespeare interpreter.
  Usage: Instantiate this class to create an interpreter instance and execute SPL plays.
  Methods:
    - __init__(settings: Settings = None):
        Initializes the Shakespeare interpreter.
        Parameters:
          - settings: An optional Settings object to configure the interpreter.
    - load_play(play_content: str):
        Loads an SPL play from a string.
        Parameters:
          - play_content: A string containing the SPL play.
    - run_play():
        Executes the loaded SPL play.
        Returns: The result of the play execution.
    - get_output():
        Retrieves the output generated during play execution.
        Returns: A string containing the interpreter's output.

shakespearelang.Settings:
  Description: Manages the configuration settings for the Shakespeare interpreter.
  Usage: Create an instance of Settings to customize interpreter behavior.
  Attributes:
    - debug (bool): Enables or disables debug mode.
    - log_level (str): Sets the logging level (e.g., 'INFO', 'DEBUG').

shakespearelang.ShakespeareError:
  Description: Base class for all ShakespeareLang-specific errors.

shakespearelang.ShakespeareParseError:
  Description: Raised when there is an error parsing an SPL play.
  Inherits from: shakespearelang.ShakespeareError

shakespearelang.ShakespeareRuntimeError:
  Description: Raised when an error occurs during the runtime execution of an SPL play.
  Inherits from: shakespearelang.ShakespeareError
```

--------------------------------

### Spl (Python SPL-to-C Compiler)

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Details on the 'Spl' project, a compiler that translates SPL to C, implemented in Python.

```python
# GitHub repository for the Spl project:
# https://github.com/drsam94/Spl
```

--------------------------------

### Debug an SPL Play

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Runs an SPL play with the shakespearelang debugger enabled, allowing for interactive debugging at breakpoints.

```bash
$ shakespeare debug first_play.spl
```

--------------------------------

### Compile Grammar Changes

Source: https://github.com/zmbc/shakespearelang/blob/main/CONTRIBUTING.md

Compiles grammar changes from the EBNF file into Python code using a script. This is necessary after modifying the grammar definition.

```shell
./scripts/compile_grammar.sh
```

--------------------------------

### Debugger Console: Inspecting State

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Using the 'state' command in the shakespearelang debugger console to view the current status of characters and global variables.

```bash
>> state
global boolean = False
on stage:
  Hamlet = -1 ()
  Juliet = 0 ()
off stage:
```

--------------------------------

### Lingua::Shakespeare (Perl Source Filter)

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Information about Lingua::Shakespeare, a source filter implementation of SPL written in Perl.

```perl
# Access Lingua::Shakespeare documentation via CPAN:
# http://search.cpan.org/dist/Lingua-Shakespeare/lib/Lingua/Shakespeare.pod
```

--------------------------------

### horatio (Javascript Interpreter)

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Information about 'horatio', an interpreter for the Shakespeare Programming Language written in Javascript.

```javascript
# GitHub repository for the horatio interpreter:
# https://github.com/mileszim/horatio
```

--------------------------------

### Debugger Console: Inspecting a Single Character

Source: https://github.com/zmbc/shakespearelang/blob/main/docs/index.md

Viewing the state of a specific character ('Hamlet') within the shakespearelang debugger console.

```bash
>> Hamlet
-1 ()
>> Juliet: Remember thyself!
Hamlet pushed -1
>> Hamlet
-1 (-1)
```
Tokens:
Raw