Ruxnasm is an assembler for Uxntal — a programming language for the Uxn stack-machine by Hundred Rabbits

Overview

ruxnasm

CI crates.io docs.rs

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 run

    cargo 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.

Comments
  • Error code > 0 expected when the assembler fails due to errors

    Error code > 0 expected when the assembler fails due to errors

    This happens for me on OSX 10.15.7 with ruxnasm built from the source code.

    I can see the errors and there is no rom produced but the return code is 0. This is an issue when trying to use ruxnasm from within other processes.

    Expected behaviour: 0 should only be returned if the assemble was successful, greater than 0 should be returned otherwise.

    ~/Documents/ruxnasm/target/release(main) » ./ruxnasm ~/life.tal /tmp/yolo.rom                                                                                                                                                                                                                                xyz@abc
    error: macro `JSR345#%$#%@##%@$#%$#%#$%4` is not defined
       ┌─ /Users/xyz/life.tal:43:25
       │
    43 │ ,fsdfdsaf ;fsdfdasfdsf  JSR345#%$#%@##%@$#%$#%#$%4
       │                         ^^^^^^^^^^^^^^^^^^^^^^^^^^
    
    error: macro `435` is not defined
       ┌─ /Users/xyz/life.tal:46:1
       │
    46 │ 435
       │ ^^^
    
    error: macro `345` is not defined
       ┌─ /Users/xyz/life.tal:47:1
       │
    47 │ 345
       │ ^^^
    
    error: macro `243543erf` is not defined
       ┌─ /Users/xyz/life.tal:49:1
       │
    49 │ 243543erf DEO
       │ ^^^^^^^^^
    
    error: found bytes on the zeroth page
       ┌─ /Users/xyz/life.tal:43:1
       │
    43 │ ╭ ,fsdfdsaf ;fsdfdasfdsf  JSR345#%$#%@##%@$#%$#%#$%4
    44 │ │ %#$543
    45 │ │ 5345
    46 │ │ 435
    47 │ │ 345
    48 │ │ 3245
    49 │ │ 243543erf DEO
       │ ╰─────────────^
    
    warning: macro `//` is never used
      ┌─ /Users/xyz/life.tal:9:40
      │
    9 │ %++ { ADD2 } %-- { SUB2 } %** { MUL2 } %// { DIV2 }
      │                                        ^^^
    
    warning: macro `!!` is never used
       ┌─ /Users/xyz/life.tal:10:40
       │
    10 │ %<< { LTH2 } %>> { GTH2 } %== { EQU2 } %!! { NEQ2 }
       │                                        ^^^
    
    warning: macro `#$543` is never used
       ┌─ /Users/xyz/life.tal:44:1
       │
    44 │ %#$543
       │ ^^^^^^
    
    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    ~/Documents/ruxnasm/target/release(main) » echo $?                                                                                                                                                                                                                                                           xyz@abc
    0
    
    bug 
    opened by xaderfos 5
  • minor idiomatic change

    minor idiomatic change

    This change removes is_hex_digit and substitutes it with pattern matching, eliminating the duplicate expressions. This also removes the panic branch in the binary caused by unwrapping, a potential marginal performance benefit.

    opened by OliveIsAWord 1
  • Add INC opcode, rearrange opcodes, use values in InstructionKind enum

    Add INC opcode, rearrange opcodes, use values in InstructionKind enum

    Main changes:

    • Rename NOP to NIP, as per uxn commit be360ffc1e5c1a41f2daae1ae04673079bf4175b
    • Merge LIT and BRK into opcode zero, add INC opcode as per commit 5b4ec0be6b7ca9740fa72d99cfa9d9392dd5d14d
    • Rearrange opcodes as per commit 107a59affac6e2e08c406ec096b6f3866fab547a

    Other changes:

    • Changed the InstructionKind enum to use associated values for more readability. A nice side effect is that the huge match in src/emitter.rs can be replaced with a simple instruction_kind as u8.

    I was a bit surprised that the hello world example from https://wiki.xxiivv.com/site/uxntal.html didn't assemble with ruxnasm, now it does!

    opened by Skelebot 1
  • Include the uxntal-test-suite submodule and add the generator crate

    Include the uxntal-test-suite submodule and add the generator crate

    This pull request includes the uxntal-test-suite repository as a Git submodule in the tests folder. The test cases are ran by the default Rust test runner and are generated by a procedural macro from located in tests/generator.

    opened by karolbelina 0
  • Rearrange opcodes for modern uxn

    Rearrange opcodes for modern uxn

    This changes the opcode order to agree with https://wiki.xxiivv.com/site/uxntal_reference.html.

    I don't know if your big rewrite is still in progress, but this made ruxnasm basically usable for me 🙌

    opened by lynn 0
Releases(v0.2.0)
Owner
Karol Belina
Karol Belina
The most primitive and the fastest implementation of a fixed-size last-in-first-out stack on stack in Rust, for Copy-implementing types

This is the simplest and the fastest (faster than Vec!) implementation of a last-in-first-out stack data structure, on stack, when stack elements are

Yegor Bugayenko 10 Jun 18, 2023
The language that eats the stack. Heavily inspired by porth which is inspired off of forth

Snack The language that eats the stack. Heavily inspired by porth which is inspired off of forth Install To use Snack you will need Rust and fasm Afte

Cowboy8625 2 Mar 20, 2022
tr-lang is a language that aims to bring programming language syntax closer to Turkish.

tr-lang Made with ❤️ in ???? tr-lang is a language that aims to bring programming language syntax closer to Turkish. tr-lang is a stack based language

Kerem Göksu 10 Apr 2, 2022
Symbolically Executable Stack Machines in Rust

Symbolically Executable Stack Machines in Rust Symbolic Stack Machines is a library for implementing symbolically executable stack-based virtual machi

TannrA 64 Dec 28, 2022
A toy-level BLE peripheral stack

bleps - A toy-level BLE peripheral stack This is a BLE peripheral stack in Rust. (no-std / no-alloc) To use it you need an implementation of embedded-

Björn Quentin 4 Oct 17, 2022
Source code and documentation for our 'full stack on rust' meetup on 29-9-2022

Full stack on Rust This is the code and documentation repository for our 'Full stack on Rust' meetup on 29-9-2022. It includes step-by-step documentat

Baseflow 7 Oct 23, 2022
Open Source Application Stack & PaaS

mycelia Open Source Application Stack & PaaS Installation cargo xtask build NOTE: We opted for cargo-xtask because Cargo build.rs is not supported for

Mycelia 3 Sep 6, 2023
A simple programming language for everyone.

Slang A simple programming language for everyone, made with Rust. State In very early stages. Plan is to create a byte-code compiler and make that exe

Slang, Inc. 11 Jul 1, 2022
A programming language. Better mantra pending.

Dusk Dusk is a programming language I've been working on on and off for the past while now. It's still very much in its infancy (... a quick look thro

Kaylynn Morgan 14 Oct 24, 2022
Frame is a markdown language for creating state machines (automata) in 7 programming languages as well as generating UML documentation.

Frame Language Transpiler v0.5.1 Hi! So very glad you are interested in Frame. Frame system design markdown language for software architects and engin

Mark Truluck 35 Dec 31, 2022
beat saber is a strongly typed, self-documenting and highly performant programming language

beatsaber beat saber is a strongly typed, self-documenting and highly performant programming language. With beat saber we aimed to create a language t

Untitled 4 Jan 17, 2022
Analogous, indented syntax for the Rust programming language.

Note: After experimenting with this in the wild, I have found representing keywords as symbols to be far less readable in large codebases. Additionall

null 42 Oct 2, 2021
A cell-based esoteric programming language

Tape A cell-based esoteric programming language Tape is a cell-based, brainfuck-like programming language that has a readable syntax and a non-wasted

Gabriel Pacheco 2 Feb 23, 2022
Programming language from down under, inspired by this Reddit post.

aussie++ Programming language from down under, inspired by this Reddit post. View live demo here. Special thanks to MarkWhyBird, louis100, and others

Zack Radisic 562 Dec 27, 2022
Programming Language Inspired by Brainfuck

Brainsuck Brainfuck but not really... like... a better version of it. Installation Requirements: Rust version 1.50 or higher Linux curl https://raw.gi

Derin Önder Eren 27 Nov 18, 2022
A Star Wars inspired by programming language

The Force The Force is a gateway to abilities many believe are unnatural... Getting Started Install Rust. We also provide a Dev Container if you would

Matthew Booe 14 Dec 21, 2022
An incremental programming language

Differential Datalog (DDlog) DDlog is a programming language for incremental computation. It is well suited for writing programs that continuously upd

VMware 1.2k Dec 28, 2022
🤯 A brainf*ck-style programming language, but readable

?? Brainease Brainease is a brainf*ck-style programming language, but readable. $ cargo install brainease # brainease -f examples/hello.bz save 'H

Arthur Fiorette 11 Sep 30, 2022
Simple programming language that speaks the ones you already know!

Simple programming language that speaks the ones you already know!

LyonSyonII 2 Feb 12, 2022