ruxnasm
Ruxnasm is an assembler for Uxntal — a programming language for the Uxn stack-machine by Hundred Rabbits. Ruxnasm strives to be an alternative to Uxnasm, featuring more user-friendly error reporting, warnings, and helpful hints, reminiscent of those seen in modern compilers for languages such as Rust or Elm.
Quick start
cargo run -- examples/helloworld.tal helloworld.rom
uxncli helloworld.rom
Compatibility with Uxnasm
Currently, Uxntal doesn't have an official language specification, which means it is defined by the programs it's processed by — the assemblers. The official assembler for Uxntal is Uxnasm, written in ANSI C. Ruxnasm does not try to be a 1:1 reimplementation of Uxnasm; it's too opinionated to be so. Instead, it tries to define a more elegant and modern version of Uxntal, while at the same time preserving the software already written with Uxnasm in mind.
Although they are mostly the same, there are programs that are valid in Uxnasm and invalid in Ruxnasm and vice versa. This means that the language defined by Ruxnasm is neither a subset nor a superset of the language defined by Uxnasm. All known differences between Ruxnasm and Uxnasm have been documented in the docs/differences.md file and are kept up-to-date as the project is being developed.
Interacting with Uxnasm from the command line is no different for Ruxnasm — just append an "r" at the start.
Installation
From binaries
Check out the releases page for prebuilt releases of Ruxnasm for various operating systems. If you want to get the most recent Linux, Windows, or macOS build, check out the artifacts of the latest CI workflow run on the actions page.
From source
You can build and install Ruxnasm from source using Cargo — Rust's package manager. You can get it by installing the most recent release of Rust. Both of the methods listed below should build the Ruxnasm binary and place it in Cargo installation root's bin
folder (~/.cargo/bin
as the default, check out this guide for more information).
-
From the Git repository
To build and install the most recent version of Ruxnasm, clone the repository,
cd
into it, and runcargo install --path .
-
From crates.io
Ruxnasm can be fetched from the crates.io package registry. To build and install the most recent release of Ruxnasm, run
cargo install ruxnasm
from anywhere.
Library
Besides being a command-line tool, Ruxnasm is also available as a library for the Rust programming language. It exposes the assemble
function, which can turn a string with an Uxntal program into an Uxn binary.
pub fn assemble(source: &[u8]) -> Result<Vec<u8>>
The library is available on crates.io and can be included in your Cargo-enabled project like this:
[dependencies]
ruxnasm = { version = "*", default-features = false } # Disable the default "bin" feature
and then used in your code like this:
let (binary, _) = ruxnasm::assemble(b"|0100 #02 #03 ADD").unwrap();
assert_eq!(binary, [0x01, 0x02, 0x01, 0x03, 0x18]);
The code above unwraps the result, but could just as well handle all the errors and warnings returned from the assemble
function in case there were any.
License
This software is licensed under the MIT license.
See the LICENSE file for more details.