org.apache.bcel.util

Class InstructionFinder

public class InstructionFinder extends Object

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

This class internally uses the Regexp 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
static interfaceInstructionFinder.CodeConstraint
Code patterns found may be checked using an additional user-defined constraint object whether they really match the needed criterion.
Constructor Summary
InstructionFinder(InstructionList il)
Method Summary
InstructionListgetInstructionList()
voidreread()
Reread the instruction list, e.g., after you've altered the list upon a match.
Iteratorsearch(String pattern, InstructionHandle from, InstructionFinder.CodeConstraint constraint)
Search for the given pattern in the instruction list.
Iteratorsearch(String pattern)
Start search beginning from the start of the given instruction list.
Iteratorsearch(String pattern, InstructionHandle from)
Start search beginning from `from'.
Iteratorsearch(String pattern, InstructionFinder.CodeConstraint constraint)
Start search beginning from the start of the given instruction list.

Constructor Detail

InstructionFinder

public InstructionFinder(InstructionList il)

Parameters: il instruction list to search for given patterns

Method Detail

getInstructionList

public final InstructionList getInstructionList()

Returns: the inquired instruction list

reread

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

search

public final Iterator 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, e.g. "istore". You can also use a super class or an interface name to match a whole set of instructions, e.g. "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

search

public final Iterator 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 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 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