Package mars.assembler.token

Class MacroHandler

java.lang.Object
mars.assembler.token.MacroHandler
public class MacroHandler extends Object
A class used by the Preprocessor to handle macro definition, lookup, and expansion.

Macros can be overloaded since they are identified by both macro name and number of parameters. Defining another macro with the same name and parameter count as a previous macro overrides it.

Note: Forward references (calling a macro before it is defined) and nested definitions (defining a macro inside the definition of another macro) are not supported.

Author:
M.H.Sekhavat (sekhavat17@gmail.com), 2013; Sean Clarke, October 2024

  • Constructor Details

    • MacroHandler

      public MacroHandler()
      Create a new MacroHandler with no defined macros.

  • Method Details

    • defineMacro

      public Macro defineMacro(Macro macro)
      Define a macro, allowing it to be called later. If a macro already exists with the same name and parameter count, it can no longer be used in expansions after this call.
      Parameters:
      macro - The macro to define.
      Returns:
      The previous macro with the same name and parameter count, if applicable, or null if no such macro was defined.

    • findMatchingMacro

      public Macro findMatchingMacro(String name, List<Token> arguments)
      Find the macro defined with the given name whose signature matches the given list of call arguments.
      Parameters:
      name - The name of the macro to find.
      arguments - The list of arguments given in the macro call.
      Returns:
      The matching macro, if one exists, or null otherwise.

    • hasMacroName

      public boolean hasMacroName(String name)
      Determine whether the given name matches any defined macros. This can be used to avoid unnecessary parsing of macro arguments if the name does not match any defined macro.
      Parameters:
      name - The macro name to search for.
      Returns:
      true if any macros have been defined with name name, regardless of parameter count, or false otherwise.

    • findMatchingMacros

      public List<Macro> findMatchingMacros(String name)
      Find all macros defined with the given name, regardless of parameter count.
      Parameters:
      name - The macro name to search for.
      Returns:
      The matching macros, which may be an empty list if none match.

    • getCallArguments

      public List<Token> getCallArguments(List<Token> callTokens)
      Filter the tokens after a possible macro name to obtain the relevant tokens for a macro call.
      Parameters:
      callTokens - The list of tokens following the macro name token.
      Returns:
      The list of tokens with comments, delimiters, and possible surrounding parentheses removed.

    • instantiate

      public List<SourceLine> instantiate(Macro macro, List<Token> arguments, SourceLine callerLine, AssemblerLog log)
      Generate a macro call expansion using the given arguments. Nested macro calls are also expanded by this method.

      Also appends _Mid to all labels defined inside the macro body, where id is an integer uniquely identifying the specific macro instance. This enables macros to contain labels without conflicting between different instances.

      Parameters:
      arguments - The macro arguments used in the call syntax.
      callerLine - The line containing the macro call.
      log - The log to be populated with any errors produced.
      Returns:
      The expanded form of the macro, including the expansions of any nested macro calls.