code documentation

Author: LisoUseInAIKyrios

api/revanced-patcher.api

@@ -178,8 +178,6 @@ public final class app/revanced/patcher/OpcodeFilter$Companion {
 }
 
 public class app/revanced/patcher/OpcodesFilter : app/revanced/patcher/InstructionFilter {
-	public fun <init> (Ljava/util/EnumSet;I)V
-	public synthetic fun <init> (Ljava/util/EnumSet;IILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun <init> (Ljava/util/List;I)V
 	public synthetic fun <init> (Ljava/util/List;IILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getOpcodes ()Ljava/util/EnumSet;

build.gradle.kts

@@ -115,5 +115,6 @@ publishing {
 
 signing {
     useGpgCmd()
+    // NOTE: If doing local dev work then comment out or remove this sign task.
     sign(publishing.publications["revanced-patcher-publication"])
 }

src/main/kotlin/app/revanced/patcher/Fingerprint.kt

@@ -81,7 +81,7 @@ class Fingerprint internal constructor(
     private var _matchOrNull: Match? = null
 
     /**
-     * The match for this [Fingerprint], or Null if no matches exist.
+     * The match for this [Fingerprint], or `null` if no matches exist.
      */
     fun matchOrNull(): Match? {
         if (_matchOrNull != null) return _matchOrNull
@@ -619,7 +619,10 @@ class FingerprintBuilder(val name: String) {
     }
 
     /**
-     * Set the opcodes.
+     * A pattern of opcodes.
+     *
+     * To use opcodes with other [InstructionFilter] objects, instead use
+     * [instructions] with individual opcodes declared using [OpcodeFilter].
      *
      * @param opcodes An opcode pattern of instructions.
      * Wildcard or unknown opcodes can be specified by `null`.

src/main/kotlin/app/revanced/patcher/InstructionFilter.kt

@@ -14,6 +14,24 @@ import com.android.tools.smali.dexlib2.iface.reference.TypeReference
 import java.util.EnumSet
 import kotlin.collections.forEach
 
+/**
+ * Matches method [Instruction] objects, similar to how [Fingerprint] matches entire fingerprints.
+ *
+ * The most basic filters match only opcodes and nothing more,
+ * and more precise filters can match:
+ * - Field references (get/put opcodes) by name/type.
+ * - Method calls (invoke_* opcodes) by name/parameter/return type.
+ * - Object instantiation for specific class types.
+ * - Literal const values.
+ *
+ * Variable space is allowed between each filter.
+ *
+ * By default [OpcodeFilter] and [OpcodesFilter] use a default [maxInstructionsBefore] of zero,
+ * meaning the opcode must be immediately after the previous filter.
+ *
+ * All other filters use a default [maxInstructionsBefore] of [METHOD_MAX_INSTRUCTIONS] meaning
+ * they can match anywhere after the previous filter.
+ */
 abstract class InstructionFilter(
     /**
      * Maximum number of non matching method instructions that can appear before this filter.
@@ -23,6 +41,12 @@ abstract class InstructionFilter(
     val maxInstructionsBefore: Int = METHOD_MAX_INSTRUCTIONS
 ) {
 
+    /**
+     * If this filter matches the method instruction.
+     *
+     * method index can be ignored unless a filter has an unusual reason,
+     * such as checking for the last index of a method.
+     */
     abstract fun matches(
         method: Method,
         instruction: Instruction,
@@ -32,6 +56,7 @@ abstract class InstructionFilter(
     companion object {
         /**
          * Maximum number of instructions allowed in a Java method.
+         * Indicates to allow a match anywhere after the previous filter.
          */
         const val METHOD_MAX_INSTRUCTIONS = 65535
     }
@@ -54,6 +79,7 @@ class AnyFilter(
     }
 }
 
+
 /**
  * Single opcode.
  */
@@ -71,6 +97,12 @@ class OpcodeFilter(
     }
 
     companion object {
+        /**
+         * First opcode can match anywhere in a method, but all
+         * subsequent opcodes must match after the previous opcode.
+         *
+         * A value of `null` indicates to match any opcode.
+         */
         fun listOfOpcodes(opcodes: Collection<Opcode?>): List<InstructionFilter> {
             var list = ArrayList<InstructionFilter>(opcodes.size)
 
@@ -91,21 +123,19 @@ class OpcodeFilter(
     }
 }
 
+
 /**
  * Matches multiple opcodes.
  * If using only a single opcode instead use [OpcodeFilter].
  */
-open class OpcodesFilter(
-    /**
-     * Value of null will match any opcode.
-     */
+open class OpcodesFilter private constructor(
     val opcodes: EnumSet<Opcode>?,
-    maxInstructionsBefore: Int = METHOD_MAX_INSTRUCTIONS,
+    maxInstructionsBefore: Int,
 ) : InstructionFilter(maxInstructionsBefore) {
 
     constructor(
         /**
-         * Value of null will match any opcode.
+         * Value of `null` will match any opcode.
          */
         opcodes: List<Opcode>?,
         maxInstructionsBefore: Int = METHOD_MAX_INSTRUCTIONS
@@ -119,18 +149,31 @@ open class OpcodesFilter(
         if (opcodes == null) {
             return true // Match anything.
         }
-        return opcodes.contains(instruction.opcode) == true
+        return opcodes.contains(instruction.opcode)
     }
 }
 
+
+/**
+ * Literal value, such as:
+ * `const v1, 0x7f080318`
+ *
+ * that can be matched using:
+ * `LiteralFilter(0x7f080318)`
+ * or
+ * `LiteralFilter(2131231512)`
+ *
+ * Use a lambda if the literal is not known at the declaration of this object such as:
+ * `LiteralFilter({ OtherClass.findLiteralToUse() })`
+ */
 class LiteralFilter(
     var literal: () -> Long,
     opcodes: List<Opcode>? = null,
     maxInstructionsBefore: Int = METHOD_MAX_INSTRUCTIONS,
 ) : OpcodesFilter(opcodes, maxInstructionsBefore) {
 
     /**
-     * Constant long literal.
+     * Integer/Long literal.
      */
     constructor(
         literal : Long,
@@ -160,6 +203,19 @@ class LiteralFilter(
     }
 }
 
+/**
+ * Filters opcode method calls.
+ *
+ * `Null` parameters matches anything.
+ *
+ * By default any type of method call matches.
+ * Specify opcodes if a specific type of method call is desired (such as only static calls).
+ *
+ * Fingerprints can be used to find obfuscated class/method names to filter with,
+ * such as:
+ * `MethodFilter(definingClass = { fingerprint.originalClassDef.type },
+ *    methodName = { fingerprint.originalMethod.name })`
+ */
 class MethodFilter (
     /**
      * Defining class of the method call. Matches using endsWith().
@@ -310,40 +366,42 @@ class MethodFilter (
         private val regex = Regex("""^(L[^;]+;)->([^(\s]+)\(([^)]*)\)(.+)$""")
 
         /**
-         * Returns a filter for a JVM-style method signature. e.g.:
+         * Returns a filter for a copy pasted JVM-style method signature. e.g.:
          * Landroid/view/View;->inflate(Landroid/content/Context;ILandroid/view/ViewGroup;)Landroid/view/View;
+         *
+         * Does not support obfuscated method names or parameter/return types.
          */
         fun parseJvmMethodCall(
             methodSignature: String,
         ) = parseJvmMethodCall(methodSignature, null, METHOD_MAX_INSTRUCTIONS)
 
         /**
-         * Returns a filter for a JVM-style method signature. e.g.:
+         * Returns a filter for a copy pasted JVM-style method signature. e.g.:
          * Landroid/view/View;->inflate(Landroid/content/Context;ILandroid/view/ViewGroup;)Landroid/view/View;
          *
-         * Does not support obfuscated method names or parameter/return types
+         * Does not support obfuscated method names or parameter/return types.
          */
         fun parseJvmMethodCall(
             methodSignature: String,
             maxInstructionsBefore: Int
         ) = parseJvmMethodCall(methodSignature, null, maxInstructionsBefore)
 
         /**
-         * Returns a filter for a JVM-style method signature. e.g.:
+         * Returns a filter for a copy pasted JVM-style method signature. e.g.:
          * Landroid/view/View;->inflate(Landroid/content/Context;ILandroid/view/ViewGroup;)Landroid/view/View;
          *
-         * Does not support obfuscated method names or parameter/return types
+         * Does not support obfuscated method names or parameter/return types.
          */
         fun parseJvmMethodCall(
             methodSignature: String,
             opcodes: List<Opcode>?,
         ) = parseJvmMethodCall(methodSignature, opcodes, METHOD_MAX_INSTRUCTIONS)
 
         /**
-         * Returns a filter for a JVM-style method signature. e.g.:
+         * Returns a filter for a copy pasted JVM-style method signature. e.g.:
          * Landroid/view/View;->inflate(Landroid/content/Context;ILandroid/view/ViewGroup;)Landroid/view/View;
          *
-         * Does not support obfuscated method names or parameter/return types
+         * Does not support obfuscated method names or parameter/return types.
          */
         fun parseJvmMethodCall(
             methodSignature: String,
@@ -415,14 +473,23 @@ class MethodFilter (
     }
 }
 
+/**
+ * Matches a field call, such as:
+ * `iget-object v0, p0, Lahhh;->g:Landroid/view/View;`
+ *
+ * Using filter:
+ * `FieldFilter(type ="Landroid/view/View;", opcode = Opcode.IGET_OBJECT)`
+ *
+ * If the field is a call to the defining class, use `this` as the declaring class:
+ * `FieldFilter(definingClass = "this", type ="Landroid/view/View;", opcode = Opcode.IGET_OBJECT)`
+ */
 class FieldFilter(
     /**
      * Defining class of the field call. Matches using endsWith().
      *
      * For calls to a method in the same class, use 'this' as the defining class.
      * Note: 'this' does not work for fields found in superclasses.
      */
-
     val definingClass: (() -> String)? = null,
     /**
      * Name of the field.  Must be a full match of the field name.