asa 1.0.0

Advanced Subleq Assembler. Assembles 'sublang' to subleq
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

<img src="https://github.com/Kat9-123/asa/raw/HEAD/assets/logo.png" width="80"/>


# Advanced Subleq Assembler
[![Build Status](https://img.shields.io/github/actions/workflow/status/Kat9-123/asa/ci.yml?branch=master&style=flat-square)](https://github.com/Kat9-123/asa/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/asa?style=flat-square)](https://crates.io/crates/asa)
[![Sublang](https://img.shields.io/badge/Sublang-documentation-blue)](https://github.com/Kat9-123/asa/blob/master/Sublang.md)
[![Coverage Status](https://img.shields.io/coveralls/github/Kat9-123/asa/master?style=flat-square)](https://coveralls.io/github/Kat9-123/asa?branch=master)
[![Crates.io](https://img.shields.io/crates/d/asa?style=flat-square)](https://crates.io/crates/asa)




This Subleq assembler assembles a custom language, called [Sublang](https://github.com/Kat9-123/asa/blob/master/Sublang.md), into Subleq


## Features
* Interpreter and debugger
* Friendly and detailed assembler feedback
* Powerful macros
* Syntax sugar for common constructs like dereferencing
* Optional typing system
* Fully fledged standard library including routines and high level control flow constructs like If or While
* Fine grained control over your code and the assembler
* Module and inclusion system
* 16-bit
* Extensive documentation

## What is Subleq?
Subleq or SUBtract and jump if Less than or EQual to zero is an assembly language that has only the `SUBLEQ` instruction, which has three operands: `A`, `B`, `C`.
The value at memory address `A` is subtracted from the value at address `B`. If the resulting number is less than or equal to zero, a jump takes place to address `C`. Otherwise the next instruction is executed.
Since there is only one instruction, the assembly does not contain opcodes.
So: 
`SUBLEQ 1 2 3`
would just be
`1 2 3`

A very basic subleq interpreter written in Python would look as follows
```Python
pc = 0
while True:
    a = mem[pc]
    b = mem[pc + 1]
    c = mem[pc + 2]

    result = mem[b] - mem[a]
    mem[b] = result
    if result <= 0:
        pc = c
    else:
        pc += 3
```
Most subleq implementations, this one included, also include the IO operations: INPUT, OUTPUT and HALT.
These can be achieved by respectively having `A = -1`, `B = -1` and `C = -1`. INPUT and OUTPUT read or write singular ASCII characters


## Installation
`cargo install asa` or download the binary from the releases tab

## Usage
```bash
asa MySubleq.sbl
```

## Syntax highlighting
See <https://github.com/Kat9-123/sublang-highlighting>


## Project status
This project is functionally complete, but the documentation for the assembler, Sublang and Sublib is still lacking. As is the Sublib itself, which isn't finished yet