README

LMAO (Low-level Malbolge Assembler, Ooh!) is an assembler for Malbolge.
It takes a program written in HeLL (Hellish Low-level Language) and
converts it to Malbolge.

Usage: ./lmao [options] <input file name>

Unfortunately, there is no full specification of the HeLL programming
language. However, at least a short overview is given at the end of this
file.

To start with HeLL, the following resources are recommended:

- Beginner's tutorial:
  https://lutter.cc/malbolge/tutorial/cat.html

- Examples written in HeLL that come with LMAO:
  - example_simple_cat.hell
  - example_simple_hello_world.hell
  - example_cat_halt_on_eof.hell
  - example_hello_world.hell
  - example_digital_root.hell
  - example_adder.hell
  The ordering above matches their complexity.


Short overview of HeLL
----------------------

Sections:
".CODE" and ".DATA"

Comments:
One line: start comment with ";", "%", "#", or "//"
Multi-line: start comment with "/*" and end with "*/"

Blocks:
Separated by blank lines that do not even contain a comment.
Alternatively: surrounded by "{" and "}"

At the begin of each block, the ".OFFSET" directive, or "@" for short,
may be used. It must be followed by a number.
Only use if really necessary.
Examples: "@C1", ".OFFSET 40000".

Labels: <<identifier>> followed by ":"

Each block must start with a label (or with an offset definition
followed by a label).


.DATA cells may contain:
------------------------

Numbers:
Decimal numbers (plain), ternary numbers (preceeded by "0t"), or one of
the following constants:
- "C0"  = 0t0000000000 = 0
- "C1"  = 0t1111111111 = 29524
- "C2"  = 0t2222222222 = 59048
- "C20" = 0t2222222220 = 59046
- "C21" = 0t2222222221 = 59047
- "EOF" = "C2"
ASCII characters enquoted with single quotes "'" can be used as well.

Operators:
Plus (+), Minus (-), Times (*), Divided (/),
Rotate Tritwise Right (>>), Rotate Tritwise Left (<<), Crazy (!)
  Example for using operators: (0t1210>>1)-1

Don't care symbols:
"?" or "?-"
"?" reserves the cell, but the initial value is irrelevant.
"?-" is an unused cell that may be used otherwise. Never access this
cell in any way, or you may cause undefined behavior. Must not follow a
label definition (in this case, use "?" instead).

References to label:
References may (but need not) be prefixed by a "R_" or "U_" modifier.
The "R_" modifier is the same as incrementing the value by one.
If the "U_" modifier is used, the prefixed reference must be followed
by a further reference. The second reference must point to a label
within the same block at a later memory position. The distance to this
label is subtracted from the prefixed reference.
  Example for "U_" prefix: "U_ref foo 0 0 foo: 1"
  The value of 2 is subtracted from "ref".

Strings:
Use quotes. Supported escape sequences:
"\r", "\n", "\t", "\\", "\"" "\0".
The string may be followed by a comma and a value. In this case,
the value will be placed between each character of the string.
Example 1: "Test" is equivalent to 'T' 'e' 's' 't'
Example 2: "Test", 42 is equivalent to 'T' 42 'e' 42 's' 42 't'

Important note:
Within the .DATA section, a label called "ENTRY" must be defined.
The D register will point at this position when the program starts.
The C register will point at any Jmp instruction.
The value of the A register is not defined.


.CODE cells must only contain xlat2 cycle descriptions
------------------------------------------------------

xlat2 cycle description:
Either a single command (for non loop-resistant cells) or a cycle of
commands separated by "/".

Commands:
"Nop", "Jmp", "MovD", "Opr", "Rot", "In", "Out", "Hlt"

Abbreviation for "Nop/Nop": "RNop" (loop-*r*esistant _Nop_)