From 596ccb1d9d4be7180083fa0bf425947dbc498d3c Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 9 Mar 2024 12:49:23 -0800
Subject: [PATCH] Add Context.registerClosable

---
 CHANGELOG.md                                  |   1 +
 clikt/api/clikt.api                           |   7 +
 .../com/github/ajalt/clikt/core/Context.kt    |  63 ++++++
 .../com/github/ajalt/clikt/parsers/Parser.kt  | 202 +++++++++++-------
 .../github/ajalt/clikt/core/ContextTest.kt    |  76 +++++++
 .../com/github/ajalt/clikt/core/ContextJvm.kt |  25 +++
 .../clikt/parameters/types/inputStream.kt     |  10 +-
 .../clikt/parameters/types/outputStream.kt    |  10 +-
 .../github/ajalt/clikt/core/ContextJvmTest.kt |  22 ++
 docs/advanced.md                              |  44 +++-
 docs/commands.md                              |   5 +
 11 files changed, 377 insertions(+), 88 deletions(-)
 create mode 100644 clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/core/ContextJvm.kt
 create mode 100644 clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/core/ContextJvmTest.kt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 247097087..6914d43f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 ### Added
 - Added `limit` parameter to `option().counted()` to limit the number of times the option can be used. You can either clamp the value to the limit, or throw an error if the limit is exceeded. ([#483](https://github.com/ajalt/clikt/issues/483))
+- Added `Context.registerClosable` and `Context.callOnClose` to allow you to register cleanup actions that will be called when the command exits. ([#395](https://github.com/ajalt/clikt/issues/395))
 
 ## 4.2.2
 ### Changed
diff --git a/clikt/api/clikt.api b/clikt/api/clikt.api
index bd2a7cece..1337c9728 100644
--- a/clikt/api/clikt.api
+++ b/clikt/api/clikt.api
@@ -161,6 +161,8 @@ public final class com/github/ajalt/clikt/core/Context {
 	public static final field Companion Lcom/github/ajalt/clikt/core/Context$Companion;
 	public synthetic fun <init> (Lcom/github/ajalt/clikt/core/Context;Lcom/github/ajalt/clikt/core/CliktCommand;ZZLjava/lang/String;ZLjava/util/Set;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function2;Lcom/github/ajalt/mordant/terminal/Terminal;Lkotlin/jvm/functions/Function1;ZLcom/github/ajalt/clikt/sources/ValueSource;Lkotlin/jvm/functions/Function2;Lcom/github/ajalt/clikt/output/Localization;Lkotlin/jvm/functions/Function1;Ljava/lang/Object;Ljava/util/List;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun ancestors ()Lkotlin/sequences/Sequence;
+	public final fun callOnClose (Lkotlin/jvm/functions/Function0;)V
+	public final fun close ()V
 	public final fun commandNameWithParents ()Ljava/util/List;
 	public final fun fail (Ljava/lang/String;)Ljava/lang/Void;
 	public static synthetic fun fail$default (Lcom/github/ajalt/clikt/core/Context;Ljava/lang/String;ILjava/lang/Object;)Ljava/lang/Void;
@@ -239,8 +241,13 @@ public abstract interface class com/github/ajalt/clikt/core/ContextCliktError {
 	public abstract fun setContext (Lcom/github/ajalt/clikt/core/Context;)V
 }
 
+public final class com/github/ajalt/clikt/core/ContextJvmKt {
+	public static final fun registerJvmCloseable (Lcom/github/ajalt/clikt/core/Context;Ljava/lang/AutoCloseable;)Ljava/lang/AutoCloseable;
+}
+
 public final class com/github/ajalt/clikt/core/ContextKt {
 	public static final fun getTheme (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/mordant/rendering/Theme;
+	public static final fun registerCloseable (Lcom/github/ajalt/clikt/core/Context;Ljava/lang/AutoCloseable;)Ljava/lang/AutoCloseable;
 }
 
 public final class com/github/ajalt/clikt/core/FileNotFound : com/github/ajalt/clikt/core/UsageError {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt
index d6d4c0af2..f3f2d2971 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt
@@ -129,6 +129,8 @@ class Context private constructor(
     var errorEncountered: Boolean = false
         internal set
 
+    private val closeables = mutableListOf<() -> Unit>()
+
     /** Find the closest object of type [T] */
     inline fun <reified T : Any> findObject(): T? {
         return selfAndAncestors().mapNotNull { it.obj as? T }.firstOrNull()
@@ -163,6 +165,43 @@ class Context private constructor(
     /** Throw a [UsageError] with the given message */
     fun fail(message: String = ""): Nothing = throw UsageError(message)
 
+    /**
+     * Register a callback to be called when this command and all its subcommands have finished.
+     *
+     * This is useful for resources that need to be shared across multiple commands.
+     *
+     * If your resource implements [AutoCloseable], you should use [registerCloseable] instead.
+     *
+     * ### Example
+     *
+     * ```
+     * currentContext.callOnClose { myResource.close() }
+     * ```
+     */
+    fun callOnClose(closeable: () -> Unit) {
+        closeables.add(closeable)
+    }
+
+    /**
+     * Close all registered closeables in the reverse order they were registered.
+     *
+     * This is called automatically after a command and its subcommands have finished running.
+     */
+    fun close() {
+        var err: Throwable? = null
+        for (c in closeables.asReversed()) {
+            try {
+                c()
+            } catch (e: Throwable) {
+                if (err == null) err = e
+                else err.addSuppressed(e)
+            }
+        }
+        closeables.clear()
+        if (err != null) throw err
+    }
+
+    // TODO(5.0): these don't need to be member functions
     @PublishedApi
     internal fun ancestors() = generateSequence(parent) { it.parent }
 
@@ -342,6 +381,30 @@ class Context private constructor(
     }
 }
 
+/**
+ * Register an [AutoCloseable] to be closed when this command and all its subcommands have
+ * finished running.
+ *
+ * This is useful for resources that need to be shared across multiple commands. For resources
+ * that aren't shared, it's often simpler to use [use] directly.
+ *
+ * Registered closeables will be closed in the reverse order that they were registered.
+ *
+ * ### Example
+ *
+ * ```
+ * currentContext.obj = currentContext.registerCloseable(MyResource())
+ * ```
+ *
+ * @return the closeable that was registered
+ * @see Context.callOnClose
+ */
+@ExperimentalStdlibApi
+fun <T: AutoCloseable> Context.registerCloseable(closeable: T): T {
+    callOnClose { closeable.close() }
+    return closeable
+}
+
 /** Find the closest object of type [T], or throw a [NullPointerException] */
 @Suppress("UnusedReceiverParameter") // these extensions don't use their receiver, but we want to limit where they can be called
 inline fun <reified T : Any> CliktCommand.requireObject(): ReadOnlyProperty<CliktCommand, T> {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
index a73aa8891..8bd60c214 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
@@ -3,6 +3,7 @@ package com.github.ajalt.clikt.parsers
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.finalizeParameters
 import com.github.ajalt.clikt.parameters.arguments.Argument
+import com.github.ajalt.clikt.parameters.groups.ParameterGroup
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
@@ -99,15 +100,13 @@ internal object Parser {
             return context.tokenTransformer(context, token.take(2)) !in optionsByName
         }
 
-        fun addError(e: Err) {
-            errors += e
-            context.errorEncountered = true
-        }
-
         fun consumeParse(tokenIndex: Int, result: OptParseResult) {
             positionalArgs += result.unknown.map { tokenIndex to it }
             invocations += result.known
-            result.err?.let(::addError)
+            result.err?.let {
+                errors += it
+                context.errorEncountered = true
+            }
             i += result.consumed
         }
 
@@ -211,92 +210,143 @@ internal object Parser {
         }
 
 
-        // Finalize and validate everything as long as we aren't resuming a parse for multiple subcommands
+        // Finalize and validate everything as long as we aren't resuming a parse for multiple
+        // subcommands
         try {
-            if (canRun) {
-                // Finalize and validate eager options
-                invocationsByOption.forEach { (o, inv) ->
-                    if (o.eager) {
-                        o.finalize(context, inv)
-                        o.postValidate(context)
-                    }
+            try {
+                if (canRun) {
+                    i = finalizeAndRun(
+                        context,
+                        i,
+                        command,
+                        subcommand,
+                        invocationsByOption,
+                        positionalArgs,
+                        arguments,
+                        hasMultipleSubAncestor,
+                        tokens,
+                        subcommands,
+                        errors,
+                        ungroupedOptions,
+                        invocationsByOptionByGroup
+                    )
+                } else if (subcommand == null && positionalArgs.isNotEmpty()) {
+                    // If we're resuming a parse with multiple subcommands, there can't be any args
+                    // after the last subcommand is parsed
+                    throw excessArgsError(positionalArgs, positionalArgs.size, context)
                 }
+            } catch (e: UsageError) {
+                // Augment usage errors with the current context if they don't have one
+                e.context = context
+                throw e
+            }
 
-                // Parse arguments
-                val argsParseResult = parseArguments(i, positionalArgs, arguments)
-                argsParseResult.err?.let(::addError)
+            if (subcommand != null) {
+                val nextTokens = parse(tokens.drop(i), subcommand.currentContext, true)
+                if (command.allowMultipleSubcommands && nextTokens.isNotEmpty()) {
+                    parse(nextTokens, context, false)
+                }
+                return nextTokens
+            }
+        } finally {
+            context.close()
+        }
 
-                val excessResult = handleExcessArguments(
-                    argsParseResult.excessCount,
-                    hasMultipleSubAncestor,
-                    i,
-                    tokens,
-                    subcommands,
-                    positionalArgs,
-                    context
-                )
-                excessResult.second?.let(::addError)
+        return tokens.drop(i)
+    }
 
-                val usageErrors = errors
-                    .filter { it.includeInMulti }.ifEmpty { errors }
-                    .sortedBy { it.i }.mapTo(mutableListOf()) { it.e }
+    private fun finalizeAndRun(
+        context: Context,
+        i: Int,
+        command: CliktCommand,
+        subcommand: CliktCommand?,
+        invocationsByOption: Map<Option, List<Invocation>>,
+        positionalArgs: MutableList<Pair<Int, String>>,
+        arguments: MutableList<Argument>,
+        hasMultipleSubAncestor: Boolean,
+        tokens: List<String>,
+        subcommands: Map<String, CliktCommand>,
+        errors: MutableList<Err>,
+        ungroupedOptions: List<Option>,
+        invocationsByOptionByGroup: Map<ParameterGroup?, Map<Option, List<Invocation>>>,
+    ): Int {
+        // Finalize and validate eager options
+        var nextArgvI = i
+
+        invocationsByOption.forEach { (o, inv) ->
+            if (o.eager) {
+                o.finalize(context, inv)
+                o.postValidate(context)
+            }
+        }
 
-                i = excessResult.first
+        // Parse arguments
+        val argsParseResult = parseArguments(nextArgvI, positionalArgs, arguments)
+        argsParseResult.err?.let {
+            errors += it
+            context.errorEncountered = true
+        }
 
-                // Finalize arguments, groups, and options
-                gatherErrors(usageErrors, context) {
-                    finalizeParameters(
-                        context,
-                        ungroupedOptions,
-                        command._groups,
-                        invocationsByOptionByGroup,
-                        argsParseResult.args,
-                    )
-                }
+        val excessResult = handleExcessArguments(
+            argsParseResult.excessCount,
+            hasMultipleSubAncestor,
+            nextArgvI,
+            tokens,
+            subcommands,
+            positionalArgs,
+            context
+        )
+        excessResult.second?.let {
+            errors += it
+            context.errorEncountered = true
+        }
 
-                // We can't validate a param that didn't finalize successfully, and we don't keep
-                // track of which ones are finalized, so throw any errors now
-                MultiUsageError.buildOrNull(usageErrors)?.let { throw it }
+        val usageErrors = errors
+            .filter { it.includeInMulti }.ifEmpty { errors }
+            .sortedBy { it.i }.mapTo(mutableListOf()) { it.e }
 
-                // Now that all parameters have been finalized, we can validate everything
-                ungroupedOptions.forEach { gatherErrors(usageErrors, context) { it.postValidate(context) } }
-                command._groups.forEach { gatherErrors(usageErrors, context) { it.postValidate(context) } }
-                command._arguments.forEach { gatherErrors(usageErrors, context) { it.postValidate(context) } }
+        nextArgvI = excessResult.first
 
-                MultiUsageError.buildOrNull(usageErrors)?.let { throw it }
+        // Finalize arguments, groups, and options
+        gatherErrors(usageErrors, context) {
+            finalizeParameters(
+                context,
+                ungroupedOptions,
+                command._groups,
+                invocationsByOptionByGroup,
+                argsParseResult.args,
+            )
+        }
 
-                if (subcommand == null && subcommands.isNotEmpty() && !command.invokeWithoutSubcommand) {
-                    throw PrintHelpMessage(context, error = true)
-                }
+        // We can't validate a param that didn't finalize successfully, and we don't keep
+        // track of which ones are finalized, so throw any errors now
+        MultiUsageError.buildOrNull(usageErrors)?.let { throw it }
+
+        // Now that all parameters have been finalized, we can validate everything
+        ungroupedOptions.forEach { gatherErrors(usageErrors, context) { it.postValidate(context) } }
+        command._groups.forEach { gatherErrors(usageErrors, context) { it.postValidate(context) } }
+        command._arguments.forEach {
+            gatherErrors(
+                usageErrors,
+                context
+            ) { it.postValidate(context) }
+        }
 
-                command.currentContext.invokedSubcommand = subcommand
-                if (command.currentContext.printExtraMessages) {
-                    for (warning in command.messages) {
-                        command.terminal.warning(warning, stderr = true)
-                    }
-                }
+        MultiUsageError.buildOrNull(usageErrors)?.let { throw it }
 
-                command.run()
-            } else if (subcommand == null && positionalArgs.isNotEmpty()) {
-                // If we're resuming a parse with multiple subcommands, there can't be any args after the last
-                // subcommand is parsed
-                throw excessArgsError(positionalArgs, positionalArgs.size, context)
-            }
-        } catch (e: UsageError) {
-            // Augment usage errors with the current context if they don't have one
-            e.context = context
-            throw e
+        if (subcommand == null && subcommands.isNotEmpty() && !command.invokeWithoutSubcommand) {
+            throw PrintHelpMessage(context, error = true)
         }
 
-        if (subcommand != null) {
-            val nextTokens = parse(tokens.drop(i), subcommand.currentContext, true)
-            if (command.allowMultipleSubcommands && nextTokens.isNotEmpty()) {
-                parse(nextTokens, context, false)
+        command.currentContext.invokedSubcommand = subcommand
+        if (command.currentContext.printExtraMessages) {
+            for (warning in command.messages) {
+                command.terminal.warning(warning, stderr = true)
             }
-            return nextTokens
         }
 
-        return tokens.drop(i)
+        command.run()
+        return nextArgvI
     }
 
     /** Returns either the new argv index, or an error */
@@ -514,14 +564,14 @@ internal object Parser {
             1 -> context.localization.extraArgumentOne(actual)
             else -> context.localization.extraArgumentMany(actual, excess)
         }
-        return UsageError(message)
+        return UsageError(message).also { it.context = context }
     }
 }
 
 private inline fun gatherErrors(
     errors: MutableList<UsageError>,
     context: Context,
-    block: () -> Unit
+    block: () -> Unit,
 ) {
     try {
         block()
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/ContextTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/ContextTest.kt
index 717fd1c41..889cfa8a8 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/ContextTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/ContextTest.kt
@@ -12,6 +12,7 @@ import io.kotest.matchers.types.beInstanceOf
 import io.kotest.matchers.types.shouldBeSameInstanceAs
 import kotlin.js.JsName
 import kotlin.test.Test
+import kotlin.test.fail
 
 class ContextTest {
     class Foo
@@ -130,4 +131,79 @@ class ContextTest {
 
         c.currentContext.obj shouldBeSameInstanceAs foo
     }
+
+    @Test
+    @OptIn(ExperimentalStdlibApi::class)
+    @JsName("register_closeable_multiple_subcommands")
+    fun `register closeable multiple subcommands`() {
+        var parentCount = 0
+        var childCount = 0
+        var childSaw0 = 0
+        var childSaw1 = 0
+
+        class Parent : TestCommand(allowMultipleSubcommands = true) {
+            override fun run_() {
+                currentContext.callOnClose { parentCount++ }
+            }
+        }
+
+
+        class Child : TestCommand(count = 2) {
+            override fun run_() {
+                when (childCount) {
+                    0 -> childSaw0++
+                    1 -> childSaw1++
+                    else -> fail("too many calls")
+                }
+                parentCount shouldBe 0
+                val c = object : AutoCloseable {
+                    override fun close() {
+                        childCount++
+                    }
+                }
+                currentContext.registerCloseable(c) shouldBeSameInstanceAs c
+            }
+        }
+        Parent().subcommands(Child()).parse("child child")
+        parentCount shouldBe 1
+        childSaw0 shouldBe 1
+        childSaw1 shouldBe 1
+        childCount shouldBe 2
+    }
+
+    @Test
+    @JsName("register_closeable_throws")
+    fun `register closeable throws`() {
+        var count1 = 0
+        var count2 = 0
+        var count3 = 0
+
+        class E1 : Exception()
+        class E2 : Exception()
+        class E3 : Exception()
+
+        class C : TestCommand() {
+            override fun run_() {
+                currentContext.callOnClose {
+                    count1++
+                    throw E1()
+                }
+                currentContext.callOnClose {
+                    count2++
+                    throw E2()
+                }
+                currentContext.callOnClose {
+                    count3++
+                    throw E3()
+                }
+            }
+        }
+        shouldThrow<E3> {
+            C().parse("")
+        }
+
+        count1 shouldBe 1
+        count2 shouldBe 1
+        count3 shouldBe 1
+    }
 }
diff --git a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/core/ContextJvm.kt b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/core/ContextJvm.kt
new file mode 100644
index 000000000..d261b3545
--- /dev/null
+++ b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/core/ContextJvm.kt
@@ -0,0 +1,25 @@
+package com.github.ajalt.clikt.core
+
+/**
+ * Register an [AutoCloseable] to be closed when this command and all its subcommands have
+ * finished running.
+ *
+ * This is useful for resources that need to be shared across multiple commands. For resources
+ * that aren't shared, it's often simpler to use [use] directly.
+ *
+ * Registered closeables will be closed in the reverse order that they were registered.
+ *
+ * ### Example
+ *
+ * ```
+ * currentContext.obj = currentContext.registerCloseable(File("foo").bufferedReader())
+ * ```
+ *
+ * @return the closeable that was registered
+ * @see Context.callOnClose
+ * @see Context.registerCloseable
+ */
+fun <T: AutoCloseable> Context.registerJvmCloseable(closeable: T): T {
+    callOnClose { closeable.close() }
+    return closeable
+}
diff --git a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt
index eb5fd315c..5d6dff8d5 100644
--- a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt
+++ b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt
@@ -34,7 +34,7 @@ fun RawOption.inputStream(
  * Use `-` as the default value for an [inputStream] option.
  */
 fun NullableOption<InputStream, InputStream>.defaultStdin(): OptionWithValues<InputStream, InputStream, InputStream> {
-    return default(UnclosableInputStream(System.`in`), "-")
+    return default(UncloseableInputStream(System.`in`), "-")
 }
 
 // endregion
@@ -62,7 +62,7 @@ fun RawArgument.inputStream(
  * Use `-` as the default value for an [inputStream] argument.
  */
 fun ProcessedArgument<InputStream, InputStream>.defaultStdin(): ArgumentDelegate<InputStream> {
-    return default(UnclosableInputStream(System.`in`))
+    return default(UncloseableInputStream(System.`in`))
 }
 
 // endregion
@@ -73,7 +73,7 @@ fun ProcessedArgument<InputStream, InputStream>.defaultStdin(): ArgumentDelegate
  * [defaultStdin]).
  */
 val InputStream.isCliktParameterDefaultStdin: Boolean
-    get() = this is UnclosableInputStream
+    get() = this is UncloseableInputStream
 
 private fun convertToInputStream(
     s: String,
@@ -82,7 +82,7 @@ private fun convertToInputStream(
     fail: (String) -> Unit,
 ): InputStream {
     return if (s == "-") {
-        UnclosableInputStream(System.`in`)
+        UncloseableInputStream(System.`in`)
     } else {
         val path = convertToPath(
             path = s,
@@ -100,7 +100,7 @@ private fun convertToInputStream(
     }
 }
 
-private class UnclosableInputStream(private var delegate: InputStream?) : InputStream() {
+private class UncloseableInputStream(private var delegate: InputStream?) : InputStream() {
     private val stream get() = delegate ?: throw IOException("Stream closed")
     override fun available(): Int = stream.available()
     override fun read(): Int = stream.read()
diff --git a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt
index b5f32dcd7..577531243 100644
--- a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt
+++ b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt
@@ -46,7 +46,7 @@ fun RawOption.outputStream(
  * Use `-` as the default value for an [outputStream] option.
  */
 fun NullableOption<OutputStream, OutputStream>.defaultStdout(): OptionWithValues<OutputStream, OutputStream, OutputStream> {
-    return default(UnclosableOutputStream(System.out), "-")
+    return default(UncloseableOutputStream(System.out), "-")
 }
 
 // endregion
@@ -85,7 +85,7 @@ fun RawArgument.outputStream(
  * Use `-` as the default value for an [outputStream] argument.
  */
 fun ProcessedArgument<OutputStream, OutputStream>.defaultStdout(): ArgumentDelegate<OutputStream> {
-    return default(UnclosableOutputStream(System.out))
+    return default(UncloseableOutputStream(System.out))
 }
 
 // endregion
@@ -96,7 +96,7 @@ fun ProcessedArgument<OutputStream, OutputStream>.defaultStdout(): ArgumentDeleg
  * [defaultStdout]).
  */
 val OutputStream.isCliktParameterDefaultStdout: Boolean
-    get() = this is UnclosableOutputStream
+    get() = this is UncloseableOutputStream
 
 private fun convertToOutputStream(
     s: String,
@@ -107,7 +107,7 @@ private fun convertToOutputStream(
     fail: (String) -> Unit,
 ): OutputStream {
     return if (s == "-") {
-        UnclosableOutputStream(System.out)
+        UncloseableOutputStream(System.out)
     } else {
         val path = convertToPath(
             s,
@@ -126,7 +126,7 @@ private fun convertToOutputStream(
     }
 }
 
-private class UnclosableOutputStream(private var delegate: OutputStream?) : OutputStream() {
+private class UncloseableOutputStream(private var delegate: OutputStream?) : OutputStream() {
     private val stream get() = delegate ?: throw IOException("Stream closed")
 
     override fun write(b: Int) = stream.write(b)
diff --git a/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/core/ContextJvmTest.kt b/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/core/ContextJvmTest.kt
new file mode 100644
index 000000000..f6db3ef16
--- /dev/null
+++ b/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/core/ContextJvmTest.kt
@@ -0,0 +1,22 @@
+package com.github.ajalt.clikt.core
+
+import com.github.ajalt.clikt.testing.TestCommand
+import com.github.ajalt.clikt.testing.parse
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeSameInstanceAs
+import kotlin.test.Test
+
+class ContextJvmTest {
+    @Test
+    fun registerJvmCloseable() {
+        var closed = 0
+        class C: TestCommand() {
+            override fun run_() {
+                val c = AutoCloseable { closed += 1 }
+                currentContext.registerJvmCloseable(c) shouldBeSameInstanceAs c
+            }
+        }
+        C().parse("")
+        closed shouldBe 1
+    }
+}
diff --git a/docs/advanced.md b/docs/advanced.md
index d1e98fac2..1af506fa8 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -350,6 +350,43 @@ If you want to use a value starting with `@` as an argument without expanding it
 - If a `\` occurs at the end of a line, the next line is trimmed of leading whitespace and the two
   lines are concatenated.
 
+## Managing Shared Resources
+
+You might need to open a resource like a file or a network connection in one command, and use it in
+its subcommands.
+
+The typical way to manage a resource is with the `use` function:
+
+```kotiln
+class MyCommand : CliktCommand() {
+    private val file by option().file().required()
+
+    override fun run() {
+        file.bufferedReader().use { reader ->
+            // use the reader
+        }
+    }
+}
+```
+
+But if you need to share the resource with subcommands, the `use` function will exit and close the
+resource before the subcommand is called. Instead, use the context's [registerCloseable] function
+(for `kotlin.AutoCloseable`) or [registerJvmCloseable] function (for `java.lang.AutoCloseable`) to:
+
+```kotlin
+class MyCommand : CliktCommand() {
+    private val file by option().file().required()
+
+    override fun run() {
+        currentContext.obj = currentContext.registerJvmCloseable(file.bufferedReader())
+    }
+}
+```
+
+You can register as many closeables as you need, and they will all be closed when the command and
+its subcommands have finished running. If you need to manage a resource that isn't `AutoClosable`,
+you can use [callOnClose].
+
 ## Custom exit status codes
 
 Clikt will normally exit your program with a status code of 0 for a normal execution, or 1 if
@@ -391,7 +428,10 @@ TerminalInterface](#replacing-stdin-and-stdout), or you can call [parse][parse]
 * [editText][editText] and [editFile][editFile] are not supported.
 * [file][file] and [path][path] parameter types are not supported.
 
+[ProgramResult]:       api/clikt/com.github.ajalt.clikt.core/-program-result/index.html
+[TermUI]:              api/clikt/com.github.ajalt.clikt.output/-term-ui/index.html
 [aliases]:             api/clikt/com.github.ajalt.clikt.core/-clikt-command/aliases.html
+[callOnClose]:         api/clikt/com.github.ajalt.clikt.core/-context/call-on-close.html
 [context-obj]:         commands.md#nested-handling-and-contexts
 [customizing-context]: commands.md#customizing-contexts
 [dash-dash]:           arguments.md#option-like-arguments-using-
@@ -403,8 +443,8 @@ TerminalInterface](#replacing-stdin-and-stdout), or you can call [parse][parse]
 [main]:                api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
 [parse]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/parse.html
 [path]:                api/clikt/com.github.ajalt.clikt.parameters.types/path.html
-[ProgramResult]:       api/clikt/com.github.ajalt.clikt.core/-program-result/index.html
 [prompt]:              api/clikt/com.github.ajalt.clikt.parameters.options/prompt.html
+[registerCloseable]:   api/clikt/com.github.ajalt.clikt.core/register-closeable.html
+[registerJvmCloseable]:api/clikt/com.github.ajalt.clikt.core/register-jvm-closeable.html
 [test]:                api/clikt/com.github.ajalt.clikt.testing/test.html
-[TermUI]:              api/clikt/com.github.ajalt.clikt.output/-term-ui/index.html
 [tokenTransformer]:    api/clikt/com.github.ajalt.clikt.core/-context/token-transformer.html
diff --git a/docs/commands.md b/docs/commands.md
index 321327acd..fe9afcd58 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -230,6 +230,11 @@ the property, you should use [`currentContext.findOrSetObject`][Context.findOrSe
     }
     ```
 
+!!! tip
+
+    If you need to share resources that need to be cleaned up, you can use
+    [`currentContext.registerCloseable`](advanced.md#managing-shared-resources)
+
 ## Running Parent Command Without Children
 
 Normally, if a command has children, [`run`][run] is not called unless a child