tiny8.assembler module

Simple assembler for tiny8 - converts assembly text into program tuples.

This module provides a tiny assembler that tokenizes and parses a simple assembly syntax and returns a list of instructions and a label mapping.

tiny8.assembler.assemble(text: str) → Tuple[List[Tuple[str, Tuple]], Dict[str, int]][source]

Parse assembly source text and return parsed instructions and label map.

Args:
text (str): Assembly source code as a single string. May contain

multiple lines, labels and comments.

Returns:
Tuple[List[Tuple[str, Tuple]], Dict[str, int]]: A pair (instructions, labels):

  • instructions: list of parsed instructions in source order. Each instruction is a tuple (mnemonic, operands) where mnemonic is a string and operands is a tuple of operand values as produced by the assembler.

  • labels: mapping from label names (str) to integer addresses (instruction indices).

Raises:
Exception: Propagates parsing errors from the underlying parser

(for example, syntax or operand errors).

Notes:

This function is a thin wrapper around parse_asm(…) and forwards any exceptions raised by the parser.

Example:
>>> src = "start: MOV R1, 5\nJMP start"
>>> instructions, labels = assemble(src)
>>> labels
{'start': 0}
tiny8.assembler.assemble_file(path: str)[source]

Assemble the contents of a source file.

Reads the entire file at path and passes its contents to assemble(…).

Args:

path (str): Path to the source file to assemble.

Returns:

Any: The result produced by calling assemble(source_text). The exact type depends on the implementation of assemble(…).

Raises:

FileNotFoundError: If the specified file does not exist. OSError: For other I/O related errors when opening or reading the file. Exception: Any exception raised by assemble(…) will be propagated.

Notes:

The file is opened in text mode and read entirely into memory; for very large files this may be inefficient.

Example:
>>> result = assemble_file("program.asm")
>>> # result now holds the assembled output produced by assemble(...)
tiny8.assembler.parse_asm(text: str) → Tuple[List[Tuple[str, Tuple]], Dict[str, int]][source]

Parse assembly source text into a program listing and a label table.

The function scans the given assembly text line-by-line and produces two values:

  • program: a list of instructions, where each instruction is a tuple (MNEMONIC, OPERANDS_TUPLE). MNEMONIC is stored in uppercase for readability (the CPU/runtime looks up handlers using mnemonic.lower()). OPERANDS_TUPLE is an immutable tuple of operand values in the order they appear.

  • labels: a mapping from label name (str) to program counter (int), where the program counter is the zero-based index of the instruction in the produced program list.

Args:
text: Assembly source code as a single string. May contain comments,

blank lines and labels.

Returns:

A pair (program, labels) as described above.

Notes:

  • Comments begin with ‘;’ and extend to the end of the line and are removed before parsing.

  • Labels may appear on a line by themselves or before an instruction with the form “label: instr …”. A label associates the name with the current instruction index.

  • Registers are encoded as (“reg”, N) where N is the register number.

  • Numeric operands are parsed using _parse_number; non-numeric tokens are preserved as strings (symbols) for later resolution.