Assembly File Handling

The asm.py module contains utilities to handle file I/O operations on arbitrary assembly files. The purpose is to remove and to restore lines from the associated assembly file accurately.

ISA

This class, which implements the Singleton pattern, is used to parse a user-defined language file and offers utilities to check whether an arbitrary string is a valid instruction according to the language file.

class asm.ISA(*args, **kwargs)[source]

Bases: object

Singleton class to provide utilities for the considered ISA.

get_mnemonics() → set[source]

Returns a set with the ISA-lang mnemonics.

Parameters:

None

Returns:

A set with all the ISA-lang mnemonics.

Return type:

set

is_instruction(assembly_line: str) → bool[source]

Checks if assembly_line’s first sub-string is present the class keywords set.

Parameters:

assembly_line (str) – an assembly mnemonic.

Returns:

True if assembly_line is in mnemonics, False otherwise.

Return type:

bool

Codeline

This is a dataclass to represent a single line of assembly code. Note that the lineno attribute which corresponds to the line number of the code line in the assembly file uses 0-based indexing!

class asm.Codeline(lineno: int, data: str, valid_insn: bool)[source]

Bases: object

Represents a line of assembly code

data: str
lineno: int
valid_insn: bool

AssemblyHandler

This class, utilises ISA and Codeline to parse a single assembly file and store its code in chunks (lists) of Codeline objects. It offers utilities for removing and restoring arbitrary lines of code from the file while keeping track of the changes performed and accurately updating the lineno attributes of the stored code lines when needed.

class asm.AssemblyHandler(isa: ISA, assembly_source: Path, chunksize: int = 1)[source]

Bases: object

Manages one assembly file.

It operates on the file by removing/restoring lines of code.

get_asm_source() → Path[source]

Returns the assembly source file pathlib.Path.

Returns:

The assembly source pathlib.Path.

Return type:

pathlib.Path

get_candidate(lineno: int) → Codeline[source]

Returns the Codeline in candidates with the specified lineno

Parameters:

lineno (int) – the line number of the candidate to be found.

Returns:

the Codeline with Codeline.lineno == lineno if found.

Return type:

Codeline

Raises:

LookUpError – If the requested Codeline does not exist

get_code() → list[Codeline][source]

Returns the parsed code as a list of Codelines.

Returns:

A list of Codeline entries.

Return type:

list

get_random_candidate(pop_candidate: bool = True) → Codeline[source]

In a uniform random manner selects one Codeline and returns it while also optionally removing it from the candidate collection.

Parameters:

pop_candidate (bool) – When True, deletes the Codeline from the collection after identifying it.

Returns:

A random Codeline from a random self.candidates chunk.

Return type:

Codeline

remove(codeline: Codeline) → None[source]

Removes the codeline from the assembly file.

Creates a new assembly file by using the current self.asm_code as a source and skips the the line which corresponds to codeline’s lineno attribute. The self.candidates lineno fields are updated (-1) if >= than the entry which is being restored.

Parameters:

codeline (Codeline) – The Codeline to be removed from the assembly file.

Returns:

None

restore() → None[source]

Re-enters the last Codeline from the changelog to the assembly file.

The self.candidates lineno fields are updated (+1) if >= than the entry which is being restored.

Returns:

None

save() → str | None[source]

Saves the current version of assembly file. The filename will be the original stem plus all current changelog codelines’ linenos seperated with a dash. If self.asm_file_changelog is empty, it does nothing.

Returns:

The filename (path) of the saved file.

Return type:

str