mnemonics package

Submodules

mnemonics.arithmetic module

Arithmetic mnemonics module for NGPASM.

This module provides arithmetic assembly instructions including addition, subtraction, multiplication, division, increment, and decrement.

class mnemonics.arithmetic.AddMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

ADD instruction - adds source to destination.

This mnemonic performs addition operation: destination = destination + source. Requires exactly two operands.

Example

AddMnemonic(Register.EAX, Register.EBX) ; Adds EBX to EAX

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize an ADD instruction.

Parameters:

• *operands – Two operands (destination, source).

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly two operands are provided.

class mnemonics.arithmetic.ArithmeticCommentGenerator

Bases: CommentGenerator

Specialized comment generator for arithmetic operations.

This generator creates context-aware comments for arithmetic instructions like ADD, SUB, MUL, DIV, INC, and DEC, using appropriate templates for each instruction type.

_templates

Class variable mapping instruction names to comment templates. Templates use {dst} and {src} placeholders for operands.

Type:

ClassVar[dict[str, str]]

_abc_impl = <_abc._abc_data object>

_templates: ClassVar[dict[str, str]] = {'add': 'Adding {src} to {dst}', 'dec': 'Decrementing {dst}', 'div': 'Dividing {dst} by {src}', 'inc': 'Incrementing {dst}', 'mul': 'Multiplying {dst} by {src}', 'sub': 'Subtracting {src} from {dst}'}

generate(mnemonic_name: str, operands: list[Operand]) → str

Generate an arithmetic-specific comment for the instruction.

Parameters:

• mnemonic_name – Name of the arithmetic instruction.

• operands – List of operands for the instruction.

Returns:

A formatted comment string describing the arithmetic operation. Falls back to default comment generation if no template exists.

class mnemonics.arithmetic.ArithmeticMnemonic(name: str, expected_operands: int, *operands: Register | str | int, enable_comment: bool = True)

Bases: BaseMnemonic

Base class for arithmetic mnemonics with common behavior.

This class provides a foundation for all arithmetic instructions, automatically setting up the appropriate validator based on the expected number of operands and using arithmetic-specific comment generation.

__init__(name: str, expected_operands: int, *operands: Register | str | int, enable_comment: bool = True) → None

Initialize an arithmetic mnemonic.

Parameters:

• name – The arithmetic instruction name (e.g., ‘add’, ‘sub’).

• expected_operands – Number of operands required (1 or 2).

• *operands – Variable number of instruction operands.

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If expected_operands is not 1/2, or if operand count mismatch.

class mnemonics.arithmetic.DecMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

DEC instruction - decrements register by 1.

This mnemonic performs decrement operation: operand = operand - 1. Requires exactly one operand.

Example

DecMnemonic(Register.EAX) ; Decrements EAX by 1

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize a DEC instruction.

Parameters:

• *operands – Single operand to decrement.

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly one operand is provided.

class mnemonics.arithmetic.DivMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

DIV instruction - divides destination by source.

This mnemonic performs division operation: destination = destination / source. Requires exactly two operands.

Example

DivMnemonic(Register.EAX, Register.EBX) ; Divides EAX by EBX

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize a DIV instruction.

Parameters:

• *operands – Two operands (destination, source).

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly two operands are provided.

class mnemonics.arithmetic.IncMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

INC instruction - increments register by 1.

This mnemonic performs increment operation: operand = operand + 1. Requires exactly one operand.

Example

IncMnemonic(Register.EAX) ; Increments EAX by 1

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize an INC instruction.

Parameters:

• *operands – Single operand to increment.

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly one operand is provided.

class mnemonics.arithmetic.MulMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

MUL instruction - multiplies destination by source.

This mnemonic performs multiplication operation: destination = destination * source. Requires exactly two operands.

Example

MulMnemonic(Register.EAX, Register.EBX) ; Multiplies EAX by EBX

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize a MUL instruction.

Parameters:

• *operands – Two operands (destination, source).

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly two operands are provided.

class mnemonics.arithmetic.SubMnemonic(*operands: Register | str | int, enable_comment: bool = True)

Bases: ArithmeticMnemonic

SUB instruction - subtracts source from destination.

This mnemonic performs subtraction operation: destination = destination - source. Requires exactly two operands.

Example

SubMnemonic(Register.EAX, Register.EBX) ; Subtracts EBX from EAX

__init__(*operands: Register | str | int, enable_comment: bool = True) → None

Initialize a SUB instruction.

Parameters:

• *operands – Two operands (destination, source).

• enable_comment – Whether to generate comments in output.

Raises:

ValueError – If not exactly two operands are provided.

mnemonics.base module

Base classes and utilities for assembly mnemonics.

This module provides the foundation for creating assembly language mnemonics with support for operand validation, comment generation, and instruction formatting.

class mnemonics.base.BaseMnemonic(name: str, validator: OperandValidator, comment_generator: CommentGenerator = None, *operands: Register | str | int, enable_comment: bool = True)

Bases: object

Base class for assembly mnemonics following SOLID principles.

This class provides core functionality for constructing assembly instructions with flexible operand handling, validation strategies, and comment generation.

name

Assembly instruction name (e.g., ‘mov’, ‘add’).

operands

List of instruction operands wrapped as Operand objects.

validator

Strategy for operand validation.

comment_generator

Strategy for comment generation.

enable_comment

Flag to control comment generation.

custom_comment

Custom comment override.

__init__(name: str, validator: OperandValidator, comment_generator: CommentGenerator = None, *operands: Register | str | int, enable_comment: bool = True) → None

Initialize a base mnemonic.

Parameters:

• name – Assembly instruction name.

• validator – Strategy for validating operands.

• comment_generator – Strategy for generating comments.

• *operands – Variable number of instruction operands.

• enable_comment – Whether to generate comments in output.

Raises:

• TypeError – If any operand has invalid type.

• ValueError – If operands fail validation.

_format_operands() → str

Format operands for instruction assembly.

Returns:

Comma-separated string of operands.

_validate_operand_types() → None

Validate operand types against allowed types.

Allowed types are Register, str, and int.

Raises:

TypeError – If any operand has invalid type.

property comment: str | None

Get the current comment for the instruction.

Returns:

Current comment string or None if no custom comment is set.

construct(indent: str = '') → str

Construct complete assembly instruction string.

This method generates the final assembly instruction with proper formatting, including indentation and optional comments.

Parameters:

indent – Leading indentation for the instruction.

Returns:

Formatted assembly instruction with optional comment.

class mnemonics.base.CommentGenerator

Bases: ABC

Base class for comment generation strategies.

_abc_impl = <_abc._abc_data object>

abstractmethod generate(mnemonic_name: str, operands: list[Operand]) → str

Generate a comment for an instruction.

Parameters:

• mnemonic_name – Name of the mnemonic/instruction.

• operands – List of operands used with the instruction.

Returns:

Generated comment string.

class mnemonics.base.DefaultCommentGenerator

Bases: CommentGenerator

Default comment generation strategy.

_abc_impl = <_abc._abc_data object>

generate(mnemonic_name: str, operands: list[Operand]) → str

Generate default comment based on operand count.

Parameters:

• mnemonic_name – Name of the mnemonic/instruction.

• operands – List of operands used with the instruction.

Returns:

Context-sensitive default comment string.

class mnemonics.base.OneOperandValidator(mnemonic_name: str)

Bases: OperandValidator

Validator for instructions requiring exactly 1 operand.

This validator ensures that instructions like INC, DEC, etc. receive the correct number of operands.

mnemonic_name

Name of the mnemonic being validated.

__init__(mnemonic_name: str) → None

Initialize one-operand validator.

Parameters:

mnemonic_name – Name of the mnemonic for error messages.

_abc_impl = <_abc._abc_data object>

validate(operands: list[Operand]) → None

Validate that exactly 1 operand is provided.

Parameters:

operands – List of operands to validate.

Raises:

ValueError – If number of operands is not exactly 1.

class mnemonics.base.Operand(value: Register | str | int)

Bases: object

Represents a mnemonic operand.

This class wraps an operand value to provide consistent string representation and type handling across different operand types.

value

The actual operand value which can be a Register, string, or integer.

Type:

ngpasm.registers.Register | str | int

__init__(value: Register | str | int) → None

value: Register | str | int

class mnemonics.base.OperandValidator

Bases: ABC

Base class for operand validation strategies.

_abc_impl = <_abc._abc_data object>

abstractmethod validate(operands: list[Operand]) → None

Validate operands for a specific instruction type.

Parameters:

operands – List of operands to validate.

Raises:

ValueError – If operands fail validation criteria.

class mnemonics.base.TwoOperandValidator(mnemonic_name: str)

Bases: OperandValidator

Validator for instructions requiring exactly 2 operands.

This validator ensures that instructions like ADD, SUB, etc. receive the correct number of operands.

mnemonic_name

Name of the mnemonic being validated.

__init__(mnemonic_name: str) → None

Initialize two-operand validator.

Parameters:

mnemonic_name – Name of the mnemonic for error messages.

_abc_impl = <_abc._abc_data object>

validate(operands: list[Operand]) → None

Validate that exactly 2 operands are provided.

Parameters:

operands – List of operands to validate.

Raises:

ValueError – If number of operands is not exactly 2.

Module contents