# Assembly Syntax for EOF Stack Instructions

EOF introduces new stack instructions with immediate operands: `DUPN`, `SWAPN`, and `EXCHANGE`. The operands determine what elements of the stack will be accessed and manipulated.

There's no standard or obvious way in which these operands should be represented in human-readable assembly syntax, and different developers may come up with different solutions. If this ends up being subtly different across different tools (e.g., off by one), an assembly instruction may have different behavior depending on the syntax variant it's read as, and people or tools may be misled, which could be used to conceal malicious behavior in the worst case. Additionally, lack of clarity in communication about these opcodes could result in bugs in various places.

Because of this, we should standardize the representation of the operands of each of these instructions.

I'll describe three alternative approaches:

1. **Verbatim:** The operands are written in assembly with the same numerical value that is present in the bytecode, probably as a decimal number.
2. **Traditional:** The operands are written in a way that matches the numeration used in the original `DUP*` and `SWAP*` instructions.
3. **Exact:** The operands are written to reflect the actual stack heights touched by the instruction in 1-based indexing.

The final choice could be a combination of these approaches.

#### Notation

The notation `<bytecode>` <-> `<assembly>` means that `<bytecode>` disassembles to `<assembly>` and that `<assembly>` assembles to `<bytecode>`.

I'll use a space to separate an opcode from its immediate operand, like `DUPN 4`, but the discussion should apply equally to different syntax, like `DUPN[4]`.

## `DUPN` and `SWAPN`

Running examples and their effect described in 1-based indexing:

- `e6 03`: `DUPN` instruction that duplicates the 4th stack element.
- `e7 03`: `SWAPN` instruction that swaps the 5th stack element with the 1st.

### 1. Verbatim

Examples:

- `e6 03` <-> `DUPN 3`
- `e7 03` <-> `SWAPN 3`

### 2. Traditional

According to this approach, for example, `DUPN 4` should be functionally equivalent to `DUP4`, and `SWAPN 4` should be functionally equivalent to `SWAP4`.

The assembly operand is thus the numerical value in the bytecode **plus one**.

Examples:

- `e6 03` <-> `DUPN 4`
- `e7 03` <-> `SWAPN 4`

### 3. Exact

In this approach, the operand of `SWAPN` is encoded differently than the operand of `DUPN`. Immediates that are equal in bytecode are not numerically equal in assembly.

Examples:

- `e6 03` <-> `DUPN 4`
- `e7 03` <-> `SWAPN 5`

Note that thus `SWAPN 5` is functionally equivalent to `SWAP4`.

## `EXCHANGE`

Exchange has a single-byte immediate, but conceptually two nibble-sized operands.

It can be confusing, so I'll use one running example, `e8 13`: the `EXCHANGE` instruction with the effect of swapping the 3rd stack element with the 7th (in 1-based indexing).

Visualizing the stack: `a b C d e f G h …` -> `a b G d e f C h …`

### 1. Verbatim

There are two ways to interpret the verbatim approach.

- One operand:
- `e8 13` <-> `EXCHANGE 0x13` (in decimal `EXCHANGE 19`)
- Two operands:
- `e8 13` <-> `EXCHANGE 1 3`

### 2. Traditional

There is no direct equivalent to `EXCHANGE` prior to EOF, so this alternative proposes to draw an equivalence with a sequence of `SWAP` or `SWAPN` instructions: `EXCHANGE n m` should be functionally equivalent to `SWAPN n SWAPN m SWAPN n`. For example, `EXCHANGE 2 6` should be equivalent to `SWAP2 SWAP6 SWAP2`.

Example:

- `e8 13` <-> `EXCHANGE 2 6`

### 3. Exact

Example:

- `e8 13` <-> `EXCHANGE 3 7`