StackAssembly is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install stack-assembly

It will make the stack-assembly command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall stack-assembly uninstalls.

Adding `stack_assembly` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add stack-assembly

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

stack-assembly = "0.1.0"

The stack_assembly library will be automatically available globally. Read the stack_assembly library documentation.

Back to the crate overview.

Readme

StackAssembly

About

StackAssembly is a minimalist, stack-based, assembly-like programming language. Here's a small taste:

# Push `0` to the stack.
0

increment:
    # Increment the value on the stack by `1`.
    1 +

    # If the value on the stack is smaller than `255`, jump to `increment:`.
    0 copy 255 <
    @increment
        jump_if

# Looks like we didn't jump to `increment:` that last time, so the value must be
# `255` now.
255 = assert

StackAssembly serves as a foundation for my personal research into programming language design and implementation. Even though I want it to be complete enough for real code too, that is not its main purpose. If you're wondering if it might work for you, the safe answer is probably "no".

Status

The initial implementation is complete, but testing (both automated and in terms of real-world use) has been limited. Feel free to try the language, but don't expect too much in terms of reliability or usefulness.

Documentation

Examples

Check out the examples/ directory to see some StackAssembly code. To run a script, follow these steps:

Clone this repository. Regular Git will do, but I generally recommend using Jujutsu instead.
Make sure you have a recent version of Rust installed on your system.
From within this repository, run the following command: cargo run -- path/to/script.stack

For example, to run the "control flow" example from the root directory of this repository, execute this command: cargo run -- examples/control-flow.stack

Interpreter API

The StackAssembly interpreter is packaged as a library. That library's documentation covers mainly the interpreter API, but also provides information on the language. Right now, you must build the documentation locally to access it. With a working Rust setup, you can do so by running cargo doc --open.

Additional Documentation

The initial design document can serve as a (not fully complete) introduction to the language. The test suite covers the full language in all its detail, basically serving the role of a specification, but is not as friendly to approach.

License

This project is open source, licensed under the terms of the Zero-Clause BSD License (0BSD, for short). This basically means you can do anything with the code, without restrictions, but you can't hold the authors liable for any problems.

See LICENSE.md for details.

Installing the command-line executable

Adding stack_assembly library as a dependency

Adding `stack_assembly` library as a dependency