stm8dce.asm_matchers API documentation
Description: This module provides functions to pattern match STM8 SDCC generated assembly code.

# Module `stm8dce.asm_matchers`

This module provides functions to pattern match STM8 SDCC generated assembly code.

## Functions

`def match_asm_line(file_path, line_number, line)`

  Attempts to match a line of assembly code to its corresponding class(es) (Directive, Label, Instruction). If the line contains a label and an instruction, it will return a list of both. If there's no matching class for the line, an empty list is returned.

  ## Args

  `file_path` :`str`
    The path of the file containing the line.
  `line_number` :`int`
    The line number of the line.
  `line` :`str`
    The assembly line itself.

  ## Returns

  `list`
    A list containing the matched class(es) if any, an empty list otherwise.
`def sanitize_line(line)`

  Sanitizes a line by removing comments and stripping whitespace.

  Criteria for a comment: - Starts at ';'

  ## Args

  `line` :`str`
    The line to sanitize.

  ## Returns

  `str`
    The sanitized line.

## Classes

`class AreaType (*args, **kwds)`

  Enum to represent different types of areas in assembly code.

  ### Ancestors

  - enum.Enum

  ### Class variables

  `var CODE`
  `var CONST`
  `var OTHER`
  `var _member_map_`
  `var _member_names_`
  `var _member_type_`

    The base class of the class hierarchy.

    When called, it accepts no arguments and returns a new featureless instance that has no instance attributes and cannot be given any.

  `var _unhashable_values_`
  `var _use_args_`
  `var _value2member_map_`
  `var _value_repr_`

  ### Static methods

  `def _generate_next_value_(name, start, count, last_values)`

    Generate the next value when not given.

    name: the name of the member start: the initial start value or None count: the number of existing members last_values: the list of values assigned

  ### Methods

  `def __new__(cls, value)`

    Create and return a new object. See help(type) for accurate signature.

  `def _new_member_(*args, **kwargs)`

    Create and return a new object. See help(type) for accurate signature.

`class Directive`

  Class to represent a directive in the assembly code.

  Initializes a Directive object.

  ## Args

  `file_path` :`str`
    The path of the file containing the directive.
  `line_number` :`int`
    The line number of the directive.
  `line` :`str`
    The directive line itself.

  ### Static methods

  `def is_area_directive(eval, area_type=None)`

    Static method to check if an instance is a Directive and is an area directive.

    ## Args

    `eval`
      The instance to check.
    `area_type` :`AreaType`, optional
      The area type to check for.

    ## Returns

    `bool`
      True if the instance is a Directive and is an area directive (and matches the area type, if provided), False otherwise.
  `def is_global_directive(eval)`

    Static method to check if an instance is a Directive and is a global directive.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is a Directive and is a global directive, False otherwise.

  ### Methods

  `def __init__(self, file_path, line_number, line)`

    Initializes a Directive object.

    ## Args

    `file_path` :`str`
      The path of the file containing the directive.
    `line_number` :`int`
      The line number of the directive.
    `line` :`str`
      The directive line itself.
  `def __repr__(self)`

    Return repr(self).

  `def __str__(self)`

    Return str(self).

  `def is_area(self, area_type=None)`

    Checks if the directive is an area directive, optionally of a specific area type.

    ## Args

    `area_type` :`AreaType`, optional
      The area type to check for.

    ## Returns

    `bool`
      True if the directive is an area directive (and matches the area type, if provided), False otherwise.
  `def is_global(self)`

    Checks if the directive is a global directive.

    ## Returns

    `bool`
      True if the directive is a global directive, False otherwise.
`class Instruction`

  Class to represent an instruction in the assembly code.

  Initializes an Instruction object.

  ## Args

  `file_path` :`str`
    The path of the file containing the instruction.
  `line_number` :`int`
    The line number of the instruction.
  `line` :`str`
    The instruction line itself.

  ### Class variables

  `var _LONG_READ_INSTRUCTIONS`
  `var _REGISTER_ARGS`

  ### Static methods

  `def _split_instruction(line)`

    Splits an instruction into its components ([mnemonic, arg1, arg2, …]). This function handles the parsing of instructions into mnemonic and arguments, taking care of special cases like parentheses.

    ## Args

    `line` :`str`
      The line containing the instruction.

    ## Returns

    `tuple`
      A tuple containing the mnemonic and a list of arguments or an empty list if there are no arguments.
  `def is_call_instruction(eval)`

    Static method to check if an instance is an Instruction and is a call instruction.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is an Instruction and is a call instruction, False otherwise.
  `def is_interrupt_instruction(eval)`

    Static method to check if an instance is an Instruction and is an interrupt instruction.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is an Instruction and is an interrupt instruction, False otherwise.
  `def is_iret_instruction(eval)`

    Static method to check if an instance is an Instruction and is an iret instruction.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is an Instruction and is an iret instruction, False otherwise.
  `def is_long_label_read_instruction(eval)`

    Static method to check if an instance is an Instruction and is a long label read instruction.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is an Instruction and is a long label read instruction, False otherwise.

  ### Methods

  `def __init__(self, file_path, line_number, line)`

    Initializes an Instruction object.

    ## Args

    `file_path` :`str`
      The path of the file containing the instruction.
    `line_number` :`int`
      The line number of the instruction.
    `line` :`str`
      The instruction line itself.
  `def __repr__(self)`

    Return repr(self).

  `def __str__(self)`

    Return str(self).

  `def _is_register(self, arg)`

    Checks if the instruction argument is a register.

    ## Args

    `arg` :`str`
      The argument to check.

    ## Returns

    `bool`
      True if the argument is a register, False otherwise.
  `def is_call(self)`

    Returns the call target if the line is a call instruction, None otherwise. Precondition: line is after a function label.

    Criteria for a call: - Starts with 'call' or - Starts with 'jp' - Followed by a label which: - Starts with _ or a letter - Only contains letters, numbers, and '_'

    ## Returns

    `str`
      The call target if it is a call instruction, None otherwise.
  `def is_int(self)`

    Determines if the line is an interrupt definition and the name of the interrupt if it is one.

    Criteria for an interrupt definition: - Starts with 'int'

    ## Returns

    `str`
      The interrupt name if it is an interrupt definition, None otherwise.
  `def is_iret(self)`

    Determines if the line marks an interrupt return. Precondition: line is after a function label.

    Criteria for an interrupt return: - Is 'iret'

    ## Returns

    `bool`
      True if the line marks an interrupt return, False otherwise.
  `def is_long_label_read(self)`

    Determines if a long addressing capable instruction reads from a label. If it does, it returns a tuple with the instruction mnemonic and the label.

    Criteria for a long label read: - Starts with an entry in LONG_READ_INSTRUCTIONS - If the instruction has a single argument: - The argument must contain a label - If the instruction has two comma separated arguments: - The src argument (right side of the comma) must contain a label - If the instruction has three comma separated arguments (btjt, btjf): - Either argument must contain a label

    A label is defined as: - Is preceded only by non-alphanumeric characters (else hex numbers would be detected) - Starts with a letter or '' - Only contains letters, numbers, and '' - Is not a register

    Note that this pattern match does not care how the label is referenced (immediate vs indirect). This means, both 'ldw x, #(_label+0)' and 'ldw x, _label+0' will match.

    ## Returns

    `tuple`
      A tuple containing the labels ([label1, label2, …]) if it reads from one or more labels, None otherwise.
`class Label`

  Class to represent a label in the assembly code.

  Initializes a Label object.

  ## Args

  `file_path` :`str`
    The path of the file containing the label.
  `line_number` :`int`
    The line number of the label.
  `line` :`str`
    The label line itself.

  ### Static methods

  `def is_absolute_label(eval)`

    Static method to check if an instance is a Label and is an absolute label.

    ## Args

    `eval`
      The instance to check.

    ## Returns

    `bool`
      True if the instance is a Label and is an absolute label, False otherwise.

  ### Methods

  `def __init__(self, file_path, line_number, line)`

    Initializes a Label object.

    ## Args

    `file_path` :`str`
      The path of the file containing the label.
    `line_number` :`int`
      The line number of the label.
    `line` :`str`
      The label line itself.
  `def __repr__(self)`

    Return repr(self).

  `def __str__(self)`

    Return str(self).

  `def is_absolute(self)`

    Checks if the label is an absolute label.

    ## Returns

    `bool`
      True if the label is absolute, False otherwise.
  `def is_relative(self)`

    Checks if the label is a relative label.

    ## Returns

    `bool`
      True if the label is relative, False otherwise.