Package ghidra.app.plugin.assembler

# Class AssemblySelector

java.lang.Object
ghidra.app.plugin.assembler.AssemblySelector

public class AssemblySelector extends Object
Provides a mechanism for pruning and selecting binary assembled instructions from the results of parsing textual assembly instructions. There are two opportunities: After parsing, but before prototype generation, and after machine code generation. In the first opportunity, filtering is optional --- the user may discard any or all parse trees. The second is required, since only one instruction may be placed at the desired address --- the user must select one instruction among the many results, and if a mask is present, decide on a value for the omitted bits.

Extensions of this class are also suitable for collecting diagnostic information about attempted assemblies. For example, an implementation may employ the syntax errors in order to produce code completion suggestions in a GUI.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final record`
  `AssemblySelector.Selection`
  A resolved selection from the results given to `select(AssemblyResolutionResults, AssemblyPatternBlock)`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Comparator<AssemblyResolvedPatterns>`
  `compareBySizeThenBits`
  A comparator on instruction length (shortest first), then bits lexicographically
  `protected Set<AssemblyResolvedError>`
  `semanticErrors`
  `protected Set<AssemblyParseResult>`
  `syntaxErrors`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AssemblySelector()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected List<AssemblyResolvedPatterns>`
  `filterCompatibleAndSort(AssemblyResolutionResults rr, AssemblyPatternBlock ctx)`
  `Collection<AssemblyParseResult>`
  `filterParse(Collection<AssemblyParseResult> parse)`
  Filter a collection of parse trees.
  `AssemblySelector.Selection`
  `select(AssemblyResolutionResults rr, AssemblyPatternBlock ctx)`
  Select an instruction from the possible results.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### syntaxErrors

    protected Set<AssemblyParseResult> syntaxErrors

  - ### semanticErrors

    protected Set<AssemblyResolvedError> semanticErrors

  - ### compareBySizeThenBits

    protected Comparator<AssemblyResolvedPatterns> compareBySizeThenBits
    A comparator on instruction length (shortest first), then bits lexicographically

- ## Constructor Details

  - ### AssemblySelector

    public AssemblySelector()

- ## Method Details

  - ### filterParse

    public Collection<AssemblyParseResult> filterParse(Collection<AssemblyParseResult> parse) throws AssemblySyntaxException
    Filter a collection of parse trees.

    Generally, the assembly resolver considers every possible parsing of an assembly instruction. If, for some reason, the user wishes to ignore certain trees (perhaps for efficiency, or perhaps because a certain form of instruction is desired), entire parse trees may be pruned here.

    It is possible that no trees pass the filter. In this case, this method ought to throw an `AssemblySyntaxException`. Another option is to pass the erroneous result on for semantic analysis, in which case, the error is simply copied into an erroneous semantic result. Depending on preferences, this may simplify the overall filtering and error-handling logic.

    By default, no filtering is applied. If all the trees produce syntax errors, an exception is thrown.

    Parameters:
      `parse` - the collection of parse results (errors and trees).
    Returns:
      the filtered collection, optionally in-place.
    Throws:
      `AssemblySyntaxException` - if the selector wishes to forward one or more syntax errors

  - ### filterCompatibleAndSort

    protected List<AssemblyResolvedPatterns> filterCompatibleAndSort(AssemblyResolutionResults rr, AssemblyPatternBlock ctx) throws AssemblySemanticException
    Throws:
      `AssemblySemanticException`

  - ### select

    public AssemblySelector.Selection select(AssemblyResolutionResults rr, AssemblyPatternBlock ctx) throws AssemblySemanticException
    Select an instruction from the possible results.

    This must select precisely one resolved constructor from the results given back by the assembly resolver. This further implies the mask of the returned result must consist of all 1s. If no selection is suitable, this must throw an exception.

    By default, this method selects the shortest instruction that is compatible with the given context and takes 0 for bits that fall outside the mask. If all possible resolutions produce errors, an exception is thrown.

    Parameters:
      `rr` - the collection of resolved constructors
      `ctx` - the applicable context.
    Returns:
      a single resolved constructor with a full instruction mask.
    Throws:
      `AssemblySemanticException` - if all the given results are semantic errors