chore(release): 3.1.0 [skip ci]

# [3.1.0](https://github.com/revanced/revanced-patcher/compare/v3.0.0...v3.1.0) (2022-08-02)

### Features

* validator for patch options ([4e2e772](4e2e772389))

.github/ISSUE_TEMPLATE/bug-issue.yml

@@ -51,10 +51,10 @@ body:
       label: Solution
       description: If applicable, add a possible solution.
     validations:
-      required: true
+      required: false
   - type: textarea
     attributes:
       label: Additional context
       description: Add additional context here.
     validations:
-      required: false
+      required: false

CHANGELOG.md

@@ -1,3 +1,53 @@
+# [3.1.0](https://github.com/revanced/revanced-patcher/compare/v3.0.0...v3.1.0) (2022-08-02)
+
+
+### Features
+
+* validator for patch options ([4e2e772](https://github.com/revanced/revanced-patcher/commit/4e2e77238957d7732326cfe5e05145bf7dab5bfb))
+
+# [3.0.0](https://github.com/revanced/revanced-patcher/compare/v2.9.0...v3.0.0) (2022-08-02)
+
+
+### Features
+
+* registry for patch options ([2431785](https://github.com/revanced/revanced-patcher/commit/2431785d0e494d6271c6951eec9adfff9db95c17))
+
+
+### BREAKING CHANGES
+
+* Patch options now use the PatchOptions registry class instead of an Iterable. This change requires modifications to existing patches using this API.
+
+# [2.9.0](https://github.com/revanced/revanced-patcher/compare/v2.8.0...v2.9.0) (2022-08-02)
+
+
+### Bug Fixes
+
+* show error message instead of `null` ([8d95b14](https://github.com/revanced/revanced-patcher/commit/8d95b14f350b47ec029f35e776f6e627aaf5f607))
+
+
+### Features
+
+* exclusive mutable access to files ([814ce0b](https://github.com/revanced/revanced-patcher/commit/814ce0b9ae29725417c86b7d11b40d025724a426))
+
+# [2.8.0](https://github.com/revanced/revanced-patcher/compare/v2.7.0...v2.8.0) (2022-08-01)
+
+
+### Bug Fixes
+
+* remove requirement for solution [skip ci] ([#80](https://github.com/revanced/revanced-patcher/issues/80)) ([9a4d30e](https://github.com/revanced/revanced-patcher/commit/9a4d30e15234ef62844f035c58a1143674d4c12e))
+
+
+### Features
+
+* patch options ([#81](https://github.com/revanced/revanced-patcher/issues/81)) ([fbb09f3](https://github.com/revanced/revanced-patcher/commit/fbb09f38dce49adc7f63b71bdf2df2ef0b84db04))
+
+# [2.7.0](https://github.com/revanced/revanced-patcher/compare/v2.6.0...v2.7.0) (2022-08-01)
+
+
+### Features
+
+* `Closeable` patches ([bbd40bf](https://github.com/revanced/revanced-patcher/commit/bbd40bf2f6ff200705f2bcb272dd1680bb244e3f))
+
 # [2.6.0](https://github.com/revanced/revanced-patcher/compare/v2.5.2...v2.6.0) (2022-07-31)
 
 

gradle.properties

@@ -1,2 +1,2 @@
 kotlin.code.style = official
-version = 2.6.0
+version = 3.1.0

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

@@ -11,7 +11,6 @@ import app.revanced.patcher.patch.Patch
 import app.revanced.patcher.patch.PatchResult
 import app.revanced.patcher.patch.PatchResultError
 import app.revanced.patcher.patch.PatchResultSuccess
-import app.revanced.patcher.patch.annotations.DependencyType
 import app.revanced.patcher.patch.impl.BytecodePatch
 import app.revanced.patcher.patch.impl.ResourcePatch
 import app.revanced.patcher.util.ListBackedSet
@@ -32,6 +31,7 @@ import org.jf.dexlib2.Opcodes
 import org.jf.dexlib2.iface.ClassDef
 import org.jf.dexlib2.iface.DexFile
 import org.jf.dexlib2.writer.io.MemoryDataStore
+import java.io.Closeable
 import java.io.File
 import java.nio.file.Files
 
@@ -247,13 +247,13 @@ class Patcher(private val options: PatcherOptions) {
      */
     private fun applyPatch(
         patch: Class<out Patch<Data>>,
-        appliedPatches: MutableMap<String, Boolean>
+        appliedPatches: LinkedHashMap<String, AppliedPatch>
     ): PatchResult {
         val patchName = patch.patchName
 
         // if the patch has already applied silently skip it
         if (appliedPatches.contains(patchName)) {
-            if (!appliedPatches[patchName]!!)
+            if (!appliedPatches[patchName]!!.success)
                 return PatchResultError("'$patchName' did not succeed previously")
 
             logger.trace("Skipping '$patchName' because it has already been applied")
@@ -264,16 +264,13 @@ class Patcher(private val options: PatcherOptions) {
         // recursively apply all dependency patches
         patch.dependencies.forEach {
             val dependency = it.patch.java
-            if ( // soft dependencies must be included manually.
-                it.type == DependencyType.SOFT && !data.patches.any { p ->
-                    p.patchName == dependency.patchName
-                }
-            ) return@forEach
 
             val result = applyPatch(dependency, appliedPatches)
             if (result.isSuccess()) return@forEach
 
-            val errorMessage = result.error()!!.cause
+            val error = result.error()!!
+            val errorMessage = error.cause ?: error.message
+
             return PatchResultError("'$patchName' depends on '${dependency.patchName}' but the following error was raised: $errorMessage")
         }
 
@@ -298,10 +295,10 @@ class Patcher(private val options: PatcherOptions) {
 
         return try {
             val result = patchInstance.execute(data)
-            appliedPatches[patchName] = result.isSuccess()
+            appliedPatches[patchName] = AppliedPatch(patchInstance, result.isSuccess())
             result
         } catch (e: Exception) {
-            appliedPatches[patchName] = false
+            appliedPatches[patchName] = AppliedPatch(patchInstance, false)
             PatchResultError(e)
         }
     }
@@ -313,23 +310,41 @@ class Patcher(private val options: PatcherOptions) {
      */
     fun applyPatches(stopOnError: Boolean = false) = sequence {
         logger.trace("Applying all patches")
-        val appliedPatches = mutableMapOf<String, Boolean>() // first is success, second is name
 
-        for (patch in data.patches) {
-            val patchResult = applyPatch(patch, appliedPatches)
+        val appliedPatches = LinkedHashMap<String, AppliedPatch>() // first is name
 
-            val result = if (patchResult.isSuccess()) {
-                Result.success(patchResult.success()!!)
-            } else {
-                Result.failure(patchResult.error()!!)
+        try {
+            for (patch in data.patches) {
+                val patchResult = applyPatch(patch, appliedPatches)
+
+                val result = if (patchResult.isSuccess()) {
+                    Result.success(patchResult.success()!!)
+                } else {
+                    Result.failure(patchResult.error()!!)
+                }
+
+                yield(patch.patchName to result)
+                if (stopOnError && patchResult.isError()) break
             }
+        } finally {
+            // close all closeable patches in order
+            for ((patch, _) in appliedPatches.values.reversed()) {
+                if (patch !is Closeable) continue
 
-            yield(patch.patchName to result)
-            if (stopOnError && patchResult.isError()) break
+                patch.close()
+            }
         }
     }
 }
 
+/**
+ * A result of applying a [Patch].
+ *
+ * @param patchInstance The instance of the [Patch] that was applied.
+ * @param success The result of the [Patch].
+ */
+internal data class AppliedPatch(val patchInstance: Patch<Data>, val success: Boolean)
+
 private fun BuildOptions.setBuildOptions(options: PatcherOptions) {
     this.aaptPath = options.aaptPath
     this.useAapt2 = true

src/main/kotlin/app/revanced/patcher/data/impl/ResourceData.kt

@@ -19,31 +19,66 @@ class ResourceData(private val resourceCacheDirectory: File) : Data, Iterable<Fi
     override fun iterator() = resourceCacheDirectory.walkTopDown().iterator()
 
     inner class XmlFileHolder {
-        operator fun get(inputStream: InputStream, outputStream: OutputStream) =
-            DomFileEditor(inputStream, lazyOf(outputStream))
+        operator fun get(inputStream: InputStream) =
+            DomFileEditor(inputStream)
+
+        operator fun get(path: String): DomFileEditor {
+            return DomFileEditor(this@ResourceData[path])
+        }
 
-        operator fun get(path: String) = DomFileEditor(this@ResourceData[path])
     }
 }
 
+/**
+ * DomFileEditor is a wrapper for a file that can be edited as a dom document.
+ *
+ * @param inputStream the input stream to read the xml file from.
+ * @param outputStream the output stream to write the xml file to. If null, the file will not be written.
+ */
 class DomFileEditor internal constructor(
     private val inputStream: InputStream,
-    private val outputStream: Lazy<OutputStream>,
+    private val outputStream: Lazy<OutputStream>? = null,
 ) : Closeable {
+    // path to the xml file to unlock the resource when closing the editor
+    private var filePath: String? = null
+
+    /**
+     * The document of the xml file
+     */
     val file: Document = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(inputStream)
         .also(Document::normalize)
 
     // lazily open an output stream
     // this is required because when constructing a DomFileEditor the output stream is created along with the input stream, which is not allowed
     // the workaround is to lazily create the output stream. This way it would be used after the input stream is closed, which happens in the constructor
-    constructor(file: File) : this(file.inputStream(), lazy { file.outputStream() })
+    constructor(file: File) : this(file.inputStream(), lazy { file.outputStream() }) {
+        filePath = file.path
 
-    override fun close() {
-        val result = StreamResult(outputStream.value)
-        TransformerFactory.newInstance().newTransformer().transform(DOMSource(file), result)
-
-        inputStream.close()
-        outputStream.value.close()
+        // prevent sharing mutability of the same file between multiple instances of DomFileEditor
+        if (locks.contains(filePath))
+            throw IllegalStateException("Can not create a DomFileEditor for that file because it is already locked by another instance of DomFileEditor.")
+        locks.add(filePath!!)
     }
 
+    override fun close() {
+        inputStream.close()
+
+        // if the output stream is not null, do not close it
+        outputStream?.let {
+            val result = StreamResult(it.value)
+            TransformerFactory.newInstance().newTransformer().transform(DOMSource(file), result)
+
+            it.value.close()
+        }
+
+        // remove the lock, if it exists
+        filePath?.let {
+            locks.remove(it)
+        }
+    }
+
+    private companion object {
+        // list of locked file paths
+        val locks = mutableListOf<String>()
+    }
 }

src/main/kotlin/app/revanced/patcher/patch/Patch.kt

@@ -3,16 +3,23 @@ package app.revanced.patcher.patch
 import app.revanced.patcher.data.Data
 import app.revanced.patcher.patch.impl.BytecodePatch
 import app.revanced.patcher.patch.impl.ResourcePatch
-
+import java.io.Closeable
 
 /**
  * A ReVanced patch.
+ *
  * Can either be a [ResourcePatch] or a [BytecodePatch].
+ * If it implements [Closeable], it will be closed after all patches have been executed.
+ * Closing will be done in reverse execution order.
  */
 abstract class Patch<out T : Data> {
-
     /**
      * The main function of the [Patch] which the patcher will call.
      */
     abstract fun execute(data: @UnsafeVariance T): PatchResult
+
+    /**
+     * A list of [PatchOption]s.
+     */
+    open val options = PatchOptions()
 }

src/main/kotlin/app/revanced/patcher/patch/PatchOption.kt

@@ -0,0 +1,155 @@
+package app.revanced.patcher.patch
+
+@Suppress("CanBeParameter", "MemberVisibilityCanBePrivate")
+class NoSuchOptionException(val option: String) : Exception("No such option: $option")
+
+/**
+ * A registry for an array of [PatchOption]s.
+ * @param options An array of [PatchOption]s.
+ */
+@Suppress("MemberVisibilityCanBePrivate")
+class PatchOptions(vararg val options: PatchOption<*>) : Iterable<PatchOption<*>> {
+    private val register = buildMap {
+        for (option in options) {
+            if (containsKey(option.key)) {
+                throw IllegalStateException("Multiple options found with the same key")
+            }
+            put(option.key, option)
+        }
+    }
+
+    /**
+     * Get a [PatchOption] by its key.
+     * @param key The key of the [PatchOption].
+     */
+    operator fun get(key: String) = register[key] ?: throw NoSuchOptionException(key)
+
+    /**
+     * Set the value of a [PatchOption].
+     * @param key The key of the [PatchOption].
+     * @param value The value you want it to be.
+     * Please note that using the wrong value type results in a runtime error.
+     */
+    inline operator fun <reified T> set(key: String, value: T) {
+        @Suppress("UNCHECKED_CAST") val opt = get(key) as? PatchOption<T>
+        if (opt == null || opt.value !is T) throw IllegalArgumentException(
+            "The type of the option value is not the same as the type value provided"
+        )
+        opt.value = value
+    }
+
+    override fun iterator() = options.iterator()
+}
+
+/**
+ * A [Patch] option.
+ * @param key Unique identifier of the option. Example: _`settings.microg.enabled`_
+ * @param default The default value of the option.
+ * @param title A human-readable title of the option. Example: _MicroG Settings_
+ * @param description A human-readable description of the option. Example: _Settings integration for MicroG._
+ * @param required Whether the option is required.
+ */
+@Suppress("MemberVisibilityCanBePrivate")
+sealed class PatchOption<T>(
+    val key: String,
+    default: T?,
+    val title: String,
+    val description: String,
+    val required: Boolean,
+    val validator: (T?) -> Boolean
+) {
+    var value: T? = default
+        set(value) {
+            if (!validator(value)) {
+                throw IllegalArgumentException("Illegal value: $value")
+            }
+            field = value
+        }
+
+    /**
+     * A [PatchOption] representing a [String].
+     * @see PatchOption
+     */
+    class StringOption(
+        key: String,
+        default: String?,
+        title: String,
+        description: String,
+        required: Boolean = false,
+        validator: (String?) -> Boolean = { true }
+    ) : PatchOption<String>(
+        key, default, title, description, required, validator
+    )
+
+    /**
+     * A [PatchOption] representing a [Boolean].
+     * @see PatchOption
+     */
+    class BooleanOption(
+        key: String,
+        default: Boolean?,
+        title: String,
+        description: String,
+        required: Boolean = false,
+        validator: (Boolean?) -> Boolean = { true }
+    ) : PatchOption<Boolean>(
+        key, default, title, description, required, validator
+    )
+
+    /**
+     * A [PatchOption] with a list of allowed options.
+     * @param options A list of allowed options for the [ListOption].
+     * @see PatchOption
+     */
+    sealed class ListOption<E>(
+        key: String,
+        default: E?,
+        val options: Iterable<E>,
+        title: String,
+        description: String,
+        required: Boolean = false,
+        validator: (E?) -> Boolean = { true }
+    ) : PatchOption<E>(
+        key, default, title, description, required, {
+            (it?.let { it in options } ?: true) && validator(it)
+        }
+    ) {
+        init {
+            if (default !in options) {
+                throw IllegalStateException("Default option must be an allowed options")
+            }
+        }
+    }
+
+    /**
+     * A [ListOption] of type [String].
+     * @see ListOption
+     */
+    class StringListOption(
+        key: String,
+        default: String?,
+        options: Iterable<String>,
+        title: String,
+        description: String,
+        required: Boolean = false,
+        validator: (String?) -> Boolean = { true }
+    ) : ListOption<String>(
+        key, default, options, title, description, required, validator
+    )
+
+    /**
+     * A [ListOption] of type [Int].
+     * @see ListOption
+     */
+    class IntListOption(
+        key: String,
+        default: Int?,
+        options: Iterable<Int>,
+        title: String,
+        description: String,
+        required: Boolean = false,
+        validator: (Int?) -> Boolean = { true }
+    ) : ListOption<Int>(
+        key, default, options, title, description, required, validator
+    )
+}

src/main/kotlin/app/revanced/patcher/patch/annotations/PatchAnnotation.kt

@@ -39,4 +39,9 @@ annotation class DependsOn(
     val type: DependencyType = DependencyType.HARD
 )
 
-enum class DependencyType { HARD, SOFT }
+enum class DependencyType {
+    /**
+     * Enforces that the dependency is applied, even if it was not selected.
+     */
+    HARD
+}

src/test/kotlin/app/revanced/patcher/patch/PatchOptionsTest.kt

@@ -0,0 +1,59 @@
+package app.revanced.patcher.patch
+
+import app.revanced.patcher.usage.bytecode.ExampleBytecodePatch
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+
+internal class PatchOptionsTest {
+    private val options = ExampleBytecodePatch().options
+
+    @Test
+    fun `should not throw an exception`() {
+        for (option in options) {
+            when (option) {
+                is PatchOption.StringOption -> {
+                    option.value = "Hello World"
+                }
+                is PatchOption.BooleanOption -> {
+                    option.value = false
+                }
+                is PatchOption.StringListOption -> {
+                    option.value = option.options.first()
+                    for (choice in option.options) {
+                        println(choice)
+                    }
+                }
+                is PatchOption.IntListOption -> {
+                    option.value = option.options.first()
+                    for (choice in option.options) {
+                        println(choice)
+                    }
+                }
+            }
+        }
+        println(options["key1"].value)
+        options["key1"] = "Hello, world!"
+        println(options["key1"].value)
+    }
+
+    @Test
+    fun `should fail because the option does not exist`() {
+        assertThrows<NoSuchOptionException> {
+            options["this option does not exist"] = 123
+        }
+    }
+
+    @Test
+    fun `should fail because of invalid value type`() {
+        assertThrows<IllegalArgumentException> {
+            options["key1"] = 123
+        }
+    }
+
+    @Test
+    fun `should fail because of an illegal value`() {
+        assertThrows<IllegalArgumentException> {
+            options["key3"] = "this value is not an allowed option"
+        }
+    }
+}

src/test/kotlin/app/revanced/patcher/usage/bytecode/ExampleBytecodePatch.kt

@@ -7,6 +7,8 @@ import app.revanced.patcher.data.impl.BytecodeData
 import app.revanced.patcher.extensions.addInstructions
 import app.revanced.patcher.extensions.or
 import app.revanced.patcher.extensions.replaceInstruction
+import app.revanced.patcher.patch.PatchOption
+import app.revanced.patcher.patch.PatchOptions
 import app.revanced.patcher.patch.PatchResult
 import app.revanced.patcher.patch.PatchResultSuccess
 import app.revanced.patcher.patch.annotations.DependencyType
@@ -37,7 +39,7 @@ import org.jf.dexlib2.util.Preconditions
 @Description("Example demonstration of a bytecode patch.")
 @ExampleResourceCompatibility
 @Version("0.0.1")
-@DependsOn(ExampleBytecodePatch::class, DependencyType.SOFT)
+@DependsOn(ExampleBytecodePatch::class, DependencyType.HARD)
 class ExampleBytecodePatch : BytecodePatch(listOf(ExampleFingerprint)) {
     // This function will be executed by the patcher.
     // You can treat it as a constructor
@@ -162,4 +164,19 @@ class ExampleBytecodePatch : BytecodePatch(listOf(ExampleFingerprint)) {
             )
         )
     }
+
+    override val options = PatchOptions(
+        PatchOption.StringOption(
+            "key1", "default", "title", "description", true
+        ),
+        PatchOption.BooleanOption(
+            "key2", true, "title", "description" // required defaults to false
+        ),
+        PatchOption.StringListOption(
+            "key3", "TEST", listOf("TEST", "TEST1", "TEST2"), "title", "description"
+        ),
+        PatchOption.IntListOption(
+            "key4", 1, listOf(1, 2, 3), "title", "description"
+        ),
+    )
 }