# Class InstructionFinder

java.lang.Object
org.apache.bcel.util.InstructionFinder

public class InstructionFinder extends Object
InstructionFinder is a tool to search for given instructions patterns, that is, match sequences of instructions in an instruction list via regular expressions. This can be used, for example, in order to implement a peep hole optimizer that looks for code patterns and replaces them with faster equivalents.

This class internally uses the java.util.regex package to search for regular expressions.

A typical application would look like this:

      InstructionFinder f = new InstructionFinder(il);
      String pat = "IfInstruction ICONST_0 GOTO ICONST_1 NOP (IFEQ|IFNE)";

      for (Iterator i = f.search(pat, constraint); i.hasNext(); ) {
          InstructionHandle[] match = (InstructionHandle[])i.next();
          ...
          il.delete(match[1], match[5]);
          ...
      }

See Also:
  - `Instruction`
  - `InstructionList`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `InstructionFinder.CodeConstraint`
  Code patterns found may be checked using an additional user-defined constraint object whether they really match the needed criterion.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InstructionFinder(InstructionList il)`
  Constructs an InstructionFinder.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final InstructionList`
  `getInstructionList()`
  Gets the inquired instruction list.
  `final void`
  `reread()`
  Reread the instruction list, for example, after you've altered the list upon a match.
  `final Iterator<InstructionHandle[]>`
  `search(String pattern)`
  Start search beginning from the start of the given instruction list.
  `final Iterator<InstructionHandle[]>`
  `search(String pattern, InstructionHandle from)`
  Start search beginning from 'from'.
  `final Iterator<InstructionHandle[]>`
  `search(String pattern, InstructionHandle from, InstructionFinder.CodeConstraint constraint)`
  Search for the given pattern in the instruction list.
  `final Iterator<InstructionHandle[]>`
  `search(String pattern, InstructionFinder.CodeConstraint constraint)`
  Start search beginning from the start of the given instruction list.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### InstructionFinder

    public InstructionFinder(InstructionList il)
    Constructs an InstructionFinder.
    Parameters:
      `il` - instruction list to search for given patterns.

- ## Method Details

  - ### getInstructionList

    public final InstructionList getInstructionList()
    Gets the inquired instruction list.
    Returns:
      the inquired instruction list.

  - ### reread

    public final void reread()
    Reread the instruction list, for example, after you've altered the list upon a match.

  - ### search

    public final Iterator<InstructionHandle[]> search(String pattern)
    Start search beginning from the start of the given instruction list.
    Parameters:
      `pattern` - the instruction pattern to search for, where case is ignored.
    Returns:
      iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area.

  - ### search

    public final Iterator<InstructionHandle[]> search(String pattern, InstructionFinder.CodeConstraint constraint)
    Start search beginning from the start of the given instruction list. Check found matches with the constraint object.
    Parameters:
      `pattern` - the instruction pattern to search for, case is ignored.
      `constraint` - constraints to be checked on matching code.
    Returns:
      instruction handle or 'null' if the match failed.

  - ### search

    public final Iterator<InstructionHandle[]> search(String pattern, InstructionHandle from)
    Start search beginning from 'from'.
    Parameters:
      `pattern` - the instruction pattern to search for, where case is ignored.
      `from` - where to start the search in the instruction list.
    Returns:
      iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area.

  - ### search

    public final Iterator<InstructionHandle[]> search(String pattern, InstructionHandle from, InstructionFinder.CodeConstraint constraint)
    Search for the given pattern in the instruction list. You can search for any valid opcode via its symbolic name, for example "istore". You can also use a super class or an interface name to match a whole set of instructions, for example "BranchInstruction" or "LoadInstruction". "istore" is also an alias for all "istore_x" instructions. Additional aliases are "if" for "ifxx", "if_icmp" for "if_icmpxx", "if_acmp" for "if_acmpxx". Consecutive instruction names must be separated by white space which will be removed during the compilation of the pattern. For the rest the usual pattern matching rules for regular expressions apply.

    Example pattern:

        search("BranchInstruction NOP ((IfInstruction|GOTO)+ ISTORE Instruction)*");

    If you alter the instruction list upon a match such that other matching areas are affected, you should call reread() to update the finder and call search() again, because the matches are cached.

    Parameters:
      `pattern` - the instruction pattern to search for, where case is ignored.
      `from` - where to start the search in the instruction list.
      `constraint` - optional CodeConstraint to check the found code pattern for user-defined constraints.
    Returns:
      iterator of matches where e.nextElement() returns an array of instruction handles describing the matched area.