Package com.pnfsoftware.jeb.core.units.code.android.ir.compiler

Class DPatternCompiler.DPattern

java.lang.Object
com.pnfsoftware.jeb.core.units.code.android.ir.compiler.DPatternCompiler.DPattern
Enclosing class:
DPatternCompiler
public static class DPatternCompiler.DPattern extends Object
IR expression multi-pattern, consisting of one or more inputs, and zero or one output (for replacement). 
 Triggers for leaves:
   $      any (terminals and non-terminals)
   T      terminals (imm, var)
   N      non-terminals
   V      variables
   #      immediates
   @x     special immediates; currently supported: @LASTBITn = (bitsize-1) of expression n
          (important: take note that n does not refer to the leaf itself, it refers to another previously matched leaf.)
   DIGITS a specific immediate (an optional id can be specified in curly braces after the value)

 Suffixes:
  {n}     Assign the id n to the leaf (must be the first suffix)
  [H1]    Select the first half of an expression (for a 32-bit leaf, the [0:16[ bits)
  [H2]    Select the second half of an expression (for a 32-bit leaf, the [16:32[ bits)

 Examples:
   $0     match any expression, assign the id 0
   V1     match any EVar, assign the id 1
   #2     match any immediate; assign the id 2 to it
   10     match an immediate holding the value 10, of any size; do not assign an id to it (will not be in the matchmap)
   10{2}  match an immediate holding the value 10; assign the id 2 to it

 Use parentheses. The parser is relatively simple and does not know about operator precedence.
 Therefore, an excess of parens around expressions is better than the reverse.

 Associativity for ADD, MUL, AND, OR, XOR: use the syntax (a OP b OP c OP d) instead of specific grouping like ((a OP b) OP (c OP d))
 to allow the matcher to try all possible combinations for associative and commutative operators.

 Immediate literals: should always start with a digit. Therefore, to use write in base 16, use the 0x prefix.
 Negative literals are allowed but must be enclosed in parens, e.g. (-3).

 Special BOL characters for multi-line patterns:
 > at beginning of line indicates the trigger (if unspecified,
   the most appropriate trigger statement will be determined heuristically)
 X at beginning of line indicates that the input expression should not be
   discarded during a replacement (if any). It can only be used for leading
   and trailing statements of an input pattern. Gaps are not allowed.

 When compiling an output pattern for replacement, immediates can reference existing matched-item ids,
 in which case their bitsize will be the one of the matched item.
 When an output pattern uses id-less immediates, the pattern-replacer engine will attempt to infer its bitsize
 from the surrounding expression. (Not recommended.)
Flexible matching: 
 => (x + imm) will also be matched as (x - (-imm))
 => (x - imm) will also be matched as (x + (-imm))
 => (x * 2) will also be matched as (x << 1), and conversely, for all powers of 2
 => (x >= y) will also be matched as (y <= x), and the same goes for all inequality operators
 => (x OP y) with OP being a commutative operator will also be matched as (y OP x)
 => (x OP y OP z) can be used for associative operators +-&|^ and will match on any possible grouping

  • Method Details

    • cc

      public static DPatternCompiler.DPattern cc(String... inputStrings)
      Convenience method to quickly create and compile a single-input, no-output pattern.
      Parameters:
      inputStrings - input pattern lines
      Returns:
      the compiled pattern

    • cc

      public static DPatternCompiler.DPattern cc(int inputFlags, String... inputStrings)
      Convenience method to quickly create and compile a single-input, no-output pattern.
      Parameters:
      inputFlags - input pattern flags
      inputStrings - input pattern lines
      Returns:
      the compiled pattern

    • create

      public static DPatternCompiler.DPattern create()
      Create an unnamed pattern.
      Returns:
      a new pattern

    • create

      public static DPatternCompiler.DPattern create(String name)
      Create a pattern.
      Parameters:
      name - optional pattern name
      Returns:
      a new pattern

    • getName

      public String getName()
      Retrieve the pattern name.
      Returns:
      the pattern name, or null if unnamed

    • setInput

      public DPatternCompiler.DPattern setInput(String str)
      Set the sole input pattern.
      Parameters:
      str - input pattern line
      Returns:
      this pattern

    • setInput

      public DPatternCompiler.DPattern setInput(int flags, String str)
      Set the sole input pattern.
      Parameters:
      flags - input pattern flags
      str - input pattern line
      Returns:
      this pattern

    • addInput

      public DPatternCompiler.DPattern addInput(String... strings)
      Add an input pattern.
      Parameters:
      strings - input pattern lines
      Returns:
      this pattern

    • addInput

      public DPatternCompiler.DPattern addInput(int flags, String... strings)
      Add an input pattern.
      Parameters:
      flags - input pattern flags
      strings - input pattern lines
      Returns:
      this pattern

    • isPureInputExpression

      public boolean isPureInputExpression()
      Indicate if a pattern has only pure input expressions (meaning no assignment and only 1 expression). Otherwise, at least an input contains full statement OR/AND several items.
      Returns:
      true if all inputs are pure expressions

    • isPureOuputExpression

      public boolean isPureOuputExpression()
      Indicate if the result of a pattern replacement is a pure expression (only an expression is replaced). Otherwise, the result will modify one or more statements.
      Returns:
      true if the output is a pure expression

    • getInput

      public DPatternCompiler.DPattern.P getInput(int index)
      Retrieve an input pattern.
      Parameters:
      index - zero-based input index
      Returns:
      the input pattern

    • getInputs

      public List<DPatternCompiler.DPattern.P> getInputs()
      Retrieve the input patterns.
      Returns:
      the input patterns

    • setOutput

      public DPatternCompiler.DPattern setOutput(String... strings)
      Set the output replacement pattern.
      Parameters:
      strings - output pattern lines
      Returns:
      this pattern

    • setOutput

      public DPatternCompiler.DPattern setOutput(int flags, String... strings)
      Set the output replacement pattern.
      Parameters:
      flags - output pattern flags
      strings - output pattern lines
      Returns:
      this pattern

    • hasOutput

      public boolean hasOutput()
      Determine whether this pattern has an output replacement.
      Returns:
      true if an output replacement is defined

    • getOutput

      public DPatternCompiler.DPattern.P getOutput()
      Retrieve the output replacement pattern.
      Returns:
      the output pattern, or null if none is defined

    • setVerifier

      public DPatternCompiler.DPattern setVerifier(IDMatchVerifier verifier)
      Set a verifier called on candidate matches.
      Parameters:
      verifier - optional match verifier
      Returns:
      this pattern

    • getVerifier

      public IDMatchVerifier getVerifier()
      Retrieve the match verifier.
      Returns:
      the verifier, or null if none is defined

    • setCustomReplacer

      public DPatternCompiler.DPattern setCustomReplacer(IDPatternReplacer replacer)
      Set a custom replacer called for successful matches.
      Parameters:
      replacer - optional custom replacer
      Returns:
      this pattern

    • getCustomReplacer

      public IDPatternReplacer getCustomReplacer()
      Retrieve the custom replacer.
      Returns:
      the custom replacer, or null if none is defined

    • compile

      public DPatternCompiler.DPattern compile(DPatternCompiler compiler)
      Compile this pattern with the provided compiler.
      Parameters:
      compiler - compiler to use, or null for the default compiler
      Returns:
      this compiled pattern

    • compile

      public DPatternCompiler.DPattern compile()
      Compile this pattern with the default compiler.
      Returns:
      this compiled pattern

    • compile

      public DPatternCompiler.DPattern compile(int flags)
      Compile this pattern with temporary compiler flags.
      Parameters:
      flags - compiler flags
      Returns:
      this compiled pattern

    • isCompiled

      public boolean isCompiled()
      Determine whether this pattern was compiled.
      Returns:
      true if this pattern was compiled

    • toString

      public String toString()
      Overrides:
      toString in class Object