Merge branch 'dev' into feat/improve-fingerprint-api

# Conflicts: # src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt # src/main/kotlin/app/revanced/patcher/patch/Patch.kt # src/test/kotlin/app/revanced/patcher/PatcherTest.kt
Build log strings in suppliers
2025-10-01 11:30:50 +02:00 · 2024-10-27 16:03:43 +01:00 · 2024-10-27 15:59:52 +01:00 · 2024-10-27 15:48:26 +01:00 · 2024-10-27 15:44:49 +01:00 · 2024-10-27 04:40:06 +01:00
12 changed files with 242 additions and 508 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,69 +1,3 @@
-# [21.0.0](https://github.com/ReVanced/revanced-patcher/compare/v20.0.2...v21.0.0) (2024-11-05)
-
-
-### Bug Fixes
-
-* Match fingerprint before delegating the match property ([5d996de](https://github.com/ReVanced/revanced-patcher/commit/5d996def4d3de4e2bfc34562e5a6c7d89a8cddf0))
-* Merge extension only when patch executes ([#315](https://github.com/ReVanced/revanced-patcher/issues/315)) ([aa472eb](https://github.com/ReVanced/revanced-patcher/commit/aa472eb9857145b53b49f843406a9764fbb7e5ce))
-
-
-### Features
-
-* Improve Fingerprint API ([#316](https://github.com/ReVanced/revanced-patcher/issues/316)) ([0abf1c6](https://github.com/ReVanced/revanced-patcher/commit/0abf1c6c0279708fdef5cb66b141d07d17682693))
-* Improve various APIs  ([#317](https://github.com/ReVanced/revanced-patcher/issues/317)) ([b824978](https://github.com/ReVanced/revanced-patcher/commit/b8249789df8b90129f7b7ad0e523a8d0ceaab848))
-* Move fingerprint match members to fingerprint for ease of access by using context receivers ([0746c22](https://github.com/ReVanced/revanced-patcher/commit/0746c22743a9561bae2284d234b151f2f8511ca5))
-
-
-### Performance Improvements
-
-* Use smallest lookup map for strings ([1358d3f](https://github.com/ReVanced/revanced-patcher/commit/1358d3fa10cb8ba011b6b89cfe3684ecf9849d2f))
-
-
-### BREAKING CHANGES
-
-* Various APIs have been changed.
-* Many APIs have been changed.
-
-# [21.0.0-dev.4](https://github.com/ReVanced/revanced-patcher/compare/v21.0.0-dev.3...v21.0.0-dev.4) (2024-11-05)
-
-
-### Performance Improvements
-
-* Use smallest lookup map for strings ([1358d3f](https://github.com/ReVanced/revanced-patcher/commit/1358d3fa10cb8ba011b6b89cfe3684ecf9849d2f))
-
-# [21.0.0-dev.3](https://github.com/ReVanced/revanced-patcher/compare/v21.0.0-dev.2...v21.0.0-dev.3) (2024-11-05)
-
-
-### Features
-
-* Move fingerprint match members to fingerprint for ease of access by using context receivers ([0746c22](https://github.com/ReVanced/revanced-patcher/commit/0746c22743a9561bae2284d234b151f2f8511ca5))
-
-# [21.0.0-dev.2](https://github.com/ReVanced/revanced-patcher/compare/v21.0.0-dev.1...v21.0.0-dev.2) (2024-11-01)
-
-
-### Bug Fixes
-
-* Match fingerprint before delegating the match property ([5d996de](https://github.com/ReVanced/revanced-patcher/commit/5d996def4d3de4e2bfc34562e5a6c7d89a8cddf0))
-
-# [21.0.0-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v20.0.2...v21.0.0-dev.1) (2024-10-27)
-
-
-### Bug Fixes
-
-* Merge extension only when patch executes ([#315](https://github.com/ReVanced/revanced-patcher/issues/315)) ([aa472eb](https://github.com/ReVanced/revanced-patcher/commit/aa472eb9857145b53b49f843406a9764fbb7e5ce))
-
-
-### Features
-
-* Improve Fingerprint API ([#316](https://github.com/ReVanced/revanced-patcher/issues/316)) ([0abf1c6](https://github.com/ReVanced/revanced-patcher/commit/0abf1c6c0279708fdef5cb66b141d07d17682693))
-* Improve various APIs  ([#317](https://github.com/ReVanced/revanced-patcher/issues/317)) ([b824978](https://github.com/ReVanced/revanced-patcher/commit/b8249789df8b90129f7b7ad0e523a8d0ceaab848))
-
-
-### BREAKING CHANGES
-
-* Various APIs have been changed.
-* Many APIs have been changed.
-
 ## [20.0.2](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1...v20.0.2) (2024-10-17)


--- a/api/revanced-patcher.api
+++ b/api/revanced-patcher.api
@@ -1,22 +1,4 @@
 public final class app/revanced/patcher/Fingerprint {
-	public final fun getClassDef (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/util/proxy/mutableTypes/MutableClass;
-	public final fun getClassDefOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/util/proxy/mutableTypes/MutableClass;
-	public final fun getMethod (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/util/proxy/mutableTypes/MutableMethod;
-	public final fun getMethodOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/util/proxy/mutableTypes/MutableMethod;
-	public final fun getOriginalClassDef (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lcom/android/tools/smali/dexlib2/iface/ClassDef;
-	public final fun getOriginalClassDefOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lcom/android/tools/smali/dexlib2/iface/ClassDef;
-	public final fun getOriginalMethod (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lcom/android/tools/smali/dexlib2/iface/Method;
-	public final fun getOriginalMethodOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lcom/android/tools/smali/dexlib2/iface/Method;
-	public final fun getPatternMatch (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/Match$PatternMatch;
-	public final fun getPatternMatchOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Lapp/revanced/patcher/Match$PatternMatch;
-	public final fun getStringMatches (Lapp/revanced/patcher/patch/BytecodePatchContext;)Ljava/util/List;
-	public final fun getStringMatchesOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;)Ljava/util/List;
-	public final fun match (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/Match;
-	public final fun match (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/Method;)Lapp/revanced/patcher/Match;
-	public final fun match (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/Method;Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/Match;
-	public final fun matchOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/Match;
-	public final fun matchOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/Method;)Lapp/revanced/patcher/Match;
-	public final fun matchOrNull (Lapp/revanced/patcher/patch/BytecodePatchContext;Lcom/android/tools/smali/dexlib2/iface/Method;Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/Match;
 }

 public final class app/revanced/patcher/FingerprintBuilder {
@@ -49,11 +31,13 @@ public final class app/revanced/patcher/Match {
 }

 public final class app/revanced/patcher/Match$PatternMatch {
+	public fun <init> (II)V
 	public final fun getEndIndex ()I
 	public final fun getStartIndex ()I
 }

 public final class app/revanced/patcher/Match$StringMatch {
+	public fun <init> (Ljava/lang/String;I)V
 	public final fun getIndex ()I
 	public final fun getString ()Ljava/lang/String;
 }
@@ -162,7 +146,11 @@ public final class app/revanced/patcher/patch/BytecodePatchContext : app/revance
 	public synthetic fun get ()Ljava/lang/Object;
 	public fun get ()Ljava/util/Set;
 	public final fun getClasses ()Lapp/revanced/patcher/util/ProxyClassList;
-	public final fun navigate (Lcom/android/tools/smali/dexlib2/iface/reference/MethodReference;)Lapp/revanced/patcher/util/MethodNavigator;
+	public final fun getMatch (Lapp/revanced/patcher/Fingerprint;)Lapp/revanced/patcher/Match;
+	public final fun getValue (Lapp/revanced/patcher/Fingerprint;Ljava/lang/Void;Lkotlin/reflect/KProperty;)Lapp/revanced/patcher/Match;
+	public final fun match (Lapp/revanced/patcher/Fingerprint;Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/Match;
+	public final fun match (Lapp/revanced/patcher/Fingerprint;Lcom/android/tools/smali/dexlib2/iface/Method;)Lapp/revanced/patcher/Match;
+	public final fun navigate (Lcom/android/tools/smali/dexlib2/iface/Method;)Lapp/revanced/patcher/util/MethodNavigator;
 	public final fun proxy (Lcom/android/tools/smali/dexlib2/iface/ClassDef;)Lapp/revanced/patcher/util/proxy/ClassProxy;
 }

@@ -398,13 +386,18 @@ public final class app/revanced/patcher/patch/ResourcePatchBuilder : app/revance
 }

 public final class app/revanced/patcher/patch/ResourcePatchContext : app/revanced/patcher/patch/PatchContext {
-	public final fun delete (Ljava/lang/String;)Z
-	public final fun document (Ljava/io/InputStream;)Lapp/revanced/patcher/util/Document;
-	public final fun document (Ljava/lang/String;)Lapp/revanced/patcher/util/Document;
 	public fun get ()Lapp/revanced/patcher/PatcherResult$PatchedResources;
 	public synthetic fun get ()Ljava/lang/Object;
 	public final fun get (Ljava/lang/String;Z)Ljava/io/File;
 	public static synthetic fun get$default (Lapp/revanced/patcher/patch/ResourcePatchContext;Ljava/lang/String;ZILjava/lang/Object;)Ljava/io/File;
+	public final fun getDocument ()Lapp/revanced/patcher/patch/ResourcePatchContext$DocumentOperatable;
+	public final fun stageDelete (Lkotlin/jvm/functions/Function1;)Z
+}
+
+public final class app/revanced/patcher/patch/ResourcePatchContext$DocumentOperatable {
+	public fun <init> (Lapp/revanced/patcher/patch/ResourcePatchContext;)V
+	public final fun get (Ljava/io/InputStream;)Lapp/revanced/patcher/util/Document;
+	public final fun get (Ljava/lang/String;)Lapp/revanced/patcher/util/Document;
 }

 public final class app/revanced/patcher/util/Document : java/io/Closeable, org/w3c/dom/Document {
@@ -480,12 +473,11 @@ public final class app/revanced/patcher/util/Document : java/io/Closeable, org/w
 }

 public final class app/revanced/patcher/util/MethodNavigator {
-	public final fun getValue (Ljava/lang/Void;Lkotlin/reflect/KProperty;)Lapp/revanced/patcher/util/proxy/mutableTypes/MutableMethod;
-	public final fun original ()Lcom/android/tools/smali/dexlib2/iface/Method;
-	public final fun stop ()Lapp/revanced/patcher/util/proxy/mutableTypes/MutableMethod;
-	public final fun to (ILkotlin/jvm/functions/Function1;)Lapp/revanced/patcher/util/MethodNavigator;
-	public final fun to ([I)Lapp/revanced/patcher/util/MethodNavigator;
-	public static synthetic fun to$default (Lapp/revanced/patcher/util/MethodNavigator;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lapp/revanced/patcher/util/MethodNavigator;
+	public final fun at (ILkotlin/jvm/functions/Function1;)Lapp/revanced/patcher/util/MethodNavigator;
+	public final fun at ([I)Lapp/revanced/patcher/util/MethodNavigator;
+	public static synthetic fun at$default (Lapp/revanced/patcher/util/MethodNavigator;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lapp/revanced/patcher/util/MethodNavigator;
+	public final fun immutable ()Lcom/android/tools/smali/dexlib2/iface/Method;
+	public final fun mutable ()Lapp/revanced/patcher/util/proxy/mutableTypes/MutableMethod;
 }

 public final class app/revanced/patcher/util/ProxyClassList : java/util/List, kotlin/jvm/internal/markers/KMutableList {
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -56,8 +56,6 @@ dependencies {
 kotlin {
    compilerOptions {
        jvmTarget.set(JvmTarget.JVM_11)
-
-        freeCompilerArgs = listOf("-Xcontext-receivers")
    }
 }

--- a/docs/2_2_1_fingerprinting.md
+++ b/docs/2_2_1_fingerprinting.md
@@ -117,19 +117,15 @@ With this information, the original code can be reconstructed:
 ```java
 package com.some.app.ads;

-<accessFlags>
-
-class AdsLoader {
-    public final boolean <methodName>(boolean <parameter>)
-
-    {
+<accessFlags> class AdsLoader {
+    public final boolean <methodName>(boolean <parameter>) {
        // ...

        var userStatus = "pro";

        // ...

-        return <returnValue >;
+        return <returnValue>;
    }
 }
 ```
@@ -138,14 +134,13 @@ Using that fingerprint, this method can be matched uniquely from all other metho

 > [!TIP]
 > A fingerprint should contain information about a method likely to remain the same across updates.
-> A method's name is not included in the fingerprint because it will likely change with each update in an obfuscated
-> app.
-> In contrast, the return type, access flags, parameters, patterns of opcodes, and strings are likely to remain the
-> same.
+> A method's name is not included in the fingerprint because it will likely change with each update in an obfuscated app.
+> In contrast, the return type, access flags, parameters, patterns of opcodes, and strings are likely to remain the same.

 ## 🔨 How to use fingerprints

-After declaring a fingerprint, it can be used in a patch to find the method it matches to:
+A fingerprint is matched to a method,
+once the `match` property of the fingerprint is accessed in a patch's `execute` scope:

 ```kt
 val fingerprint = fingerprint {
@@ -154,34 +149,52 @@ val fingerprint = fingerprint {

 val patch = bytecodePatch {
    execute {
-        fingerprint.method
+        val match = fingerprint.match!!
    }
 }
 ```

-The fingerprint won't be matched again, if it has already been matched once, for performance reasons.
-This makes it useful, to share fingerprints between multiple patches,
-and let the first executing patch match the fingerprint:
+The fingerprint won't be matched again, if it has already been matched once.
+This makes it useful, to share fingerprints between multiple patches, and let the first patch match the fingerprint:

 ```kt
 // Either of these two patches will match the fingerprint first and the other patch can reuse the match:
 val mainActivityPatch1 = bytecodePatch {
    execute {
-        mainActivityOnCreateFingerprint.method
+        val match = mainActivityOnCreateFingerprint.match!!
    }
 }

 val mainActivityPatch2 = bytecodePatch {
    execute {
-        mainActivityOnCreateFingerprint.method
+        val match = mainActivityOnCreateFingerprint.match!!
+    }
+}
+```
+
+A fingerprint match can also be delegated to a variable for convenience without the need to check for `null`:
+```kt
+val fingerprint = fingerprint {
+    // ...
+}
+
+val patch = bytecodePatch {
+    execute {
+        // Alternative to fingerprint.match ?: throw PatchException("No match found")
+        val match by fingerprint.match
+
+        try {
+            match.method
+        } catch (e: PatchException) {
+            // Handle the exception for example.
+        }
    }
 }
 ```

 > [!WARNING]
-> If the fingerprint can not be matched to any method,
-> accessing certain properties of the fingerprint will raise an exception.
-> Instead, the `orNull` properties can be used to return `null` if no match is found.
+> If the fingerprint can not be matched to any method, the match of a fingerprint is `null`. If such a match is delegated
+> to a variable, accessing it will raise an exception.

 > [!TIP]
 > If a fingerprint has an opcode pattern, you can use the `fuzzyPatternScanThreshhold` parameter of the `opcode`
@@ -198,43 +211,47 @@ val mainActivityPatch2 = bytecodePatch {
 >    )
 >}
 > ```
+> 
+The match of a fingerprint contains references to the original method and class definition of the method:

-The following properties can be accessed in a fingerprint:
+```kt
+class Match(
+    val originalMethod: Method,
+    val originalClassDef: ClassDef,
+    val patternMatch: Match.PatternMatch?,
+    val stringMatches: List<Match.StringMatch>?,
+    // ...
+) {
+    val classDef by lazy { /* ... */ }
+    val method by lazy { /* ... */ }

- `originalClassDef`: The original class definition the fingerprint matches to.
- `originalClassDefOrNull`: The original class definition the fingerprint matches to.
- `originalMethod`: The original method the fingerprint matches to.
- `originalMethodOrNull`: The original method the fingerprint matches to.
- `classDef`: The class the fingerprint matches to.
- `classDefOrNull`: The class the fingerprint matches to.
- `method`: The method the fingerprint matches to. If no match is found, an exception is raised.
- `methodOrNull`: The method the fingerprint matches to.
+    // ...
+}
+```

-The difference between the `original` and non-`original` properties is that the `original` properties return the
-original class or method definition, while the non-`original` properties return a mutable copy of the class or method.
-The mutable copies can be modified. They are lazy properties, so they are only computed
-and only then will effectively replace the `original` method or class definition when accessed.
+The `classDef` and `method` properties can be used to make changes to the class or method.
+They are lazy properties, so they are only computed 
+and will effectively replace the original method or class definition when accessed.

 > [!TIP]
-> If only read-only access to the class or method is needed,
-> the `originalClassDef` and `originalMethod` properties should be used,
+> If only read-only access to the class or method is needed, 
+> the `originalClassDef` and `originalMethod` properties can be used, 
 > to avoid making a mutable copy of the class or method.

 ## 🏹 Manually matching fingerprints

-By default, a fingerprint is matched automatically against all classes
-when one of the fingerprint's properties is accessed.
+By default, a fingerprint is matched automatically against all classes when the `match` property is accessed.

 Instead, the fingerprint can be matched manually using various overloads of a fingerprint's `match` function:

 - In a **list of classes**, if the fingerprint can match in a known subset of classes

  If you have a known list of classes you know the fingerprint can match in,
-  you can match the fingerprint on the list of classes:
+you can match the fingerprint on the list of classes:

  ```kt
  execute {
-    val match = showAdsFingerprint(classes)
+    val match = showAdsFingerprint.match(classes) ?: throw PatchException("No match found")
  }
  ```

@@ -246,24 +263,23 @@ Instead, the fingerprint can be matched manually using various overloads of a fi
  execute {
    val adsLoaderClass = classes.single { it.name == "Lcom/some/app/ads/Loader;" }

-    val match = showAdsFingerprint.match(adsLoaderClass)
+    val match = showAdsFingerprint.match(context, adsLoaderClass) ?: throw PatchException("No match found")
  }
  ```
-
+  
  Another common usecase is to use a fingerprint to reduce the search space of a method to a single class.

  ```kt
  execute {
    // Match showAdsFingerprint in the class of the ads loader found by adsLoaderClassFingerprint.
-    val match = showAdsFingerprint.match(adsLoaderClassFingerprint.classDef)
+    val match by showAdsFingerprint.match(adsLoaderClassFingerprint.match!!.classDef)
  }
  ```

 - Match a **single method**, to extract certain information about it

  The match of a fingerprint contains useful information about the method,
-  such as the start and end index of an opcode pattern or the indices of the instructions with certain string
-  references.
+  such as the start and end index of an opcode pattern or the indices of the instructions with certain string references.
  A fingerprint can be leveraged to extract such information from a method instead of manually figuring it out:

  ```kt
@@ -272,19 +288,14 @@ Instead, the fingerprint can be matched manually using various overloads of a fi
      strings("free", "trial")
    }

-    currentPlanFingerprint.match(adsFingerprint.method).let { match ->
+    currentPlanFingerprint.match(adsFingerprintMatch.method)?.let { match ->
      match.stringMatches.forEach { match ->
        println("The index of the string '${match.string}' is ${match.index}")
      }
-    }
+    } ?: throw PatchException("No match found")
  }
  ```

-> [!WARNING]
-> If the fingerprint can not be matched to any method, calling `match` will raise an
-> exception.
-> Instead, the `orNull` overloads can be used to return `null` if no match is found.
-
 > [!TIP]
 > To see real-world examples of fingerprints,
 > check out the repository for [ReVanced Patches](https://github.com/revanced/revanced-patches).
--- a/docs/4_apis.md
+++ b/docs/4_apis.md
@@ -6,105 +6,14 @@ A handful of APIs are available to make patch development easier and more effici

 1. 👹 Create mutable replacements of classes with `proxy(ClassDef)`
 2. 🔍 Find and create mutable replaces with `classBy(Predicate)`
-3. 🏃‍ Navigate method calls recursively by index with `navigate(Method)`
-4. 💾 Read and write resource files with `get(String, Boolean)` and `delete(String)`
-5. 📃 Read and write DOM files using `document(String)` and  `document(InputStream)`
+3. 🏃‍ Navigate method calls recursively by index with `navigate(Method).at(index)`
+4. 💾 Read and write resource files with `get(Path, Boolean)`
+5. 📃 Read and write DOM files using `document`

 ### 🧰 APIs

-#### 👹 `proxy(ClassDef)`
-
-By default, the classes are immutable, meaning they cannot be modified.
-To make a class mutable, use the `proxy(ClassDef)` function.
-This function creates a lazy mutable copy of the class definition.
-Accessing the property will replace the original class definition with the mutable copy,
-thus allowing you to make changes to the class. Subsequent accesses will return the same mutable copy.
-
-```kt
-execute {
-    val mutableClass = proxy(classDef)
-    mutableClass.methods.add(Method())
-}
-```
-
-#### 🔍 `classBy(Predicate)`
-
-The `classBy(Predicate)` function is an alternative to finding and creating mutable classes by a predicate.
-It automatically proxies the class definition, making it mutable.
-
-```kt
-execute {
-    // Alternative to proxy(classes.find { it.name == "Lcom/example/MyClass;" })?.classDef
-    val classDef = classBy { it.name == "Lcom/example/MyClass;" }?.classDef
-}
-```
-
-#### 🏃‍ `navigate(Method).at(index)`
-
-The `navigate(Method)` function allows you to navigate method calls recursively by index.
-
-```kt
-execute {
-    // Sequentially navigate to the instructions at index 1 within 'someMethod'.
-    val method = navigate(someMethod).to(1).original() // original() returns the original immutable method.
-    
-    // Further navigate to the second occurrence where the instruction's opcode is 'INVOKEVIRTUAL'.
-    // stop() returns the mutable copy of the method.
-    val method = navigate(someMethod).to(2) { instruction -> instruction.opcode == Opcode.INVOKEVIRTUAL }.stop()
-    
-    // Alternatively, to stop(), you can delegate the method to a variable.
-    val method by navigate(someMethod).to(1)
-    
-    // You can chain multiple calls to at() to navigate deeper into the method.
-    val method by navigate(someMethod).to(1).to(2, 3, 4).to(5)
-}
-```
-
-#### 💾 `get(String, Boolean)` and `delete(String)`
-
-The `get(String, Boolean)` function returns a `File` object that can be used to read and write resource files.
-
-```kt
-execute {
-    val file = get("res/values/strings.xml")
-    val content = file.readText()
-    file.writeText(content)
-}
-```
-
-The `delete` function can mark files for deletion when the APK is rebuilt.
-
-```kt
-execute {
-    delete("res/values/strings.xml")
-}
-```
-
-#### 📃 `document(String)`  and  `document(InputStream)`
-
-The `document` function is used to read and write DOM files.
-
-```kt
-execute {
-    document("res/values/strings.xml").use { document ->
-        val element = doc.createElement("string").apply {
-            textContent = "Hello, World!"
-        }
-        document.documentElement.appendChild(element)
-    }
-}
-```
-
-You can also read documents from an `InputStream`:
-
-```kt
-execute {
-    val inputStream = classLoader.getResourceAsStream("some.xml")
-    document(inputStream).use { document ->
-        // ...
-    }
-}
-```
+> [!WARNING]
+> This section is still under construction and may be incomplete.

 ## 🎉 Afterword

@@ -112,6 +21,5 @@ ReVanced Patcher is a powerful library to patch Android applications, offering a
 that outlive app updates. Patches make up ReVanced; without you, the community of patch developers,
 ReVanced would not be what it is today. We hope that this documentation has been helpful to you
 and are excited to see what you will create with ReVanced Patcher. If you have any questions or need help,
-talk to us on one of our platforms linked on [revanced.app](https://revanced.app) or open an issue in case of a bug or
-feature request,  
+talk to us on one of our platforms linked on [revanced.app](https://revanced.app) or open an issue in case of a bug or feature request,  
 ReVanced
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,3 +1,3 @@
 org.gradle.parallel = true
 org.gradle.caching = true
-version = 21.0.0
+version = 20.0.2
--- a/src/main/kotlin/app/revanced/patcher/Fingerprint.kt
+++ b/src/main/kotlin/app/revanced/patcher/Fingerprint.kt
--- a/src/main/kotlin/app/revanced/patcher/PatcherResult.kt
+++ b/src/main/kotlin/app/revanced/patcher/PatcherResult.kt
@@ -29,12 +29,12 @@ class PatcherResult internal constructor(
     * @param resourcesApk The compiled resources.apk file.
     * @param otherResources The directory containing other resources files.
     * @param doNotCompress List of files that should not be compressed.
-     * @param deleteResources List of resources that should be deleted.
+     * @param deleteResources List of predicates about resources that should be deleted.
     */
    class PatchedResources internal constructor(
        val resourcesApk: File?,
        val otherResources: File?,
        val doNotCompress: Set<String>,
-        val deleteResources: Set<String>,
+        val deleteResources: Set<(String) -> Boolean>,
    )
 }
--- a/src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt
+++ b/src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt
@@ -1,8 +1,6 @@
 package app.revanced.patcher.patch

-import app.revanced.patcher.InternalApi
-import app.revanced.patcher.PatcherConfig
-import app.revanced.patcher.PatcherResult
+import app.revanced.patcher.*
 import app.revanced.patcher.extensions.InstructionExtensions.instructionsOrNull
 import app.revanced.patcher.util.ClassMerger.merge
 import app.revanced.patcher.util.MethodNavigator
@@ -14,7 +12,6 @@ import com.android.tools.smali.dexlib2.iface.ClassDef
 import com.android.tools.smali.dexlib2.iface.DexFile
 import com.android.tools.smali.dexlib2.iface.Method
 import com.android.tools.smali.dexlib2.iface.instruction.ReferenceInstruction
-import com.android.tools.smali.dexlib2.iface.reference.MethodReference
 import com.android.tools.smali.dexlib2.iface.reference.StringReference
 import lanchon.multidexlib2.BasicDexFileNamer
 import lanchon.multidexlib2.DexIO
@@ -24,6 +21,7 @@ import java.io.Closeable
 import java.io.FileFilter
 import java.util.*
 import java.util.logging.Logger
+import kotlin.reflect.KProperty

 /**
 * A context for patches containing the current state of the bytecode.
@@ -34,7 +32,7 @@ import java.util.logging.Logger
 class BytecodePatchContext internal constructor(private val config: PatcherConfig) :
    PatchContext<Set<PatcherResult.PatchedDexFile>>,
    Closeable {
-    private val logger = Logger.getLogger(this::javaClass.name)
+    private val logger = Logger.getLogger(BytecodePatchContext::class.java.name)

    /**
     * [Opcodes] of the supplied [PatcherConfig.apkFile].
@@ -54,6 +52,36 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
        ).also { opcodes = it.opcodes }.classes.toMutableList(),
    )

+    /**
+     * The match for this [Fingerprint]. Null if unmatched.
+     */
+    val Fingerprint.match get() = match(this@BytecodePatchContext)
+
+    /**
+     * Match using a [ClassDef].
+     *
+     * @param classDef The class to match against.
+     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
+     */
+    fun Fingerprint.match(classDef: ClassDef) = match(this@BytecodePatchContext, classDef)
+
+    /**
+     * Match using a [Method].
+     * The class is retrieved from the method.
+     *
+     * @param method The method to match against.
+     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
+     */
+    fun Fingerprint.match(method: Method) = match(this@BytecodePatchContext, method)
+
+    /**
+     * Get the match for this [Fingerprint].
+     *
+     * @throws IllegalStateException If the [Fingerprint] has not been matched.
+     */
+    operator fun Fingerprint.getValue(nothing: Nothing?, property: KProperty<*>): Match = _match
+        ?: throw PatchException("No fingerprint match to delegate to \"${property.name}\".")
+
    /**
     * The lookup maps for methods and the class they are a member of from the [classes].
     */
@@ -108,9 +136,9 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
     *
     * @return A proxy for the class.
     */
-    fun proxy(classDef: ClassDef) = classes.proxyPool.find {
+    fun proxy(classDef: ClassDef) = this@BytecodePatchContext.classes.proxyPool.find {
        it.immutableClass.type == classDef.type
-    } ?: ClassProxy(classDef).also { classes.proxyPool.add(it) }
+    } ?: ClassProxy(classDef).also { this@BytecodePatchContext.classes.proxyPool.add(it) }

    /**
     * Navigate a method.
@@ -119,7 +147,7 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
     *
     * @return A [MethodNavigator] for the method.
     */
-    fun navigate(method: MethodReference) = MethodNavigator(method)
+    fun navigate(method: Method) = MethodNavigator(this@BytecodePatchContext, method)

    /**
     * Compile bytecode from the [BytecodePatchContext].
@@ -198,6 +226,28 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
            }
        }

+        internal companion object {
+            /**
+             * Appends a string based on the parameter reference types of this method.
+             */
+            internal fun StringBuilder.appendParameters(parameters: Iterable<CharSequence>) {
+                // Maximum parameters to use in the signature key.
+                // Some apps have methods with an incredible number of parameters (over 100 parameters have been seen).
+                // To keep the signature map from becoming needlessly bloated,
+                // group together in the same map entry all methods with the same access/return and 5 or more parameters.
+                // The value of 5 was chosen based on local performance testing and is not set in stone.
+                val maxSignatureParameters = 5
+                // Must append a unique value before the parameters to distinguish this key includes the parameters.
+                // If this is not appended, then methods with no parameters
+                // will collide with different keys that specify access/return but omit the parameters.
+                append("p:")
+                parameters.forEachIndexed { index, parameter ->
+                    if (index >= maxSignatureParameters) return
+                    append(parameter.first())
+                }
+            }
+        }
+
        override fun close() {
            methodsByStrings.clear()
            classesByType.clear()
--- a/src/main/kotlin/app/revanced/patcher/patch/ResourcePatchContext.kt
+++ b/src/main/kotlin/app/revanced/patcher/patch/ResourcePatchContext.kt
@@ -31,20 +31,15 @@ class ResourcePatchContext internal constructor(
 ) : PatchContext<PatcherResult.PatchedResources?> {
    private val logger = Logger.getLogger(ResourcePatchContext::class.java.name)

-    /**
-     * Read a document from an [InputStream].
-     */
-    fun document(inputStream: InputStream) = Document(inputStream)
-
    /**
     * Read and write documents in the [PatcherConfig.apkFiles].
     */
-    fun document(path: String) = Document(get(path))
+    val document = DocumentOperatable()

    /**
-     * Set of resources from [PatcherConfig.apkFiles] to delete.
+     * Predicate to delete resources from [PatcherConfig.apkFiles].
     */
-    private val deleteResources = mutableSetOf<String>()
+    private val deleteResources = mutableSetOf<(String) -> Boolean>()

    /**
     * Decode resources of [PatcherConfig.apkFile].
@@ -206,11 +201,11 @@ class ResourcePatchContext internal constructor(
    }

    /**
-     * Mark a file for deletion when the APK is rebuilt.
+     * Stage a file to be deleted from [PatcherConfig.apkFile].
     *
-     * @param name The name of the file to delete.
+     * @param shouldDelete The predicate to stage the file for deletion given its name.
     */
-    fun delete(name: String) = deleteResources.add(name)
+    fun stageDelete(shouldDelete: (String) -> Boolean) = deleteResources.add(shouldDelete)

    /**
     * How to handle resources decoding and compiling.
@@ -232,4 +227,10 @@ class ResourcePatchContext internal constructor(
         */
        NONE,
    }
+
+    inner class DocumentOperatable {
+        operator fun get(inputStream: InputStream) = Document(inputStream)
+
+        operator fun get(path: String) = Document(this@ResourcePatchContext[path])
+    }
 }
--- a/src/main/kotlin/app/revanced/patcher/util/MethodNavigator.kt
+++ b/src/main/kotlin/app/revanced/patcher/util/MethodNavigator.kt
@@ -12,11 +12,11 @@ import com.android.tools.smali.dexlib2.iface.instruction.Instruction
 import com.android.tools.smali.dexlib2.iface.instruction.ReferenceInstruction
 import com.android.tools.smali.dexlib2.iface.reference.MethodReference
 import com.android.tools.smali.dexlib2.util.MethodUtil
-import kotlin.reflect.KProperty

 /**
 * A navigator for methods.
 *
+ * @param context The [BytecodePatchContext] to use.
 * @param startMethod The [Method] to start navigating from.
 *
 * @constructor Creates a new [MethodNavigator].
@@ -24,16 +24,12 @@ import kotlin.reflect.KProperty
 * @throws NavigateException If the method does not have an implementation.
 * @throws NavigateException If the instruction at the specified index is not a method reference.
 */
-context(BytecodePatchContext)
-class MethodNavigator internal constructor(
-    private var startMethod: MethodReference,
-) {
+class MethodNavigator internal constructor(private val context: BytecodePatchContext, private var startMethod: MethodReference) {
    private var lastNavigatedMethodReference = startMethod

-    private val lastNavigatedMethodInstructions
-        get() = with(original()) {
-            instructionsOrNull ?: throw NavigateException("Method $this does not have an implementation.")
-        }
+    private val lastNavigatedMethodInstructions get() = with(immutable()) {
+        instructionsOrNull ?: throw NavigateException("Method $definingClass.$name does not have an implementation.")
+    }

    /**
     * Navigate to the method at the specified index.
@@ -42,7 +38,7 @@ class MethodNavigator internal constructor(
     *
     * @return This [MethodNavigator].
     */
-    fun to(vararg index: Int): MethodNavigator {
+    fun at(vararg index: Int): MethodNavigator {
        index.forEach {
            lastNavigatedMethodReference = lastNavigatedMethodInstructions.getMethodReferenceAt(it)
        }
@@ -56,7 +52,7 @@ class MethodNavigator internal constructor(
     * @param index The index of the method to navigate to.
     * @param predicate The predicate to match.
     */
-    fun to(index: Int = 0, predicate: (Instruction) -> Boolean): MethodNavigator {
+    fun at(index: Int = 0, predicate: (Instruction) -> Boolean): MethodNavigator {
        lastNavigatedMethodReference = lastNavigatedMethodInstructions.asSequence()
            .filter(predicate).asIterable().getMethodReferenceAt(index)

@@ -80,22 +76,15 @@ class MethodNavigator internal constructor(
     *
     * @return The last navigated method mutably.
     */
-    fun stop() = classBy(matchesCurrentMethodReferenceDefiningClass)!!.mutableClass.firstMethodBySignature
+    fun mutable() = context.classBy(matchesCurrentMethodReferenceDefiningClass)!!.mutableClass.firstMethodBySignature
        as MutableMethod

-    /**
-     * Get the last navigated method mutably.
-     *
-     * @return The last navigated method mutably.
-     */
-    operator fun getValue(nothing: Nothing?, property: KProperty<*>) = stop()
-
    /**
     * Get the last navigated method immutably.
     *
     * @return The last navigated method immutably.
     */
-    fun original(): Method = classes.first(matchesCurrentMethodReferenceDefiningClass).firstMethodBySignature
+    fun immutable() = context.classes.first(matchesCurrentMethodReferenceDefiningClass).firstMethodBySignature

    /**
     * Predicate to match the class defining the current method reference.
@@ -107,10 +96,9 @@ class MethodNavigator internal constructor(
    /**
     * Find the first [lastNavigatedMethodReference] in the class.
     */
-    private val ClassDef.firstMethodBySignature
-        get() = methods.first {
-            MethodUtil.methodSignaturesMatch(it, lastNavigatedMethodReference)
-        }
+    private val ClassDef.firstMethodBySignature get() = methods.first {
+        MethodUtil.methodSignaturesMatch(it, lastNavigatedMethodReference)
+    }

    /**
     * An exception thrown when navigating fails.
--- a/src/test/kotlin/app/revanced/patcher/PatcherTest.kt
+++ b/src/test/kotlin/app/revanced/patcher/PatcherTest.kt
@@ -3,18 +3,21 @@ package app.revanced.patcher
 import app.revanced.patcher.patch.*
 import app.revanced.patcher.patch.BytecodePatchContext.LookupMaps
 import app.revanced.patcher.util.ProxyClassList
+import com.android.tools.smali.dexlib2.iface.ClassDef
+import com.android.tools.smali.dexlib2.iface.Method
 import com.android.tools.smali.dexlib2.immutable.ImmutableClassDef
 import com.android.tools.smali.dexlib2.immutable.ImmutableMethod
-import io.mockk.*
+import io.mockk.every
+import io.mockk.just
+import io.mockk.mockk
+import io.mockk.runs
+import jdk.internal.module.ModuleBootstrap.patcher
 import kotlinx.coroutines.flow.toList
 import kotlinx.coroutines.runBlocking
 import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.assertAll
 import java.util.logging.Logger
-import kotlin.test.Test
-import kotlin.test.assertEquals
-import kotlin.test.assertNotNull
-import kotlin.test.assertTrue
+import kotlin.test.*

 internal object PatcherTest {
    private lateinit var patcher: Patcher
@@ -150,10 +153,10 @@ internal object PatcherTest {
        val patch = bytecodePatch {
            execute {
                // Fingerprint can never match.
-                val fingerprint = fingerprint { }
+                val match by fingerprint { }

                // Throws, because the fingerprint can't be matched.
-                fingerprint.patternMatch
+                match.patternMatch
            }
        }

@@ -190,6 +193,11 @@ internal object PatcherTest {
                ),
            ),
        )
+        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match } } answers { callOriginal() }
+        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match(any<ClassDef>()) } } answers { callOriginal() }
+        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match(any<Method>()) } } answers { callOriginal() }
+        every { patcher.context.bytecodeContext.classBy(any()) } answers { callOriginal() }
+        every { patcher.context.bytecodeContext.proxy(any()) } answers { callOriginal() }

        val fingerprint = fingerprint { returns("V") }
        val fingerprint2 = fingerprint { returns("V") }
@@ -200,21 +208,19 @@ internal object PatcherTest {
                execute {
                    fingerprint.match(classes.first().methods.first())
                    fingerprint2.match(classes.first())
-                    fingerprint3.originalClassDef
+                    fingerprint3.match
                }
            },
        )

        patches()

-        with(patcher.context.bytecodeContext) {
-            assertAll(
-                "Expected fingerprints to match.",
-                { assertNotNull(fingerprint.originalClassDefOrNull) },
-                { assertNotNull(fingerprint2.originalClassDefOrNull) },
-                { assertNotNull(fingerprint3.originalClassDefOrNull) },
-            )
-        }
+        assertAll(
+            "Expected fingerprints to match.",
+            { assertNotNull(fingerprint._match) },
+            { assertNotNull(fingerprint2._match) },
+            { assertNotNull(fingerprint3._match) },
+        )
    }

    private operator fun Set<Patch<*>>.invoke(): List<PatchResult> {
Author	SHA1	Message	Date
oSumAtrIX	e41504bd99	Merge branch 'dev' into feat/improve-fingerprint-api # Conflicts: # src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt # src/main/kotlin/app/revanced/patcher/patch/Patch.kt # src/test/kotlin/app/revanced/patcher/PatcherTest.kt	2024-10-27 16:03:43 +01:00
oSumAtrIX	35b85b2c29	Build log strings in suppliers	2024-10-27 15:59:52 +01:00
oSumAtrIX	f62e952514	add common usecase example	2024-10-27 15:48:26 +01:00
oSumAtrIX	635d23c9b7	add notice regarding using immutable references	2024-10-27 15:44:49 +01:00
oSumAtrIX	5a0e3841ff	more nesting fixes	2024-10-27 04:40:06 +01:00
oSumAtrIX	cfb459b832	fix nesting	2024-10-27 04:37:40 +01:00
oSumAtrIX	2096306107	fix nesting	2024-10-27 04:37:20 +01:00
oSumAtrIX	92eaba8081	feat: Improve Fingerprint API Fingerprints can now be matched easily without having to add them to a patch first. BREAKING CHANGE: Many APIs have been changed.	2024-10-27 04:31:43 +01:00
oSumAtrIX	7be0cd8548	fix: Merge extension only when patch executes	2024-10-26 23:23:36 +02:00