zsim-cli 0.6.1

A simulator for an assembly like toy-language.

zsim-cli

A simulator for an assembly like toy-language
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Tokenization
   • Validation
   • Simulating
   • Using interactive mode
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Implemented for the compiler building course after the winter semester 2020 on the Aachen University of Applied Sciences.
Z-Code is a simplified assembly like toy language created to prove that compiling to a temporary language like Java-Bytecode can be much easier than going from a high-level language directly to assembly.

Check out the syntax diagrams for detailed information on how the syntax of Z-Code is defined here.

Sublime syntax highlighting for Z-Code available here!

It even works on Termux!

(back to top)

Built With

zsim-cli relies heavily on the following libraries.

• Click
• pytest

(back to top)

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

• Python 3.6
  • Head over to https://python.org and install the binary suitable for your operation system. Make sure you can run it:

  python --version
  

• pip
  • Check if pip is already installed:

  pip --version
  

  • If your python installation does not come with pip pre-installed visit https://pip.pypa.io to install it and then check again.

Installation

1. Clone the repository

   git clone https://gitlab.com/justin_lehnen/zsim-cli.git
   cd zsim-cli
   

2. (Optionally) create a python virtual environment and enter it

   python -m venv venv
   # Windows
   venv/Scripts/activate.bat
   # Unix or MacOS
   source venv/bin/activate
   

3. Install using pip

   pip install -e .
   

4. Run unit tests

   pytest
   

And you're set!

(back to top)

Usage

For more examples, please refer to the Documentation

Tokenization

zsim-cli tokenize [ZCODE]

--json / --no-json

Type: Boolean Default: False

If the flag is set, the output will be in JSON format.
The JSON schema is [ { "type": "<type>", "value": "<value>" }, ... ].

Examples:

# Tokenize code in JSON
zsim-cli tokenize "LIT 7; PRT;" --json

# Pipe output to a JSON parser like jq for powerful postprocessing!
zsim-cli tokenize "LIT 7; PRT;" --json | jq -r .[].type

-i, --input FILENAME

Type: String Default: None

Set an input file to read the Z-Code from. - will use the stdin.

If you're using Windows, remember that the default cmd.exe requires two EOF characters followed by return (see examples).

Examples:

# Tokenize file programs/test.zc
zsim-cli tokenize -i programs/test.zc

# Tokenize from stdin
zsim-cli tokenize -i -
LIT 7;
PRT;
# Windows
^Z <ENTER>
^Z <ENTER>
# Unix or MacOS
^D^D

--encoding TEXT

Type: String Default: "utf_8"

Encoding to use when opening files with -i, --input.
Refer to the Python docs for possible values.

Examples:

# Use ASCII encoding
zsim-cli tokenize -i ascii_encoded.zc --encoding ascii

Validation

zsim-cli validate [ZCODE]

--json / --no-json

Type: Boolean Default: False

If the flag is set, the output will be in JSON format.
The JSON schema is { "success": <boolean>, "message": "<string>" }.

Examples:

# Validate code in JSON
zsim-cli validate "LIT 7; PRT;" --json

# Pipe output to a JSON parser like jq for powerful postprocessing!
zsim-cli validate "LIT 7; PRT;" --json | jq -r .message

-i, --input FILENAME

Type: String Default: None

Set an input file to read the Z-Code from. - will use the stdin.

If you're using Windows, remember that the default cmd.exe requires two EOF characters followed by return (see examples).

Examples:

# Validate file programs/test.zc
zsim-cli validate -i programs/test.zc

# Validate from stdin
zsim-cli validate -i -
LIT 7;
PRT;
# Windows
^Z <ENTER>
^Z <ENTER>
# Unix or MacOS
^D^D

--encoding TEXT

Type: String Default: "utf_8"

Encoding to use when opening files with -i, --input.
Refer to the Python docs for possible values.

Examples:

# Use ASCII encoding
zsim-cli validate -i ascii_encoded.zc --encoding ascii

Simulating

zsim-cli run [ZCODE]

--json / --no-json

Type: Boolean Default: False

If the flag is set, the output will be in JSON format.
This flag is not compatible with --step!
The JSON schema is either { "success": <boolean>, "message": "<string>" } for invalid zcode or

{
    "success": true,
    "instruction_set": "<z|zfp|zds|zfpds>",
    "initial_memory": { "..." },
    "code": "...",
    "final_state": {
        "m": 1,
        "d": [],
        "b": [],
        "h": {},
        "o": "",
    },
    "states": [
        {
            "state": { "Same as final_state" },
            "next_instruction": {
                "command": "...",
                "mnemonic": "...",
                "parameters": [ 1, 2, 3 ],
            },
        },
        "..."
    ],
}

when the execution was successful.

Examples:

# Run code and output information about the states in JSON
zsim-cli run "LIT 7; PRT;" --json

# Pipe output to a JSON parser like jq for powerful postprocessing!
zsim-cli run "LIT 7; PRT;" --json | jq -r .final_state.o

-i, --input FILENAME

Type: String Default: None

Set an input file to read the Z-Code from. - will use the stdin.

If you're using Windows, remember that the default cmd.exe requires two EOF characters followed by return (see examples).

Examples:

# Run file programs/test.zc
zsim-cli run -i programs/test.zc

# Run from stdin
zsim-cli run -i -
LIT 7;
PRT;
# Windows
^Z <ENTER>
^Z <ENTER>
# Unix or MacOS
^D^D

--encoding TEXT

Type: String Default: "utf_8"

Encoding to use when opening files with -i, --input.
Refer to the Python docs for possible values.

Examples:

# Use ASCII encoding
zsim-cli run -i ascii_encoded.zc --encoding ascii

-h, --memory TEXT

Type: String Default: "[]"

Optionally overwrite the memory configuration for the executing code.
The format is [ <addr>/<value>, ... ].

Examples:

# 10 + 5
zsim-cli run "LOD 1; LOD 2; ADD;" -h "[1/10, 2/5]"

--instructionset

Type: String Default: "zfpds"

Set the instruction set. Each instruction set has different available instructions to use.
For example LODI comes from zds, while LODLOCAL is defined in zfp.
When you are unsure, stick with zfpds where all instructions are available.

Examples:

# Use a specific instruction-set
zsim-cli run "LIT 7; LIT 3; ADD;" --instructionset "z"

--step / --no-step

Type: Boolean Default: False

If this flag is set, the execution will ask for confirmation after each step of the execution.
This flag is not compatible with --json or --full-output!

Examples:

# Go through Z-Code instruction by instruction
zsim-cli run "LIT 7; POP;" --step

--format

Type: String Default: "({m}, {d}, {b}, {h}, {o})"

The --format option allows you to customize the regular output of the simulation.

Available placeholders:

• {m} = instruction counter
• {d} = data stack
• {b} = procedure stack
• {h} = heap memory
• {o} = output

Examples:

# Use less components from the machine. This will yield "m: 5, h: [1/7], output: '7'"
zsim-cli run "LIT 7; STO 1; LOD 1; PRT;" --format "m: {m}, h: {h}, output: '{o}'"

--full-output / --no-full-output

Type: Boolean Default: False

If this flag is given, all states are printed on the standard output.
--step will ignore this option.

Examples:

# This will print all five states on the standard output
zsim-cli run "LIT 7; STO 1; LOD 1; PRT;" --full-output

-it, --interactive / --no-interactive

Type: Boolean Default: False

Use this flag to start a Z-Code interpreter.
Only --format, --instructionset and -h, --memory are compatible with this option.

Examples:

zsim-cli run -it

(back to top)

Using interactive mode

With zsim-cli run -it you can start an interactive interpreter to execute Z-Code line by line.

Using the interactive mode might present you with difficulties when using jumps or function calls.

The following code will not work in interactive mode:

LIT 6;
CALL(increment, 1,);
HALT;
increment: LODLOCAL 1;
LIT 1;
ADD;
RET;

CALL(increment, 1,); will fail since increment is not defined until later.
To circumvent this issue two special commands have been added: #noexec and #exec.

These commands push and pop frames in which commands are not directly executed but parsed and saved. The following example does the same as the Z-Code above, but uses #noexec and #exec:

> LIT 6;
> #noexec
#> f: LODLOCAL 1;
#> LIT 1;
#> ADD;
#> RET;
#> #exec
> CALL(f, 1,);

Note the # in front of the prompt that tell how many #noexec frames are running.

You are not limited to defining functions that way either! The next example uses #noexec differently:

> #noexec          
#> add_and_sto: ADD;
#> STO 1;
#> HALT;     
#> #exec           
> LIT 4;           
> LIT 1;
> JMP add_and_sto;
> LOD 1;
> PRT;

In the standard simulation mode HALT would jump after PRT but since the last typed command was JMP add_and_sto; it will jump continue right after the instruction we just sent off!

(back to top)

Roadmap

• Code execution
• Memory allocation in code
• Comments
• Interactive mode
• Better -h, --memory parsing
• Error handling
• More instruction sets
• Documentation
• More sample programs

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a merge request. You can also simply open an issue with the label "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Use pytest to run unit tests (pytest)
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a merge request

Codestyle

• Four space indentation
• One class per file
• Variables and functions are written in snake_case
• Class names are written in PascalCase

(back to top)

License

Distributed under the Unlicense license. See LICENSE for more information.

(back to top)

Contact

Justin Lehnen - [e-mail] - [e-mail]

Project Link: https://gitlab.com/justin_lehnen/zsim-cli

(back to top)

Acknowledgments

• Aachen University of Applied Sciences
• Choose an Open Source License
• GitHub Emoji Cheat Sheet
• Img Shields

(back to top)