From 88d4dcb99fb4343aeb091880860ce594d0b487ca Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 30 Mar 2024 11:18:56 -0700
Subject: [PATCH 01/43] Add NoSuchArgument

---
 CHANGELOG.md                                  |  2 ++
 .../com/github/ajalt/clikt/core/exceptions.kt | 33 ++++++++++++++++---
 .../com/github/ajalt/clikt/parsers/Parser.kt  | 14 +++-----
 .../ajalt/clikt/parameters/ArgumentTest.kt    |  6 ++--
 .../ajalt/clikt/parameters/OptionTest.kt      |  2 +-
 5 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a8197eae..8cc0d9e7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,8 @@
 # Changelog
 
 ## Unreleased
+### Added
+- Added `NoSuchArgument` exception that is thrown when too many arguments were given on the command line. Previously, a less specific `UsageError` was thrown instead.
 ## 4.4.0
 ### Added
 - Publish `linuxArm64` and `wasmJs` targets.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/exceptions.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/exceptions.kt
index 73e6b1e9..18d93a91 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/exceptions.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/exceptions.kt
@@ -147,9 +147,16 @@ class MultiUsageError(
         fun buildOrNull(errors: List<UsageError>): UsageError? = when (errors.size) {
             0 -> null
             1 -> errors[0]
-            else -> MultiUsageError(errors.flatMap {
-                (it as? MultiUsageError)?.errors ?: listOf(it)
-            })
+            else -> {
+                val flatErrors = errors.flatMap { (it as? MultiUsageError)?.errors ?: listOf(it) }
+                var encounteredUnknownOpt = false
+                // Don't report argument errors after unknown options since they might be the values
+                // for that option
+                MultiUsageError(flatErrors.filter {
+                    if (it is NoSuchOption) encounteredUnknownOpt = true
+                    !encounteredUnknownOpt || it !is NoSuchArgument
+                })
+            }
         }
     }
 
@@ -230,7 +237,6 @@ class NoSuchSubcommand(
     }
 }
 
-
 /** An option was provided that does not exist. */
 class NoSuchOption(
     paramName: String,
@@ -244,6 +250,25 @@ class NoSuchOption(
     }
 }
 
+/**
+ * One or more arguments were provided that do not exist.
+ */
+class NoSuchArgument(
+    private val excessArguments: List<String>,
+) : UsageError(null) {
+    init {
+        require(excessArguments.isNotEmpty()) { "must provide at least one excess argument" }
+    }
+
+    override fun formatMessage(localization: Localization, formatter: ParameterFormatter): String {
+        val actual = excessArguments.joinToString(" ", limit = 3, prefix = "(", postfix = ")")
+        return when (excessArguments.size) {
+            1 -> localization.extraArgumentOne(actual)
+            else -> localization.extraArgumentMany(actual, excessArguments.size)
+        }
+    }
+}
+
 
 /** An option was supplied but the number of values supplied to the option was incorrect. */
 class IncorrectOptionValueCount(
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 8bd60c21..050faa97 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
@@ -8,7 +8,7 @@ import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
 /** [i] is the argv index of the token that caused the error */
-private data class Err(val e: UsageError, val i: Int, val includeInMulti: Boolean = true)
+private data class Err(val e: UsageError, val i: Int)
 
 private data class ArgsParseResult(
     val excessCount: Int,
@@ -302,7 +302,6 @@ internal object Parser {
         }
 
         val usageErrors = errors
-            .filter { it.includeInMulti }.ifEmpty { errors }
             .sortedBy { it.i }.mapTo(mutableListOf()) { it.e }
 
         nextArgvI = excessResult.first
@@ -369,7 +368,7 @@ internal object Parser {
                     )
                 }
 
-                else -> -1 to Err(excessArgsError(positionalArgs, excess, context), i, false)
+                else -> -1 to Err(excessArgsError(positionalArgs, excess, context), i)
             }
         }
         return i to null
@@ -558,13 +557,8 @@ internal object Parser {
         excess: Int,
         context: Context,
     ): UsageError {
-        val actual = positionalArgs.takeLast(excess)
-            .joinToString(" ", limit = 3, prefix = "(", postfix = ")") { it.second }
-        val message = when (excess) {
-            1 -> context.localization.extraArgumentOne(actual)
-            else -> context.localization.extraArgumentMany(actual, excess)
-        }
-        return UsageError(message).also { it.context = context }
+        val actual = positionalArgs.takeLast(excess).map { it.second }
+        return NoSuchArgument(actual).also { it.context = context }
     }
 }
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
index 6dda101c..8af41685 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
@@ -161,9 +161,9 @@ class ArgumentTest {
         }
         shouldThrow<IncorrectArgumentValueCount> { C().parse("foo") }
             .formattedMessage shouldBe "argument X requires 2 values"
-        shouldThrow<UsageError> { C().parse("foo bar baz") }
+        shouldThrow<NoSuchArgument> { C().parse("foo bar baz") }
             .formattedMessage shouldBe "got unexpected extra argument (baz)"
-        shouldThrow<UsageError> { C().parse("foo bar baz qux") }
+        shouldThrow<NoSuchArgument> { C().parse("foo bar baz qux") }
             .formattedMessage shouldBe "got unexpected extra arguments (baz qux)"
     }
 
@@ -176,7 +176,7 @@ class ArgumentTest {
 
         shouldThrow<IncorrectArgumentValueCount> { C().parse("foo bar") }
             .formattedMessage shouldBe "argument X requires 3 values"
-        shouldThrow<UsageError> { C().parse("foo bar baz qux") }
+        shouldThrow<NoSuchArgument> { C().parse("foo bar baz qux") }
             .formattedMessage shouldBe "got unexpected extra argument (qux)"
 
     }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
index 51d6a584..27d3514f 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
@@ -233,7 +233,7 @@ class OptionTest {
         }
         shouldThrow<IncorrectOptionValueCount> { C().parse("-x") }.formattedMessage shouldBe
                 "option -x requires 2 values"
-        shouldThrow<UsageError> { C().parse("--yy foo bar baz") }.formattedMessage shouldBe
+        shouldThrow<NoSuchArgument> { C().parse("--yy foo bar baz") }.formattedMessage shouldBe
                 "got unexpected extra argument (baz)"
     }
 

From 50b8cf1d95d39d74762764c72d4202806db32cf0 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 30 Mar 2024 16:05:18 -0700
Subject: [PATCH 02/43] Separate parsing from execution

---
 .../github/ajalt/clikt/core/CliktCommand.kt   |   7 +-
 .../com/github/ajalt/clikt/core/Context.kt    |  36 +-
 .../clikt/execution/CommandLineRunner.kt      |  41 ++
 .../ajalt/clikt/internal/Finalization.kt      |  23 +-
 .../github/ajalt/clikt/parsers/Invocation.kt  |  20 +
 .../com/github/ajalt/clikt/parsers/Parser.kt  |  19 +-
 .../com/github/ajalt/clikt/parsers/atfile.kt  |   9 +-
 .../ajalt/clikt/tmp/CommandLineParser.kt      |  39 ++
 .../com/github/ajalt/clikt/tmp/NewParser.kt   | 446 ++++++++++++++++++
 .../github/ajalt/clikt/testing/TestCommand.kt |   2 +-
 10 files changed, 594 insertions(+), 48 deletions(-)
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 6bbcdd2b..7761f44d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -52,7 +52,7 @@ abstract class CliktCommand(
      */
     val printHelpOnEmptyArgs: Boolean = false,
     /**
-     * Extra information about this option to pass to the help formatter.
+     * Extra information about this command to pass to the help formatter.
      */
     val helpTags: Map<String, String> = emptyMap(),
     /**
@@ -132,6 +132,11 @@ abstract class CliktCommand(
 
     private fun registeredOptionNames() = _options.flatMapTo(mutableSetOf()) { it.names }
 
+    fun resetContext(parent: Context?): Context {
+        TODO("implement this, doc that each run get a fresh context now")
+//        _context?.close()
+//        return createContext(...)
+    }
     private fun createContext(
         argv: List<String>,
         parent: Context?,
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 f3f2d297..7af5a08c 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
@@ -357,24 +357,24 @@ class Context private constructor(
                 val formatter: ((Context) -> HelpFormatter) =
                     helpFormatter ?: { MordantHelpFormatter(it) }
                 return Context(
-                    parent,
-                    command,
-                    interspersed,
-                    allowGroupedShortOptions,
-                    autoEnvvarPrefix,
-                    printExtraMessages,
-                    helpOptionNames.toSet(),
-                    formatter,
-                    tokenTransformer,
-                    terminal,
-                    argumentFileReader,
-                    readEnvvarBeforeValueSource,
-                    valueSource,
-                    correctionSuggestor,
-                    localization,
-                    envvarReader,
-                    obj,
-                    argv
+                    parent = parent,
+                    command = command,
+                    allowInterspersedArgs = interspersed,
+                    allowGroupedShortOptions = allowGroupedShortOptions,
+                    autoEnvvarPrefix = autoEnvvarPrefix,
+                    printExtraMessages = printExtraMessages,
+                    helpOptionNames = helpOptionNames.toSet(),
+                    helpFormatter = formatter,
+                    tokenTransformer = tokenTransformer,
+                    terminal = terminal,
+                    argumentFileReader = argumentFileReader,
+                    readEnvvarBeforeValueSource = readEnvvarBeforeValueSource,
+                    valueSource = valueSource,
+                    correctionSuggestor = correctionSuggestor,
+                    localization = localization,
+                    readEnvvar = envvarReader,
+                    obj = obj,
+                    originalArgv = argv
                 )
             }
         }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
new file mode 100644
index 00000000..2674e9ab
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
@@ -0,0 +1,41 @@
+package com.github.ajalt.clikt.execution
+//
+//import com.github.ajalt.clikt.core.BaseCliktCommand
+//import com.github.ajalt.clikt.core.CliktError
+//import com.github.ajalt.clikt.mpp.exitProcessMpp
+//import com.github.ajalt.clikt.tmp.CommandLineParser
+//
+//fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
+//    val result = CommandLineParser.parse(this, argv.asList())
+//    for (invocation in result.invocations) {
+//        CommandLineParser.finalize(invocation)
+//        invocation.command.runner()
+//    }
+//}
+//
+//fun BaseCliktCommand<() -> Unit>.main(argv: Array<String>) {
+//    try {
+//        parse(argv)
+//    } catch (e: CliktError) {
+//        echoFormattedHelp(e)
+//        exitProcessMpp(e.statusCode)
+//    }
+//}
+//
+//suspend fun BaseCliktCommand<suspend () -> Unit>.parse(argv: Array<String>) {
+//    val result = CommandLineParser.parse(this, argv.asList())
+//    for (invocation in result.invocations) {
+//        CommandLineParser.finalize(invocation)
+//        invocation.command.runner()
+//    }
+//}
+//
+//fun <T> BaseCliktCommand<(T) -> T>.parse(initialValue: T, argv: Array<String>): T {
+//    val result = CommandLineParser.parse(this, argv.asList())
+//    var value = initialValue
+//    for (invocation in result.invocations) {
+//        CommandLineParser.finalize(invocation)
+//        value = invocation.command.runner(value)
+//    }
+//    return value
+//}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index e165aa9e..dc6b6f87 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -1,12 +1,10 @@
 package com.github.ajalt.clikt.internal
 
-import com.github.ajalt.clikt.core.Abort
-import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.core.MultiUsageError
-import com.github.ajalt.clikt.core.UsageError
+import com.github.ajalt.clikt.core.*
 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.parsers.ArgumentInvocation
 import com.github.ajalt.clikt.parsers.Invocation
 
 internal fun finalizeOptions(
@@ -15,7 +13,7 @@ internal fun finalizeOptions(
     invocationsByOption: Map<Option, List<Invocation>>,
 ) {
     finalizeParameters(
-        context, options, emptyList(), mapOf(null to invocationsByOption), emptyList()
+        context, options, emptyList(), invocationsByOption, emptyList()
     )
 }
 
@@ -28,23 +26,26 @@ internal fun finalizeParameters(
     context: Context,
     options: List<Option>,
     groups: List<ParameterGroup>,
-    invocationsByOptionByGroup: Map<ParameterGroup?, Map<Option, List<Invocation>>>,
-    argsAndTokens: List<Pair<Argument, List<String>>>,
+    optionInvocations: Map<Option, List<Invocation>>,
+    argumentInvocations: List<ArgumentInvocation>,
 ) {
+    val allGroups = optionInvocations.entries
+        .groupBy({ it.key.group }, { it.key to it.value })
+        .mapValuesTo(mutableMapOf()) { it.value.toMap() }
+
     // Add uninvoked params last so that e.g. we can skip prompting if there's an error in an
     // invoked option
-    val allGroups = invocationsByOptionByGroup.toMutableMap()
     for (group in groups) {
         if (group !in allGroups) allGroups[group] = emptyMap()
     }
 
-    val allOptions = (invocationsByOptionByGroup[null] ?: emptyMap()).toMutableMap()
+    val allOptions = (allGroups[null] ?: emptyMap()).toMutableMap()
     for (opt in options) {
         if (opt !in allOptions) allOptions[opt] = emptyList()
     }
 
     val allParams: List<Param> =
-        argsAndTokens.map { Arg(it.first, it.second) } +
+        argumentInvocations.map { Arg(it.argument, it.values) } +
                 allOptions.map { Opt(it.key, it.value) } +
                 allGroups.mapNotNull { it.key?.let { k -> Group(k, it.value) } }
 
@@ -78,3 +79,5 @@ internal fun finalizeParameters(
 
     MultiUsageError.buildOrNull(errors)?.let { throw it }
 }
+
+private val Option.group: ParameterGroup? get() = (this as? GroupableOption)?.parameterGroup
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 277771c8..4e0c8029 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -1,5 +1,8 @@
 package com.github.ajalt.clikt.parsers
 
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.CliktError
+import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 
 /**
@@ -11,3 +14,20 @@ import com.github.ajalt.clikt.parameters.options.Option
  *   will have a size in the range of [Option.nvalues].
  */
 data class Invocation(val name: String, val values: List<String>)
+
+// TODO: docs
+data class ArgumentInvocation(val argument: Argument, val values: List<String>)
+
+// TODO: swap to BaseCliktCommand<T>
+data class CommandInvocation(
+    val command: CliktCommand,
+    val optionInvocations: Map<Option, List<Invocation>>,
+    val argumentInvocations: List<ArgumentInvocation>,
+)
+
+class CommandLineParseResult(
+    val invocations: List<CommandInvocation>,
+    val originalArgv: List<String>,
+    val expandedArgv: List<String>,
+    val errors: List<CliktError>,
+)
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 050faa97..3cd0494d 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,7 +3,6 @@ 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
 
@@ -197,14 +196,6 @@ internal object Parser {
 
         // Group options for finalization
         val invocationsByOption = invocations.groupBy({ it.opt }, { it.inv })
-        val invocationsByGroup = invocations.groupBy {
-            (it.opt as? GroupableOption)?.parameterGroup
-        }
-        val invocationsByOptionByGroup = invocationsByGroup
-            .mapValues { (_, invocations) ->
-                invocations.groupBy({ it.opt }, { it.inv })
-                    .filterKeys { !it.eager }
-            }
         val ungroupedOptions = command._options.filter {
             !it.eager && (it as? GroupableOption)?.parameterGroup == null
         }
@@ -227,8 +218,7 @@ internal object Parser {
                         tokens,
                         subcommands,
                         errors,
-                        ungroupedOptions,
-                        invocationsByOptionByGroup
+                        ungroupedOptions
                     )
                 } else if (subcommand == null && positionalArgs.isNotEmpty()) {
                     // If we're resuming a parse with multiple subcommands, there can't be any args
@@ -268,7 +258,6 @@ internal object Parser {
         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
@@ -312,8 +301,8 @@ internal object Parser {
                 context,
                 ungroupedOptions,
                 command._groups,
-                invocationsByOptionByGroup,
-                argsParseResult.args,
+                invocationsByOption,
+                argsParseResult.args.map { (a, v) -> ArgumentInvocation(a, v) },
             )
         }
 
@@ -549,7 +538,7 @@ internal object Parser {
     }
 
     private fun loadArgFile(filename: String, context: Context): List<String> {
-        return shlex(filename, context.argumentFileReader!!(filename), context)
+        return shlex(filename, context.argumentFileReader!!(filename), context.localization)
     }
 
     private fun excessArgsError(
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/atfile.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/atfile.kt
index 0de203bf..5b8468cc 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/atfile.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/atfile.kt
@@ -1,11 +1,14 @@
 package com.github.ajalt.clikt.parsers
 
-import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.InvalidFileFormat
+import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
-internal fun shlex(filename: String, text: String, context: Context?): List<String> {
-    val localization = context?.localization ?: defaultLocalization
+internal fun shlex(
+    filename: String,
+    text: String,
+    localization: Localization = defaultLocalization,
+): List<String> {
     val toks = mutableListOf<String>()
     var inQuote: Char? = null
     val sb = StringBuilder()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
new file mode 100644
index 00000000..f4fe4a82
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
@@ -0,0 +1,39 @@
+package com.github.ajalt.clikt.tmp
+
+import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.internal.finalizeParameters
+import com.github.ajalt.clikt.output.Localization
+import com.github.ajalt.clikt.output.defaultLocalization
+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.parsers.CommandInvocation
+import com.github.ajalt.clikt.parsers.CommandLineParseResult
+import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.shlex
+
+// TODO: move this back to parsers package
+
+object CommandLineParser {
+    fun tokenize(
+        commandLine: String,
+        localization: Localization = defaultLocalization,
+    ): List<String> {
+        return shlex("TODO", commandLine, localization)// TODO
+    }
+
+    // does not throw
+    fun parse(command: CliktCommand, originalArgv: List<String>): CommandLineParseResult {
+        return parseArgv(command, originalArgv)
+    }
+
+    fun finalize(invocation: CommandInvocation) {
+        finalizeParameters(
+            invocation.command.currentContext,
+            invocation.command.registeredOptions(),
+            invocation.command.registeredParameterGroups(),
+            invocation.optionInvocations,
+            invocation.argumentInvocations,
+        )
+    }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
new file mode 100644
index 00000000..f0cb4128
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
@@ -0,0 +1,446 @@
+package com.github.ajalt.clikt.tmp
+
+import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.parameters.arguments.Argument
+import com.github.ajalt.clikt.parameters.options.Option
+import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
+import com.github.ajalt.clikt.parsers.*
+
+internal fun parseArgv(command: CliktCommand, originalArgv: List<String>): CommandLineParseResult {
+    val results = mutableListOf<CommandInvocation>()
+    var expandedArgv = originalArgv
+    val errors = mutableListOf<CliktError>()
+    var i = 0
+    do {
+        val parent = results.lastOrNull()?.command?.currentContext
+        val commandResult = parseCommand(command, parent, expandedArgv, i)
+        check(commandResult.i in expandedArgv.indices) {
+            "Internal error: index $i out of bounds ${expandedArgv.indices}"
+        }
+
+        i = commandResult.i
+        errors += commandResult.errors
+        expandedArgv = commandResult.expandedArgv
+        if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
+
+        val argResult = parseArguments(commandResult.argumentTokens, command._arguments)
+        val excessArgResult = handleExcessArgs(argResult, command, i, expandedArgv, commandResult)
+        i = excessArgResult.first
+        errors += excessArgResult.second
+        errors.forEach { e ->
+            (e as? UsageError)?.let { it.context = it.context ?: command.currentContext }
+        }
+        results += CommandInvocation(command, commandResult.optInvocations, argResult.invocations)
+    } while (commandResult.subcommand != null)
+    val lastInvocation = results.lastOrNull()
+    if (lastInvocation != null && i != expandedArgv.lastIndex) {
+        errors += NoSuchArgument(expandedArgv.drop(i + 1)).also {
+            it.context = command.currentContext
+        }
+    }
+    return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
+}
+
+private fun parseCommand(
+    command: CliktCommand,
+    parentContext: Context?,
+    argv: List<String>,
+    startingIndex: Int,
+): CommandParseResult {
+    var tokens = argv
+    val context = command.resetContext(parentContext)
+    val aliases = command.aliases()
+    val subcommands = command._subcommands.associateBy { it.commandName }
+    val subcommandNames = subcommands.keys
+    val optionsByName = mutableMapOf<String, Option>()
+    val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
+    val prefixes = mutableSetOf<String>()
+    val longNames = mutableSetOf<String>()
+    val argumentTokens = mutableListOf<String>()
+    var subcommand: CliktCommand? = null
+    var canParseOptions = true
+    var canExpandAtFiles = context.expandArgumentFiles
+    val optInvocations = mutableListOf<OptInvocation>()
+    val errors = mutableListOf<CliktError>()
+    var i = startingIndex
+    var minAliasI = i
+
+    fun makeResult(): CommandParseResult {
+        val opts = optInvocations.groupBy({ it.opt }, { it.inv })
+        return CommandParseResult(subcommand, i, errors, tokens, opts, argumentTokens)
+    }
+
+    for (option in command._options) {
+        require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
+            "options must have at least one name"
+        }
+
+        require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
+            "acceptsUnattachedValue must be true if the option accepts more than one value"
+        }
+
+        for (name in option.names + option.secondaryNames) {
+            optionsByName[name] = option
+            if (name.length > 2) longNames += name
+            prefixes += splitOptionPrefix(name).first
+        }
+    }
+    prefixes.remove("")
+
+    if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
+        errors += PrintHelpMessage(context, error = true)
+        return makeResult()
+    }
+
+    fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
+        if ("=" !in token) return false
+        if (prefix.isEmpty()) return false
+        if (prefix.length > 1) return true
+        if (context.tokenTransformer(
+                context,
+                token.substringBefore("=")
+            ) in longNames
+        ) return true
+        return context.tokenTransformer(context, token.take(2)) !in optionsByName
+    }
+
+    fun consumeOptionParse(result: OptParseResult) {
+        argumentTokens += result.unknown
+        optInvocations += result.known
+        result.err?.let {
+            errors += it
+            context.errorEncountered = true
+        }
+        i += result.consumed
+    }
+
+    fun insertTokens(newTokens: List<String>) {
+        tokens = buildList(tokens.size + newTokens.size) {
+            addAll(tokens.take(i))
+            addAll(newTokens)
+            addAll(tokens.drop(i + 1))
+        }
+        minAliasI = i + newTokens.size
+    }
+
+    loop@ while (i <= tokens.lastIndex) {
+        val tok = tokens[i]
+        val normTok = context.tokenTransformer(context, tok)
+        val prefix = splitOptionPrefix(tok).first
+        when {
+            canExpandAtFiles
+                    && tok.startsWith("@")
+                    && normTok !in optionsByName -> {
+                if (tok.startsWith("@@")) {
+                    argumentTokens += tok.drop(1)
+                    i += 1
+                } else {
+                    insertTokens(loadArgFile(normTok.drop(1), context))
+                }
+            }
+
+            canParseOptions
+                    && tok == "--" -> {
+                i += 1
+                canParseOptions = false
+                canExpandAtFiles = false
+            }
+
+            canParseOptions && (
+                    prefix.length > 1 && prefix in prefixes
+                            || normTok in longNames
+                            || isLongOptionWithEquals(prefix, tok)
+                            || !context.allowGroupedShortOptions
+                    ) -> {
+                consumeOptionParse(
+                    parseLongOpt(
+                        command.treatUnknownOptionsAsArgs,
+                        context,
+                        tokens,
+                        tok,
+                        i,
+                        optionsByName,
+                        subcommandNames
+                    )
+                )
+            }
+
+            canParseOptions
+                    && tok.length >= 2
+                    && prefix.isNotEmpty()
+                    && prefix in prefixes -> {
+                consumeOptionParse(
+                    parseShortOpt(
+                        command.treatUnknownOptionsAsArgs,
+                        context,
+                        tokens,
+                        tok,
+                        i,
+                        optionsByName,
+                        numberOption,
+                        subcommandNames
+                    )
+                )
+            }
+
+            i >= minAliasI && tok in aliases -> {
+                insertTokens(aliases.getValue(tok))
+            }
+
+            normTok in subcommands -> {
+                subcommand = subcommands.getValue(normTok)
+                i += 1
+                break@loop
+            }
+
+            else -> {
+                if (!context.allowInterspersedArgs) canParseOptions = false
+                argumentTokens += tok // arguments aren't transformed
+                i += 1
+            }
+        }
+    }
+
+    return makeResult()
+}
+
+/** Returns the new argv index and any errors */
+private fun handleExcessArgs(
+    argResult: ArgsParseResult,
+    command: CliktCommand,
+    i: Int,
+    expandedArgv: List<String>,
+    commandResult: CommandParseResult,
+): Pair<Int, List<CliktError>> {
+    if (argResult.excessCount <= 0) return i to emptyList()
+    val hasMultipleSubAncestor = command.currentContext.ancestors().any {
+        it.command.allowMultipleSubcommands
+    }
+    if (hasMultipleSubAncestor) {
+        return expandedArgv.size - argResult.excessCount to emptyList()
+    } else {
+        val subcommandNames = command._subcommands.map { it.commandName }
+        val error = when {
+            argResult.excessCount == 1 && subcommandNames.isNotEmpty() -> {
+                val actual = commandResult.argumentTokens.last()
+                val possibilities = command.currentContext.correctionSuggestor(
+                    actual, subcommandNames
+                )
+                NoSuchSubcommand(actual, possibilities)
+            }
+
+            else -> {
+                NoSuchArgument(commandResult.argumentTokens.takeLast(argResult.excessCount))
+            }
+        }
+        return i to listOf(error)
+    }
+}
+
+
+private fun parseLongOpt(
+    ignoreUnknown: Boolean,
+    context: Context,
+    tokens: List<String>,
+    tok: String,
+    index: Int,
+    optionsByName: Map<String, Option>,
+    subcommandNames: Set<String>,
+): OptParseResult {
+    val equalsIndex = tok.indexOf('=')
+    var (name, attachedValue) = if (equalsIndex >= 0) {
+        tok.substring(0, equalsIndex) to tok.substring(equalsIndex + 1)
+    } else {
+        tok to null
+    }
+    name = context.tokenTransformer(context, name)
+    val option = optionsByName[name] ?: if (ignoreUnknown) {
+        return OptParseResult(1, listOf(tok))
+    } else {
+        val possibilities = context.correctionSuggestor(
+            name,
+            optionsByName.filterNot { it.value.hidden }.keys.toList()
+        )
+        return OptParseResult(1, err = NoSuchOption(name, possibilities))
+    }
+
+    return parseOptValues(
+        option,
+        name,
+        ignoreUnknown,
+        tokens,
+        index,
+        attachedValue,
+        optionsByName,
+        subcommandNames
+    )
+}
+
+private fun parseOptValues(
+    option: Option,
+    name: String,
+    ignoreUnknown: Boolean,
+    tokens: List<String>,
+    index: Int,
+    attachedValue: String?,
+    optionsByName: Map<String, Option>,
+    subcommandNames: Set<String>,
+): OptParseResult {
+    val values = mutableListOf<String>()
+    if (attachedValue != null) {
+        values += attachedValue
+    } else if (!option.acceptsUnattachedValue) {
+        return OptParseResult(1, option, name, emptyList())
+    }
+
+    for (i in (index + 1)..tokens.lastIndex) {
+        val tok = tokens[i]
+        if (values.size >= option.nvalues.last) break
+        if (values.size >= option.nvalues.first && (tok == "--"
+                    || tok in optionsByName
+                    || tok in subcommandNames
+                    || !ignoreUnknown && splitOptionPrefix(tok).first.isNotEmpty())
+        ) {
+            break
+        }
+
+        values += tok
+    }
+
+    val consumed = values.size + if (attachedValue == null) 1 else 0
+    if (values.size !in option.nvalues) {
+        return OptParseResult(
+            consumed,
+            err = IncorrectOptionValueCount(option, name)
+        )
+    }
+
+    return OptParseResult(consumed, option, name, values)
+}
+
+private fun parseShortOpt(
+    ignoreUnknown: Boolean,
+    context: Context,
+    tokens: List<String>,
+    tok: String,
+    index: Int,
+    optionsByName: Map<String, Option>,
+    numberOption: Option?,
+    subcommandNames: Set<String>,
+): OptParseResult {
+    val prefix = tok[0].toString()
+
+    if (numberOption != null && tok.drop(1).all { it.isDigit() }) {
+        return OptParseResult(1, numberOption, "", listOf(tok.drop(1)))
+    }
+
+    val invocations = mutableListOf<OptInvocation>()
+
+    for ((i, opt) in tok.withIndex()) {
+        if (i == 0) continue // skip the dash
+
+        val name = context.tokenTransformer(context, prefix + opt)
+        val option = optionsByName[name] ?: if (ignoreUnknown) {
+            return OptParseResult(1, unknown = listOf(tok))
+        } else {
+            val possibilities = when {
+                prefix == "-" && "-$tok" in optionsByName -> listOf("-$tok")
+                else -> emptyList()
+            }
+            return OptParseResult(1, err = NoSuchOption(name, possibilities))
+        }
+        if (option.nvalues.last > 0) {
+            val value = if (i < tok.lastIndex) tok.drop(i + 1) else null
+            val result = parseOptValues(
+                option,
+                name,
+                ignoreUnknown,
+                tokens,
+                index,
+                value,
+                optionsByName,
+                subcommandNames
+            )
+            return result.copy(known = invocations + result.known)
+        } else {
+            invocations += OptInvocation(option, name, emptyList())
+        }
+    }
+    return OptParseResult(1, invocations)
+}
+
+
+private fun parseArguments(
+    argumentTokens: List<String>,
+    arguments: List<Argument>,
+): ArgsParseResult {
+    val invocations = mutableListOf<ArgumentInvocation>()
+    // The number of fixed size arguments that occur after an unlimited size argument. This
+    // includes optional args, so it might be bigger than the number of provided values.
+    val endSize = arguments.asReversed()
+        .takeWhile { it.nvalues > 0 }
+        .sumOf { it.nvalues }
+
+    var i = 0
+    for (argument in arguments) {
+        val remaining = argumentTokens.size - i
+        val consumed = when {
+            argument.nvalues <= 0 -> maxOf(if (argument.required) 1 else 0, remaining - endSize)
+            argument.nvalues > 0 && !argument.required && remaining == 0 -> 0
+            else -> argument.nvalues
+        }
+
+        if (consumed > remaining) {
+            val e = when (remaining) {
+                0 -> MissingArgument(argument)
+                else -> IncorrectArgumentValueCount(argument)
+            }
+            return ArgsParseResult(0, invocations, e)
+        }
+        val values = argumentTokens.subList(i, i + consumed)
+        invocations += ArgumentInvocation(argument, values)
+        i += consumed
+    }
+
+    val excess = argumentTokens.size - i
+    return ArgsParseResult(excess, invocations, null)
+}
+
+private fun loadArgFile(filename: String, context: Context): List<String> {
+    return shlex(filename, context.argumentFileReader!!(filename), context.localization)
+}
+
+private data class CommandParseResult(
+    val subcommand: CliktCommand?,
+    val i: Int,
+    val errors: List<CliktError>,
+    val expandedArgv: List<String>,
+    val optInvocations: Map<Option, List<Invocation>>,
+    val argumentTokens: List<String>,
+)
+
+private data class ArgsParseResult(
+    val excessCount: Int,
+    val invocations: List<ArgumentInvocation>,
+    val err: CliktError?,
+)
+
+private data class OptInvocation(val opt: Option, val name: String, val values: List<String>) {
+    val inv get() = Invocation(name, values)
+}
+
+private data class OptParseResult(
+    val consumed: Int,
+    val unknown: List<String> = emptyList(),
+    val known: List<OptInvocation> = emptyList(),
+    val err: CliktError? = null,
+) {
+    constructor(consumed: Int, invocations: List<OptInvocation>) : this(
+        consumed,
+        emptyList(),
+        invocations
+    )
+
+    constructor(consumed: Int, opt: Option, name: String, values: List<String>)
+            : this(consumed, emptyList(), listOf(OptInvocation(opt, name, values)))
+}
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index b2aed4b1..0d766412 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -67,7 +67,7 @@ open class TestCommand(
 }
 
 fun <T : TestCommand> T.parse(argv: String): T {
-    parse(shlex("test", argv, null))
+    parse(shlex("test", argv))
     TestCommand.assertCalled(this)
     return this
 }

From c53d570593be48b17a3bcf193864873c28375683 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 30 Mar 2024 16:12:32 -0700
Subject: [PATCH 03/43] Remove deprecated functions from CliktCommand

---
 .../github/ajalt/clikt/core/CliktCommand.kt   | 98 +------------------
 1 file changed, 4 insertions(+), 94 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 7761f44d..ec91ca2d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -30,12 +30,12 @@ abstract class CliktCommand(
      * The help for this command. The first line is used in the usage string, and the entire string
      * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
      */
-    help: String = "",
+    private val help: String = "",
     /**
      * Text to display at the end of the full help output. It is automatically re-wrapped to the
      * terminal width.
      */
-    epilog: String = "",
+    private val epilog: String = "",
     /**
      * The name of the program to use in the help output. If not given, it is inferred from the
      * class name.
@@ -84,9 +84,6 @@ abstract class CliktCommand(
      */
     val commandName: String = name ?: inferCommandName()
 
-    @Deprecated("Use commandHelp method instead")
-    open val commandHelp: String = help
-
     /**
      * The help text for this command.
      *
@@ -104,13 +101,9 @@ abstract class CliktCommand(
      * ```
      */
     open fun commandHelp(context: Context): String {
-        @Suppress("DEPRECATION")
-        return commandHelp
+        return help
     }
 
-    @Deprecated("Use commandHelpEpilog method instead")
-    open val commandHelpEpilog: String = epilog
-
     /**
      * Help text to display at the end of the help output, after any parameters.
      *
@@ -118,8 +111,7 @@ abstract class CliktCommand(
      * method.
      */
     open fun commandHelpEpilog(context: Context): String {
-        @Suppress("DEPRECATION")
-        return commandHelpEpilog
+        return epilog
     }
 
     internal var _subcommands: List<CliktCommand> = emptyList()
@@ -369,88 +361,6 @@ abstract class CliktCommand(
         }
     }
 
-    /**
-     * A deprecated alias for `terminal.prompt`.
-     */
-    @Deprecated(
-        "Use terminal.prompt instead",
-        ReplaceWith(
-            "terminal.prompt(text, default, showDefault, showChoices, hideInput, choices, promptSuffix, invalidChoiceMessage)",
-            "com.github.ajalt.clikt.core.terminal"
-        )
-    )
-    fun prompt(
-        text: String,
-        default: String? = null,
-        showDefault: Boolean = true,
-        showChoices: Boolean = true,
-        hideInput: Boolean = false,
-        choices: Collection<String> = emptyList(),
-        promptSuffix: String = ": ",
-        invalidChoiceMessage: String = "Invalid value, choose from ",
-    ): String? = currentContext.terminal.prompt(
-        text,
-        default,
-        showDefault,
-        showChoices,
-        hideInput,
-        choices,
-        promptSuffix,
-        invalidChoiceMessage
-    )
-
-    /**
-     * A deprecated alias for `terminal.prompt`.
-     */
-    @Deprecated(
-        "Use terminal.prompt instead",
-        ReplaceWith(
-            "terminal.prompt(text, default, showDefault, showChoices, hideInput, choices, promptSuffix, invalidChoiceMessage, convert)",
-            "com.github.ajalt.clikt.core.terminal"
-        )
-    )
-    fun <T> prompt(
-        text: String,
-        default: T? = null,
-        showDefault: Boolean = true,
-        showChoices: Boolean = true,
-        hideInput: Boolean = false,
-        choices: Collection<T> = emptyList(),
-        promptSuffix: String = ": ",
-        invalidChoiceMessage: String = "Invalid value, choose from ",
-        convert: (String) -> ConversionResult<T>,
-    ): T? = currentContext.terminal.prompt(
-        text,
-        default,
-        showDefault,
-        showChoices,
-        hideInput,
-        choices,
-        promptSuffix,
-        invalidChoiceMessage,
-        convert
-    )
-
-    @Deprecated(
-        "Use YesNoPrompt instead",
-        ReplaceWith(
-            "YesNoPrompt(text, terminal, default, uppercaseDefault, showChoices, choiceStrings, promptSuffix, invalidChoiceMessage).ask()",
-            "com.github.ajalt.clikt.core.terminal",
-            "com.github.ajalt.mordant.terminal.YesNoPrompt"
-        )
-    )
-    fun confirm(
-        text: String,
-        default: Boolean? = null,
-        uppercaseDefault: Boolean = true,
-        showChoices: Boolean = true,
-        choiceStrings: List<String> = listOf("y", "n"),
-        promptSuffix: String = ": ",
-        invalidChoiceMessage: String = "Invalid value, choose from ",
-    ): Boolean? {
-        return YesNoPrompt(text, terminal, default, uppercaseDefault, showChoices, choiceStrings, promptSuffix, invalidChoiceMessage).ask()
-    }
-
     /**
      * Parse the command line and throw an exception if parsing fails.
      *

From 821fe0410ce51683f4051bcb3e9b84cd84a68eb3 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 30 Mar 2024 16:34:24 -0700
Subject: [PATCH 04/43] Add BaseCliktCommand

---
 .../github/ajalt/clikt/core/CliktCommand.kt   | 81 ++++++++++++-------
 .../com/github/ajalt/clikt/core/Context.kt    | 38 +++++----
 .../clikt/execution/CommandLineRunner.kt      | 64 +++++++--------
 .../github/ajalt/clikt/parsers/Invocation.kt  | 11 ++-
 .../ajalt/clikt/tmp/CommandLineParser.kt      | 15 ++--
 .../com/github/ajalt/clikt/tmp/NewParser.kt   | 27 ++++---
 6 files changed, 130 insertions(+), 106 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index ec91ca2d..bd0790a3 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -4,28 +4,20 @@ import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.mpp.exitProcessMpp
 import com.github.ajalt.clikt.output.HelpFormatter.ParameterHelp
 import com.github.ajalt.clikt.parameters.arguments.Argument
-import com.github.ajalt.clikt.parameters.arguments.ProcessedArgument
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.groups.OptionGroup
 import com.github.ajalt.clikt.parameters.groups.ParameterGroup
 import com.github.ajalt.clikt.parameters.options.*
 import com.github.ajalt.clikt.parsers.Parser
-import com.github.ajalt.mordant.terminal.ConversionResult
 import com.github.ajalt.mordant.terminal.Terminal
-import com.github.ajalt.mordant.terminal.YesNoPrompt
 
+// TODO: docs
 /**
- * The [CliktCommand] is the core of command line interfaces in Clikt.
- *
- * Command line interfaces created by creating a subclass of [CliktCommand] with properties defined with
- * [option] and [argument]. You can then parse `argv` by calling [main], which will take care of printing
- * errors and help to the user. If you want to handle output yourself, you can use [parse] instead.
- *
- * Once the command line has been parsed and all the parameters are populated, [run] is called.
+ * A base class for commands that want to define a custom type for their `run` function.
  */
 @Suppress("PropertyName")
 @ParameterHolderDsl
-abstract class CliktCommand(
+abstract class BaseCliktCommand<RunnerT : Function<*>>(
     /**
      * The help for this command. The first line is used in the usage string, and the entire string
      * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
@@ -77,6 +69,13 @@ abstract class CliktCommand(
      */
     private val hidden: Boolean = false,
 ) : ParameterHolder {
+    /**
+     * The function to run when this command is invoked.
+     *
+     * For [CliktCommand], this just calls `run`.
+     */
+    abstract val runner: RunnerT
+
     /**
      * The name of this command, used in help output.
      *
@@ -114,7 +113,7 @@ abstract class CliktCommand(
         return epilog
     }
 
-    internal var _subcommands: List<CliktCommand> = emptyList()
+    internal var _subcommands: List<BaseCliktCommand<RunnerT>> = emptyList()
     internal val _options: MutableList<Option> = mutableListOf()
     internal val _arguments: MutableList<Argument> = mutableListOf()
     internal val _groups: MutableList<ParameterGroup> = mutableListOf()
@@ -125,14 +124,34 @@ abstract class CliktCommand(
     private fun registeredOptionNames() = _options.flatMapTo(mutableSetOf()) { it.names }
 
     fun resetContext(parent: Context?): Context {
-        TODO("implement this, doc that each run get a fresh context now")
-//        _context?.close()
-//        return createContext(...)
+        //TODO ("doc that each run get a fresh context now")
+        _context?.close()
+        // TODO either pass argv or remove it from ctx
+        _context = Context.build(this, parent, emptyList(), _contextConfig)
+
+        if (allowMultipleSubcommands) {
+            require(currentContext.ancestors().none { it.command.allowMultipleSubcommands }) {
+                "Commands with allowMultipleSubcommands=true cannot be nested in " +
+                        "commands that also have allowMultipleSubcommands=true"
+            }
+        }
+
+        if (currentContext.helpOptionNames.isNotEmpty()) {
+            val names = currentContext.helpOptionNames - registeredOptionNames()
+            if (names.isNotEmpty()) {
+                eagerOption(names, currentContext.localization.helpOptionMessage()) {
+                    throw PrintHelpMessage(context)
+                }
+            }
+        }
+        // TODO  check(command !in a) { "Command ${command.commandName} already registered" }
+        return _context!!
     }
+
     private fun createContext(
         argv: List<String>,
         parent: Context?,
-        ancestors: List<CliktCommand>,
+        ancestors: List<BaseCliktCommand<RunnerT>>,
     ): Context {
         _context = Context.build(this, parent, argv, _contextConfig)
 
@@ -180,7 +199,7 @@ abstract class CliktCommand(
     }
 
     private fun getCommandNameWithParents(): String {
-        if (_context == null) createContext(emptyList(), null, emptyList())
+        if (_context == null) resetContext(null)
         return currentContext.commandNameWithParents().joinToString(" ")
     }
 
@@ -303,8 +322,7 @@ abstract class CliktCommand(
             return error.message
         }
 
-        val ctx = (error as? ContextCliktError)?.context
-            ?: _context ?: createContext(emptyList(), null, emptyList())
+        val ctx = (error as? ContextCliktError)?.context ?: _context ?: resetContext(null)
         val cmd = ctx.command
         val programName = cmd.getCommandNameWithParents()
         return ctx.helpFormatter(ctx).formatHelp(
@@ -367,7 +385,6 @@ abstract class CliktCommand(
      * You should use [main] instead unless you want to handle output yourself.
      */
     fun parse(argv: List<String>, parentContext: Context? = null) {
-        createContext(argv, parentContext, emptyList())
         generateCompletion()
         Parser.parse(argv, this.currentContext)
     }
@@ -407,14 +424,14 @@ abstract class CliktCommand(
     abstract fun run()
 
     override fun toString() = buildString {
-        append("<${this@CliktCommand.classSimpleName()} name=$commandName")
+        append("<${this@BaseCliktCommand.classSimpleName()} name=$commandName")
 
         if (_options.isNotEmpty()) {
-            _options.joinTo(this, prefix=" options=[", postfix = "]")
+            _options.joinTo(this, prefix = " options=[", postfix = "]")
         }
 
         if (_arguments.isNotEmpty()) {
-            _arguments.joinTo(this, prefix=" arguments=[", postfix = "]")
+            _arguments.joinTo(this, prefix = " arguments=[", postfix = "]")
         }
 
         if (_subcommands.isNotEmpty()) {
@@ -425,13 +442,21 @@ abstract class CliktCommand(
     }
 }
 
+//abstract class CliktCommand : BaseCliktCommand<() -> Unit>() {
+//    override fun run() {
+//        throw PrintHelpMessage(currentContext)
+//    }
+//}
+
 /** Add the given commands as a subcommand of this command. */
-fun <T : CliktCommand> T.subcommands(commands: Iterable<CliktCommand>): T = apply {
+fun <RunnerT, CommandT> CommandT.subcommands(commands: Iterable<CommandT>): CommandT
+        where CommandT : BaseCliktCommand<RunnerT> = apply {
     _subcommands = _subcommands + commands
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <T : CliktCommand> T.subcommands(vararg commands: CliktCommand): T = apply {
+fun <RunnerT, CommandT> CommandT.subcommands(vararg commands: CommandT): CommandT
+        where CommandT : BaseCliktCommand<RunnerT> = apply {
     _subcommands = _subcommands + commands
 }
 
@@ -441,7 +466,7 @@ fun <T : CliktCommand> T.subcommands(vararg commands: CliktCommand): T = apply {
  * Context property values are normally inherited from the parent context, but you can override any of them
  * here.
  */
-fun <T : CliktCommand> T.context(block: Context.Builder.() -> Unit): T = apply {
+fun <T : BaseCliktCommand<*>> T.context(block: Context.Builder.() -> Unit): T = apply {
     // save the old config to allow multiple context calls
     val c = _contextConfig
     _contextConfig = {
@@ -452,7 +477,7 @@ fun <T : CliktCommand> T.context(block: Context.Builder.() -> Unit): T = apply {
 
 private fun Any.classSimpleName(): String = this::class.simpleName.orEmpty().split("$").last()
 
-private fun CliktCommand.inferCommandName(): String {
+private fun BaseCliktCommand<*>.inferCommandName(): String {
     val name = classSimpleName()
 
     val suffixes = setOf("Command", "Commands")
@@ -467,5 +492,5 @@ private fun CliktCommand.inferCommandName(): String {
 }
 
 /** A short for accessing the terminal from the [currentContext][CliktCommand.currentContext] */
-val CliktCommand.terminal: Terminal
+val BaseCliktCommand<*>.terminal: Terminal
     get() = currentContext.terminal
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 7af5a08c..05e725e8 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
@@ -27,7 +27,7 @@ class Context private constructor(
     /**
      * The command that this context associated with.
      */
-    val command: CliktCommand,
+    val command: BaseCliktCommand<*>,
     /**
      * If false, options and arguments cannot be mixed; the first time an argument is
      *   encountered, all remaining tokens are parsed as arguments.
@@ -116,7 +116,7 @@ class Context private constructor(
      * If this command has subcommands and one of them was invoked, this is the subcommand that will
      * be run next.
      */
-    var invokedSubcommand: CliktCommand? = null
+    var invokedSubcommand: BaseCliktCommand<*>? = null
         internal set
 
     /**
@@ -152,9 +152,7 @@ class Context private constructor(
 
     /** Return a list of command names, starting with the topmost command and ending with this Context's parent. */
     fun parentNames(): List<String> {
-        return ancestors()
-            .map { it.command.commandName }
-            .toList().asReversed()
+        return ancestors().map { it.command.commandName }.toList().asReversed()
     }
 
     /** Return a list of command names, starting with the topmost command and ending with this Context's command. */
@@ -215,7 +213,7 @@ class Context private constructor(
     val expandArgumentFiles: Boolean get() = argumentFileReader != null
 
 
-    class Builder(command: CliktCommand, val parent: Context? = null) {
+    class Builder(command: BaseCliktCommand<*>, val parent: Context? = null) {
         /**
          * If false, options and arguments cannot be mixed; the first time an argument is encountered, all
          * remaining tokens are parsed as arguments.
@@ -343,17 +341,17 @@ class Context private constructor(
 
     companion object {
         internal fun build(
-            command: CliktCommand,
+            command: BaseCliktCommand<*>,
             parent: Context?,
             argv: List<String>,
             block: Builder.() -> Unit,
         ): Context {
             with(Builder(command, parent)) {
                 block()
-                val interspersed = allowInterspersedArgs && !command.allowMultipleSubcommands &&
-                        parent?.let { p ->
-                            p.selfAndAncestors().any { it.command.allowMultipleSubcommands }
-                        } != true
+                val interspersed =
+                    allowInterspersedArgs && !command.allowMultipleSubcommands && parent?.let { p ->
+                        p.selfAndAncestors().any { it.command.allowMultipleSubcommands }
+                    } != true
                 val formatter: ((Context) -> HelpFormatter) =
                     helpFormatter ?: { MordantHelpFormatter(it) }
                 return Context(
@@ -400,20 +398,20 @@ class Context private constructor(
  * @see Context.callOnClose
  */
 @ExperimentalStdlibApi
-fun <T: AutoCloseable> Context.registerCloseable(closeable: T): T {
+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> {
+inline fun <reified T : Any> BaseCliktCommand<*>.requireObject(): ReadOnlyProperty<BaseCliktCommand<*>, T> {
     return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findObject()!! }
 }
 
 /** Find the closest object of type [T], or null */
 @Suppress("UnusedReceiverParameter")
-inline fun <reified T : Any> CliktCommand.findObject(): ReadOnlyProperty<CliktCommand, T?> {
+inline fun <reified T : Any> BaseCliktCommand<*>.findObject(): ReadOnlyProperty<BaseCliktCommand<*>, T?> {
     return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findObject() }
 }
 
@@ -426,16 +424,16 @@ inline fun <reified T : Any> CliktCommand.findObject(): ReadOnlyProperty<CliktCo
  * function instead.
  */
 @Suppress("UnusedReceiverParameter")
-inline fun <reified T : Any> CliktCommand.findOrSetObject(crossinline default: () -> T): ReadOnlyProperty<CliktCommand, T> {
+inline fun <reified T : Any> BaseCliktCommand<*>.findOrSetObject(
+    crossinline default: () -> T
+): ReadOnlyProperty<BaseCliktCommand<*>, T> {
     return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findOrSetObject(default) }
 }
 
 /** The current terminal's theme */
-val Context.theme : Theme get() = terminal.theme
+val Context.theme: Theme get() = terminal.theme
 
 private val DEFAULT_CORRECTION_SUGGESTOR: TypoSuggestor = { enteredValue, possibleValues ->
-    possibleValues.map { it to jaroWinklerSimilarity(enteredValue, it) }
-        .filter { it.second > 0.8 }
-        .sortedByDescending { it.second }
-        .map { it.first }
+    possibleValues.map { it to jaroWinklerSimilarity(enteredValue, it) }.filter { it.second > 0.8 }
+        .sortedByDescending { it.second }.map { it.first }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
index 2674e9ab..3509b59d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
@@ -1,18 +1,18 @@
 package com.github.ajalt.clikt.execution
-//
-//import com.github.ajalt.clikt.core.BaseCliktCommand
-//import com.github.ajalt.clikt.core.CliktError
-//import com.github.ajalt.clikt.mpp.exitProcessMpp
-//import com.github.ajalt.clikt.tmp.CommandLineParser
-//
-//fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
-//    val result = CommandLineParser.parse(this, argv.asList())
-//    for (invocation in result.invocations) {
-//        CommandLineParser.finalize(invocation)
-//        invocation.command.runner()
-//    }
-//}
-//
+
+import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.CliktError
+import com.github.ajalt.clikt.mpp.exitProcessMpp
+import com.github.ajalt.clikt.tmp.CommandLineParser
+
+fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
+    val result = CommandLineParser.parse(this, argv.asList())
+    for (invocation in result.invocations) {
+        CommandLineParser.finalize(invocation)
+        invocation.command.runner()
+    }
+}
+
 //fun BaseCliktCommand<() -> Unit>.main(argv: Array<String>) {
 //    try {
 //        parse(argv)
@@ -21,21 +21,21 @@ package com.github.ajalt.clikt.execution
 //        exitProcessMpp(e.statusCode)
 //    }
 //}
-//
-//suspend fun BaseCliktCommand<suspend () -> Unit>.parse(argv: Array<String>) {
-//    val result = CommandLineParser.parse(this, argv.asList())
-//    for (invocation in result.invocations) {
-//        CommandLineParser.finalize(invocation)
-//        invocation.command.runner()
-//    }
-//}
-//
-//fun <T> BaseCliktCommand<(T) -> T>.parse(initialValue: T, argv: Array<String>): T {
-//    val result = CommandLineParser.parse(this, argv.asList())
-//    var value = initialValue
-//    for (invocation in result.invocations) {
-//        CommandLineParser.finalize(invocation)
-//        value = invocation.command.runner(value)
-//    }
-//    return value
-//}
+
+suspend fun BaseCliktCommand<suspend () -> Unit>.parse(argv: Array<String>) {
+    val result = CommandLineParser.parse(this, argv.asList())
+    for (invocation in result.invocations) {
+        CommandLineParser.finalize(invocation)
+        invocation.command.runner()
+    }
+}
+
+fun <T> BaseCliktCommand<(T) -> T>.parse(initialValue: T, argv: Array<String>): T {
+    val result = CommandLineParser.parse(this, argv.asList())
+    var value = initialValue
+    for (invocation in result.invocations) {
+        CommandLineParser.finalize(invocation)
+        value = invocation.command.runner(value)
+    }
+    return value
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 4e0c8029..65ee7082 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -1,6 +1,6 @@
 package com.github.ajalt.clikt.parsers
 
-import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
@@ -18,15 +18,14 @@ data class Invocation(val name: String, val values: List<String>)
 // TODO: docs
 data class ArgumentInvocation(val argument: Argument, val values: List<String>)
 
-// TODO: swap to BaseCliktCommand<T>
-data class CommandInvocation(
-    val command: CliktCommand,
+data class CommandInvocation<RunnerT : Function<*>>(
+    val command: BaseCliktCommand<RunnerT>,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
 )
 
-class CommandLineParseResult(
-    val invocations: List<CommandInvocation>,
+class CommandLineParseResult<RunnerT : Function<*>>(
+    val invocations: List<CommandInvocation<RunnerT>>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
     val errors: List<CliktError>,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
index f4fe4a82..93a4ec1f 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
@@ -1,15 +1,11 @@
 package com.github.ajalt.clikt.tmp
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.internal.finalizeParameters
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
-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.parsers.CommandInvocation
 import com.github.ajalt.clikt.parsers.CommandLineParseResult
-import com.github.ajalt.clikt.parsers.Invocation
 import com.github.ajalt.clikt.parsers.shlex
 
 // TODO: move this back to parsers package
@@ -22,12 +18,15 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
-    // does not throw
-    fun parse(command: CliktCommand, originalArgv: List<String>): CommandLineParseResult {
+    // TODO: docs does not throw
+    fun <RunnerT : Function<*>> parse(
+        command: BaseCliktCommand<RunnerT>,
+        originalArgv: List<String>,
+    ): CommandLineParseResult<RunnerT> {
         return parseArgv(command, originalArgv)
     }
 
-    fun finalize(invocation: CommandInvocation) {
+    fun finalize(invocation: CommandInvocation<*>) {
         finalizeParameters(
             invocation.command.currentContext,
             invocation.command.registeredOptions(),
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
index f0cb4128..aae20295 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
@@ -6,8 +6,11 @@ import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 import com.github.ajalt.clikt.parsers.*
 
-internal fun parseArgv(command: CliktCommand, originalArgv: List<String>): CommandLineParseResult {
-    val results = mutableListOf<CommandInvocation>()
+internal fun <RunnerT : Function<*>> parseArgv(
+    command: BaseCliktCommand<RunnerT>,
+    originalArgv: List<String>,
+): CommandLineParseResult<RunnerT> {
+    val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
     val errors = mutableListOf<CliktError>()
     var i = 0
@@ -41,12 +44,12 @@ internal fun parseArgv(command: CliktCommand, originalArgv: List<String>): Comma
     return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
 }
 
-private fun parseCommand(
-    command: CliktCommand,
+private fun <RunnerT : Function<*>> parseCommand(
+    command: BaseCliktCommand<RunnerT>,
     parentContext: Context?,
     argv: List<String>,
     startingIndex: Int,
-): CommandParseResult {
+): CommandParseResult<RunnerT> {
     var tokens = argv
     val context = command.resetContext(parentContext)
     val aliases = command.aliases()
@@ -57,7 +60,7 @@ private fun parseCommand(
     val prefixes = mutableSetOf<String>()
     val longNames = mutableSetOf<String>()
     val argumentTokens = mutableListOf<String>()
-    var subcommand: CliktCommand? = null
+    var subcommand: BaseCliktCommand<RunnerT>? = null
     var canParseOptions = true
     var canExpandAtFiles = context.expandArgumentFiles
     val optInvocations = mutableListOf<OptInvocation>()
@@ -65,7 +68,7 @@ private fun parseCommand(
     var i = startingIndex
     var minAliasI = i
 
-    fun makeResult(): CommandParseResult {
+    fun makeResult(): CommandParseResult<RunnerT> {
         val opts = optInvocations.groupBy({ it.opt }, { it.inv })
         return CommandParseResult(subcommand, i, errors, tokens, opts, argumentTokens)
     }
@@ -205,12 +208,12 @@ private fun parseCommand(
 }
 
 /** Returns the new argv index and any errors */
-private fun handleExcessArgs(
+private fun <RunnerT : Function<*>> handleExcessArgs(
     argResult: ArgsParseResult,
-    command: CliktCommand,
+    command: BaseCliktCommand<RunnerT>,
     i: Int,
     expandedArgv: List<String>,
-    commandResult: CommandParseResult,
+    commandResult: CommandParseResult<RunnerT>,
 ): Pair<Int, List<CliktError>> {
     if (argResult.excessCount <= 0) return i to emptyList()
     val hasMultipleSubAncestor = command.currentContext.ancestors().any {
@@ -410,8 +413,8 @@ private fun loadArgFile(filename: String, context: Context): List<String> {
     return shlex(filename, context.argumentFileReader!!(filename), context.localization)
 }
 
-private data class CommandParseResult(
-    val subcommand: CliktCommand?,
+private data class CommandParseResult<RunnerT : Function<*>>(
+    val subcommand: BaseCliktCommand<RunnerT>?,
     val i: Int,
     val errors: List<CliktError>,
     val expandedArgv: List<String>,

From 1e8ac8b25566aa3bfea7933d608e047e28db7268 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 30 Mar 2024 17:32:04 -0700
Subject: [PATCH 05/43] Update everything to use new main extensions

---
 .../completion/BashCompletionGenerator.kt     |   6 +-
 .../clikt/completion/CompletionBuiltins.kt    |   3 +-
 .../clikt/completion/CompletionGenerator.kt   |   3 +-
 .../completion/FishCompletionGenerator.kt     |   7 +-
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 424 +++++++++++++
 .../github/ajalt/clikt/core/CliktCommand.kt   | 544 +++--------------
 .../ajalt/clikt/core/NoOpCliktCommand.kt      |   4 +-
 .../clikt/execution/CommandLineRunner.kt      |  41 --
 .../clikt/parameters/arguments/Argument.kt    |  14 +-
 .../clikt/parameters/groups/ChoiceGroup.kt    |  11 +-
 .../groups/CoOccurringOptionGroup.kt          |   7 +-
 .../groups/MutuallyExclusiveOption.kt         |   6 +-
 .../clikt/parameters/groups/ParameterGroup.kt |  19 +-
 .../clikt/parameters/options/EagerOption.kt   |  11 +-
 .../{tmp => parsers}/CommandLineParser.kt     |   5 +-
 .../com/github/ajalt/clikt/parsers/Parser.kt  | 565 ------------------
 .../ParserInternals.kt}                       |   5 +-
 .../ajalt/clikt/testing/CliktTesting.kt       |   9 +-
 .../clikt/output/MordantHelpFormatterTest.kt  |   1 +
 .../github/ajalt/clikt/testing/TestCommand.kt |   4 +-
 .../ajalt/clikt/samples/aliases/main.kt       |   1 +
 .../github/ajalt/clikt/samples/copy/main.kt   |   1 +
 .../ajalt/clikt/samples/helpformat/main.kt    |   1 +
 .../github/ajalt/clikt/samples/json/main.kt   |   1 +
 .../ajalt/clikt/samples/plugins/main.kt       |   1 +
 .../github/ajalt/clikt/samples/repo/main.kt   |   1 +
 .../ajalt/clikt/samples/validation/main.kt    |   1 +
 27 files changed, 561 insertions(+), 1135 deletions(-)
 create mode 100755 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
 delete mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
 rename clikt/src/commonMain/kotlin/com/github/ajalt/clikt/{tmp => parsers}/CommandLineParser.kt (84%)
 delete mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
 rename clikt/src/commonMain/kotlin/com/github/ajalt/clikt/{tmp/NewParser.kt => parsers/ParserInternals.kt} (99%)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/BashCompletionGenerator.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/BashCompletionGenerator.kt
index 3034516c..db5d2d30 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/BashCompletionGenerator.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/BashCompletionGenerator.kt
@@ -1,11 +1,11 @@
 package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.completion.CompletionCandidates.Custom.ShellType
-import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.parameters.options.Option
 
 internal object BashCompletionGenerator {
-    fun generateBashOrZshCompletion(command: CliktCommand, zsh: Boolean): String {
+    fun generateBashOrZshCompletion(command: BaseCliktCommand<*>, zsh: Boolean): String {
         val commandName = command.commandName
         val (isTopLevel, funcName) = commandCompletionFuncName(command)
         val options = command._options
@@ -297,7 +297,7 @@ internal object BashCompletionGenerator {
         }
     }
 
-    private fun commandCompletionFuncName(command: CliktCommand): Pair<Boolean, String> {
+    private fun commandCompletionFuncName(command: BaseCliktCommand<*>): Pair<Boolean, String> {
         val ancestors = generateSequence(command.currentContext) { it.parent }
             .map { it.command.commandName }
             .toList().asReversed()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
index 815b41d4..fe2d8479 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
@@ -1,5 +1,6 @@
 package com.github.ajalt.clikt.completion
 
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
@@ -11,7 +12,7 @@ private val choices = arrayOf("bash", "zsh", "fish")
 /**
  * Add an option to a command that will print a completion script for the given shell when invoked.
  */
-fun <T : CliktCommand> T.completionOption(
+fun <T : BaseCliktCommand<*>> T.completionOption(
     vararg names: String = arrayOf("--generate-completion"),
     help: String = "",
     hidden: Boolean = false,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
index 24ed45e2..4c9144f8 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
@@ -1,10 +1,11 @@
 package com.github.ajalt.clikt.completion
 
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.PrintCompletionMessage
 
 internal object CompletionGenerator {
-    fun throwCompletionMessage(command: CliktCommand, shell: String): Nothing {
+    fun throwCompletionMessage(command: BaseCliktCommand<*>, shell: String): Nothing {
         val message = when (shell.trim().lowercase()) {
             "fish" -> FishCompletionGenerator.generateFishCompletion(command = command)
             "zsh" -> BashCompletionGenerator.generateBashOrZshCompletion(
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
index 67c18c6e..48509ed7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
@@ -1,17 +1,18 @@
 package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.completion.CompletionCandidates.Custom.ShellType
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.options.Option
 
 internal object FishCompletionGenerator {
-    fun generateFishCompletion(command: CliktCommand): String {
+    fun generateFishCompletion(command: BaseCliktCommand<*>): String {
         if (!command.hasFishCompletionRequirements) return ""
         return generateFishCompletionForCommand(command)
     }
 
 
-    private fun generateFishCompletionForCommand(command: CliktCommand): String = buildString {
+    private fun generateFishCompletionForCommand(command: BaseCliktCommand<*>): String = buildString {
         val parentCommandName = command.currentContext.parentNames().lastOrNull()
         val rootCommandName = command.currentContext.commandNameWithParents().first()
         val isTopLevel = parentCommandName == null
@@ -171,7 +172,7 @@ internal object FishCompletionGenerator {
         return joinToString("_", postfix = "_subcommands") { it.replace(Regex("\\W"), "_") }
     }
 
-    private val CliktCommand.hasFishCompletionRequirements: Boolean
+    private val BaseCliktCommand<*>.hasFishCompletionRequirements: Boolean
         get() = _arguments.isNotEmpty()
                 || _subcommands.isNotEmpty()
                 || _options.flatMap { it.allNames }.any { it.isValidFishCompletionOption }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
new file mode 100755
index 00000000..e1b49e6f
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -0,0 +1,424 @@
+package com.github.ajalt.clikt.core
+
+import com.github.ajalt.clikt.completion.CompletionGenerator
+import com.github.ajalt.clikt.output.HelpFormatter
+import com.github.ajalt.clikt.parameters.arguments.Argument
+import com.github.ajalt.clikt.parameters.arguments.argument
+import com.github.ajalt.clikt.parameters.groups.OptionGroup
+import com.github.ajalt.clikt.parameters.groups.ParameterGroup
+import com.github.ajalt.clikt.parameters.options.Option
+import com.github.ajalt.clikt.parameters.options.eagerOption
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.mordant.terminal.Terminal
+
+/**
+ * A base class for commands that want to define a custom type for their `run` function.
+ */
+@Suppress("PropertyName")
+@ParameterHolderDsl
+abstract class BaseCliktCommand<RunnerT : Function<*>>(
+    /**
+     * The help for this command. The first line is used in the usage string, and the entire string
+     * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
+     */
+    private val help: String = "",
+    /**
+     * Text to display at the end of the full help output. It is automatically re-wrapped to the
+     * terminal width.
+     */
+    private val epilog: String = "",
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
+    name: String? = null,
+    /**
+     * Used when this command has subcommands, and this command is called without a subcommand. If
+     * true, [run] will be called. By default, a [PrintHelpMessage] is thrown instead.
+     */
+    val invokeWithoutSubcommand: Boolean = false,
+    /**
+     * If this command is called with no values on the command line, print a help message (by
+     * throwing [PrintHelpMessage]) if this is true, otherwise run normally.
+     */
+    val printHelpOnEmptyArgs: Boolean = false,
+    /**
+     * Extra information about this command to pass to the help formatter.
+     */
+    val helpTags: Map<String, String> = emptyMap(),
+    /**
+     * The envvar to use to enable shell autocomplete script generation. Set to null to disable
+     * generation.
+     */
+    private val autoCompleteEnvvar: String? = "",
+    /**
+     * If true, allow multiple of this command's subcommands to be called sequentially. This will
+     * disable `allowInterspersedArgs` on the context of this command and its descendants.
+     */
+    internal val allowMultipleSubcommands: Boolean = false,
+    /**
+     * If true, any options on the command line whose names aren't valid will be parsed as an
+     * argument rather than reporting an error. You'll need to define an `argument().multiple()` to
+     * collect these options, or an error will still be reported. Unknown short option flags grouped
+     * with other flags on the command line will always be reported as errors.
+     */
+    internal val treatUnknownOptionsAsArgs: Boolean = false,
+    /**
+     * If true, don't display this command in help output when used as a subcommand.
+     */
+    private val hidden: Boolean = false,
+) : ParameterHolder {
+    /**
+     * The function to run when this command is invoked.
+     *
+     * For [CliktCommand], this just calls `run`.
+     */
+    abstract val runner: RunnerT
+
+    /**
+     * The name of this command, used in help output.
+     *
+     * You can set this by passing `name` to the [CliktCommand] constructor.
+     */
+    val commandName: String = name ?: inferCommandName()
+
+    /**
+     * The help text for this command.
+     *
+     * You can set this by passing `help` to the [CliktCommand] constructor, or by overriding this
+     * method if you need to build the string lazily or access the terminal or context.
+     *
+     * ### Example:
+     *
+     * ```
+     * class Command: CliktCommand() {
+     *     override fun commandHelp(context: Context): String {
+     *         return context.theme.info("This is a command")
+     *     }
+     * }
+     * ```
+     */
+    open fun commandHelp(context: Context): String {
+        return help
+    }
+
+    /**
+     * Help text to display at the end of the help output, after any parameters.
+     *
+     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
+     * method.
+     */
+    open fun commandHelpEpilog(context: Context): String {
+        return epilog
+    }
+
+    internal var _subcommands: List<BaseCliktCommand<RunnerT>> = emptyList()
+    internal val _options: MutableList<Option> = mutableListOf()
+    internal val _arguments: MutableList<Argument> = mutableListOf()
+    internal val _groups: MutableList<ParameterGroup> = mutableListOf()
+    internal var _contextConfig: Context.Builder.() -> Unit = {}
+    private var _context: Context? = null
+    private val _messages = mutableListOf<String>()
+
+    private fun registeredOptionNames() = _options.flatMapTo(mutableSetOf()) { it.names }
+
+    fun resetContext(parent: Context?): Context {
+        //TODO ("doc that each run get a fresh context now")
+        _context?.close()
+        // TODO either pass argv or remove it from ctx
+        _context = Context.build(this, parent, emptyList(), _contextConfig)
+
+        if (allowMultipleSubcommands) {
+            require(currentContext.ancestors().none { it.command.allowMultipleSubcommands }) {
+                "Commands with allowMultipleSubcommands=true cannot be nested in " +
+                        "commands that also have allowMultipleSubcommands=true"
+            }
+        }
+
+        if (currentContext.helpOptionNames.isNotEmpty()) {
+            val names = currentContext.helpOptionNames - registeredOptionNames()
+            if (names.isNotEmpty()) {
+                eagerOption(names, currentContext.localization.helpOptionMessage()) {
+                    throw PrintHelpMessage(context)
+                }
+            }
+        }
+        // TODO
+        //  val a = (ancestors + parent?.command).filterNotNull()
+        //  check(command !in a) { "Command ${command.commandName} already registered" }
+        return _context!!
+    }
+
+    /**
+     * Return the parameters that should be sent to the help formatter when this command's [getFormattedHelp] is
+     * called.
+     */
+    open fun allHelpParams(): List<HelpFormatter.ParameterHelp> {
+        return listOf(
+            _options.mapNotNull { it.parameterHelp(currentContext) },
+            _arguments.mapNotNull { it.parameterHelp(currentContext) },
+            _groups.mapNotNull { it.parameterHelp(currentContext) },
+            _subcommands.mapNotNull { c ->
+                HelpFormatter.ParameterHelp.Subcommand(
+                    c.commandName,
+                    c.shortHelp(currentContext),
+                    c.helpTags
+                ).takeUnless { c.hidden }
+            }
+        ).flatten()
+    }
+
+    private fun getCommandNameWithParents(): String {
+        if (_context == null) resetContext(null)
+        return currentContext.commandNameWithParents().joinToString(" ")
+    }
+
+    private fun generateCompletion() {
+        if (autoCompleteEnvvar == null) return
+        val envvar = when {
+            autoCompleteEnvvar.isBlank() -> "_${commandName.replace("-", "_").uppercase()}_COMPLETE"
+            else -> autoCompleteEnvvar
+        }
+
+        val envval = currentContext.readEnvvar(envvar) ?: return
+
+        CompletionGenerator.throwCompletionMessage(this, envval)
+    }
+
+    /**
+     * This command's context.
+     *
+     * @throws NullPointerException if accessed before [parse] or [main] are called.
+     */
+    val currentContext: Context
+        get() {
+            checkNotNull(_context) { "Context accessed before parse has been called." }
+            return _context!!
+        }
+
+    /** All messages issued during parsing. */
+    val messages: List<String> get() = _messages
+
+    /** Add a message to be printed after parsing */
+    fun issueMessage(message: String) {
+        _messages += message
+    }
+
+    /** The help displayed in the commands list when this command is used as a subcommand. */
+    protected fun shortHelp(context: Context): String =
+        Regex("""\s*(?:```)?\s*(.+)""").find(commandHelp(context))?.groups?.get(1)?.value ?: ""
+
+    /** The names of all direct children of this command */
+    fun registeredSubcommandNames(): List<String> = _subcommands.map { it.commandName }
+
+    /**
+     * Get a read-only list of commands registered as [subcommands] of this command.
+     */
+    fun registeredSubcommands(): List<BaseCliktCommand<RunnerT>> = _subcommands.toList()
+
+    /**
+     * Get a read-only list of options registered in this command (e.g. via [registerOption] or an
+     * [option] delegate)
+     */
+    fun registeredOptions(): List<Option> = _options.toList()
+
+    /**
+     * Get a read-only list of arguments registered in this command (e.g. via [registerArgument] or
+     * an [argument] delegate)
+     */
+    fun registeredArguments(): List<Argument> = _arguments.toList()
+
+    /**
+     * Get a read-only list of groups registered in this command (e.g. via [registerOptionGroup] or
+     * an [OptionGroup] delegate)
+     */
+    fun registeredParameterGroups(): List<ParameterGroup> = _groups.toList()
+
+    /**
+     * Register an option with this command.
+     *
+     * This is called automatically for the built-in options, but you need to call this if you want to add a
+     * custom option.
+     */
+    fun registerOption(option: Option) {
+        val names = registeredOptionNames()
+        for (name in option.names) {
+            require(name !in names) { "Duplicate option name $name" }
+        }
+        if (option.acceptsNumberValueWithoutName) {
+            require(_options.none { it.acceptsNumberValueWithoutName }) {
+                "Multiple options with acceptsNumberValueWithoutName"
+            }
+        }
+        _options += option
+    }
+
+    override fun registerOption(option: GroupableOption) = registerOption(option as Option)
+
+    /**
+     * Register an argument with this command.
+     *
+     * This is called automatically for the built-in arguments, but you need to call this if you want to add a
+     * custom argument.
+     */
+    fun registerArgument(argument: Argument) {
+        require(argument.nvalues > 0 || _arguments.none { it.nvalues < 0 }) {
+            "Cannot declare multiple arguments with variable numbers of values"
+        }
+        _arguments += argument
+    }
+
+    /**
+     * Register a group with this command.
+     *
+     * This is called automatically for built-in groups, but you need to call this if you want to
+     * add a custom group.
+     *
+     * If you call this manually, you also need to call [registerOption] for any options within the group.
+     */
+    fun registerOptionGroup(group: ParameterGroup) {
+        require(group !in _groups) { "Cannot register the same group twice" }
+        require(group.groupName == null || _groups.none { it.groupName == group.groupName }) {
+            "Cannot register the same group name twice"
+        }
+        _groups += group
+    }
+
+
+    /**
+     * Return the help string for this command, optionally with an [error].
+     *
+     * Return `null` if the error does not have a message (e.g. [ProgramResult])
+     */
+    fun getFormattedHelp(error: CliktError? = null): String? {
+        if (error != null && error !is ContextCliktError) {
+            return error.message
+        }
+
+        val ctx = (error as? ContextCliktError)?.context ?: _context ?: resetContext(null)
+        val cmd = ctx.command
+        val programName = cmd.getCommandNameWithParents()
+        return ctx.helpFormatter(ctx).formatHelp(
+            error as? UsageError,
+            cmd.commandHelp(ctx),
+            cmd.commandHelpEpilog(ctx),
+            cmd.allHelpParams(),
+            programName
+        )
+    }
+
+    /**
+     * Echo the string returned by [getFormattedHelp].
+     */
+    fun echoFormattedHelp(error: CliktError? = null) {
+        val msg = getFormattedHelp(error)
+        if (msg != null) {
+            echo(msg, err = error?.printError ?: false)
+        }
+    }
+
+    /**
+     * A list of command aliases.
+     *
+     * If the user enters a command that matches a key in this map, the command is replaced with the
+     * corresponding value in the map. The aliases aren't recursive, so aliases won't be looked up again while
+     * tokens from an existing alias are being parsed.
+     */
+    open fun aliases(): Map<String, List<String>> = emptyMap()
+
+    /** Print a line break to `stdout` */
+    fun echo() {
+        echo("")
+    }
+
+    /**
+     * Print the [message] to the screen.
+     *
+     * This is similar to [print] or [println], but converts newlines to the system line separator.
+     *
+     * @param message The message to print.
+     * @param trailingNewline If true, behave like [println], otherwise behave like [print]
+     * @param err If true, print to stderr instead of stdout
+     */
+    fun echo(
+        message: Any?,
+        trailingNewline: Boolean = true,
+        err: Boolean = false,
+    ) {
+        if (trailingNewline) {
+            currentContext.terminal.println(message, stderr = err)
+        } else {
+            currentContext.terminal.print(message, stderr = err)
+        }
+    }
+
+    override fun toString() = buildString {
+        append("<${this@BaseCliktCommand.classSimpleName()} name=$commandName")
+
+        if (_options.isNotEmpty()) {
+            _options.joinTo(this, prefix = " options=[", postfix = "]")
+        }
+
+        if (_arguments.isNotEmpty()) {
+            _arguments.joinTo(this, prefix = " arguments=[", postfix = "]")
+        }
+
+        if (_subcommands.isNotEmpty()) {
+            _subcommands.joinTo(this, prefix = " subcommands=[", postfix = "]")
+        }
+
+        append(">")
+    }
+}
+
+/** Add the given commands as a subcommand of this command. */
+fun <RunnerT, BaseT : BaseCliktCommand<RunnerT>, CommandT : BaseT> CommandT.subcommands(
+    commands: Iterable<BaseT>,
+): CommandT = apply {
+    _subcommands = _subcommands + commands
+}
+
+/** Add the given commands as a subcommand of this command. */
+fun <RunnerT, BaseT : BaseCliktCommand<RunnerT>, CommandT : BaseT> CommandT.subcommands(
+    vararg commands: BaseT,
+): CommandT = apply {
+    _subcommands = _subcommands + commands
+}
+
+/**
+ * Configure this command's [Context].
+ *
+ * Context property values are normally inherited from the parent context, but you can override any of them
+ * here.
+ */
+fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.context(
+    block: Context.Builder.() -> Unit,
+): CommandT = apply {
+    // save the old config to allow multiple context calls
+    val c = _contextConfig
+    _contextConfig = {
+        c()
+        block()
+    }
+}
+
+private fun Any.classSimpleName(): String = this::class.simpleName.orEmpty().split("$").last()
+private fun BaseCliktCommand<*>.inferCommandName(): String {
+    val name = classSimpleName()
+
+    val suffixes = setOf("Command", "Commands")
+    if (name in suffixes) return name.lowercase()
+
+    val nameWithoutSuffixes = suffixes.fold(name) { acc, s -> acc.removeSuffix(s) }
+    val lowerUpperRegex = Regex("([a-z])([A-Z])")
+
+    return nameWithoutSuffixes.replace(lowerUpperRegex) {
+        "${it.groupValues[1]}-${it.groupValues[2]}"
+    }.lowercase()
+}
+
+/**
+ * A shortcut for accessing the terminal from the [currentContext][CliktCommand.currentContext]
+ */
+val BaseCliktCommand<*>.terminal: Terminal
+    get() = currentContext.terminal
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index bd0790a3..50c6740b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -1,496 +1,100 @@
 package com.github.ajalt.clikt.core
 
-import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.mpp.exitProcessMpp
-import com.github.ajalt.clikt.output.HelpFormatter.ParameterHelp
-import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.arguments.argument
-import com.github.ajalt.clikt.parameters.groups.OptionGroup
-import com.github.ajalt.clikt.parameters.groups.ParameterGroup
-import com.github.ajalt.clikt.parameters.options.*
-import com.github.ajalt.clikt.parsers.Parser
-import com.github.ajalt.mordant.terminal.Terminal
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parsers.CommandLineParser
 
-// TODO: docs
 /**
- * A base class for commands that want to define a custom type for their `run` function.
+ * The [CliktCommand] is the core of command line interfaces in Clikt.
+ *
+ * Command line interfaces created by creating a subclass of [CliktCommand] with properties defined with
+ * [option] and [argument]. You can then parse `argv` by calling [main], which will take care of printing
+ * errors and help to the user. If you want to handle output yourself, you can use [parse] instead.
+ *
+ * Once the command line has been parsed and all the parameters are populated, [run] is called.
  */
-@Suppress("PropertyName")
-@ParameterHolderDsl
-abstract class BaseCliktCommand<RunnerT : Function<*>>(
-    /**
-     * The help for this command. The first line is used in the usage string, and the entire string
-     * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
-     */
-    private val help: String = "",
-    /**
-     * Text to display at the end of the full help output. It is automatically re-wrapped to the
-     * terminal width.
-     */
-    private val epilog: String = "",
-    /**
-     * The name of the program to use in the help output. If not given, it is inferred from the
-     * class name.
-     */
+abstract class CliktCommand(
+    help: String = "",
+    epilog: String = "",
     name: String? = null,
-    /**
-     * Used when this command has subcommands, and this command is called without a subcommand. If
-     * true, [run] will be called. By default, a [PrintHelpMessage] is thrown instead.
-     */
-    val invokeWithoutSubcommand: Boolean = false,
-    /**
-     * If this command is called with no values on the command line, print a help message (by
-     * throwing [PrintHelpMessage]) if this is true, otherwise run normally.
-     */
-    val printHelpOnEmptyArgs: Boolean = false,
-    /**
-     * Extra information about this command to pass to the help formatter.
-     */
-    val helpTags: Map<String, String> = emptyMap(),
-    /**
-     * The envvar to use to enable shell autocomplete script generation. Set to null to disable
-     * generation.
-     */
-    private val autoCompleteEnvvar: String? = "",
-    /**
-     * If true, allow multiple of this command's subcommands to be called sequentially. This will
-     * disable `allowInterspersedArgs` on the context of this command and its descendants.
-     */
-    internal val allowMultipleSubcommands: Boolean = false,
-    /**
-     * If true, any options on the command line whose names aren't valid will be parsed as an
-     * argument rather than reporting an error. You'll need to define an `argument().multiple()` to
-     * collect these options, or an error will still be reported. Unknown short option flags grouped
-     * with other flags on the command line will always be reported as errors.
-     */
-    internal val treatUnknownOptionsAsArgs: Boolean = false,
-    /**
-     * If true, don't display this command in help output when used as a subcommand.
-     */
-    private val hidden: Boolean = false,
-) : ParameterHolder {
-    /**
-     * The function to run when this command is invoked.
-     *
-     * For [CliktCommand], this just calls `run`.
-     */
-    abstract val runner: RunnerT
-
-    /**
-     * The name of this command, used in help output.
-     *
-     * You can set this by passing `name` to the [CliktCommand] constructor.
-     */
-    val commandName: String = name ?: inferCommandName()
-
-    /**
-     * The help text for this command.
-     *
-     * You can set this by passing `help` to the [CliktCommand] constructor, or by overriding this
-     * method if you need to build the string lazily or access the terminal or context.
-     *
-     * ### Example:
-     *
-     * ```
-     * class Command: CliktCommand() {
-     *     override fun commandHelp(context: Context): String {
-     *         return context.theme.info("This is a command")
-     *     }
-     * }
-     * ```
-     */
-    open fun commandHelp(context: Context): String {
-        return help
-    }
-
-    /**
-     * Help text to display at the end of the help output, after any parameters.
-     *
-     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
-     * method.
-     */
-    open fun commandHelpEpilog(context: Context): String {
-        return epilog
-    }
-
-    internal var _subcommands: List<BaseCliktCommand<RunnerT>> = emptyList()
-    internal val _options: MutableList<Option> = mutableListOf()
-    internal val _arguments: MutableList<Argument> = mutableListOf()
-    internal val _groups: MutableList<ParameterGroup> = mutableListOf()
-    internal var _contextConfig: Context.Builder.() -> Unit = {}
-    private var _context: Context? = null
-    private val _messages = mutableListOf<String>()
-
-    private fun registeredOptionNames() = _options.flatMapTo(mutableSetOf()) { it.names }
-
-    fun resetContext(parent: Context?): Context {
-        //TODO ("doc that each run get a fresh context now")
-        _context?.close()
-        // TODO either pass argv or remove it from ctx
-        _context = Context.build(this, parent, emptyList(), _contextConfig)
-
-        if (allowMultipleSubcommands) {
-            require(currentContext.ancestors().none { it.command.allowMultipleSubcommands }) {
-                "Commands with allowMultipleSubcommands=true cannot be nested in " +
-                        "commands that also have allowMultipleSubcommands=true"
-            }
-        }
-
-        if (currentContext.helpOptionNames.isNotEmpty()) {
-            val names = currentContext.helpOptionNames - registeredOptionNames()
-            if (names.isNotEmpty()) {
-                eagerOption(names, currentContext.localization.helpOptionMessage()) {
-                    throw PrintHelpMessage(context)
-                }
-            }
-        }
-        // TODO  check(command !in a) { "Command ${command.commandName} already registered" }
-        return _context!!
-    }
-
-    private fun createContext(
-        argv: List<String>,
-        parent: Context?,
-        ancestors: List<BaseCliktCommand<RunnerT>>,
-    ): Context {
-        _context = Context.build(this, parent, argv, _contextConfig)
-
-        if (allowMultipleSubcommands) {
-            require(currentContext.ancestors().none { it.command.allowMultipleSubcommands }) {
-                "Commands with allowMultipleSubcommands=true cannot be nested in " +
-                        "commands that also have allowMultipleSubcommands=true"
-            }
-        }
-
-        if (currentContext.helpOptionNames.isNotEmpty()) {
-            val names = currentContext.helpOptionNames - registeredOptionNames()
-            if (names.isNotEmpty()) {
-                eagerOption(names, currentContext.localization.helpOptionMessage()) {
-                    throw PrintHelpMessage(context)
-                }
-            }
-        }
-
-        for (command in _subcommands) {
-            val a = (ancestors + parent?.command).filterNotNull()
-            check(command !in a) { "Command ${command.commandName} already registered" }
-            command.createContext(argv, currentContext, a)
-        }
-        return _context!!
-    }
-
-    /**
-     * Return the parameters that should be sent to the help formatter when this command's [getFormattedHelp] is
-     * called.
-     */
-    open fun allHelpParams(): List<ParameterHelp> {
-        return listOf(
-            _options.mapNotNull { it.parameterHelp(currentContext) },
-            _arguments.mapNotNull { it.parameterHelp(currentContext) },
-            _groups.mapNotNull { it.parameterHelp(currentContext) },
-            _subcommands.mapNotNull { c ->
-                ParameterHelp.Subcommand(
-                    c.commandName,
-                    c.shortHelp(currentContext),
-                    c.helpTags
-                ).takeUnless { c.hidden }
-            }
-        ).flatten()
-    }
-
-    private fun getCommandNameWithParents(): String {
-        if (_context == null) resetContext(null)
-        return currentContext.commandNameWithParents().joinToString(" ")
-    }
-
-    private fun generateCompletion() {
-        if (autoCompleteEnvvar == null) return
-        val envvar = when {
-            autoCompleteEnvvar.isBlank() -> "_${commandName.replace("-", "_").uppercase()}_COMPLETE"
-            else -> autoCompleteEnvvar
-        }
-
-        val envval = currentContext.readEnvvar(envvar) ?: return
-
-        CompletionGenerator.throwCompletionMessage(this, envval)
-    }
-
-    /**
-     * This command's context.
-     *
-     * @throws NullPointerException if accessed before [parse] or [main] are called.
-     */
-    val currentContext: Context
-        get() {
-            checkNotNull(_context) { "Context accessed before parse has been called." }
-            return _context!!
-        }
-
-    /** All messages issued during parsing. */
-    val messages: List<String> get() = _messages
-
-    /** Add a message to be printed after parsing */
-    fun issueMessage(message: String) {
-        _messages += message
-    }
-
-    /** The help displayed in the commands list when this command is used as a subcommand. */
-    protected fun shortHelp(context: Context): String =
-        Regex("""\s*(?:```)?\s*(.+)""").find(commandHelp(context))?.groups?.get(1)?.value ?: ""
-
-    /** The names of all direct children of this command */
-    fun registeredSubcommandNames(): List<String> = _subcommands.map { it.commandName }
-
-    /**
-     * Get a read-only list of commands registered as [subcommands] of this command.
-     */
-    fun registeredSubcommands(): List<CliktCommand> = _subcommands.toList()
-
-    /**
-     * Get a read-only list of options registered in this command (e.g. via [registerOption] or an [option] delegate)
-     */
-    fun registeredOptions(): List<Option> = _options.toList()
-
-    /**
-     * Get a read-only list of arguments registered in this command (e.g. via [registerArgument] or an [argument] delegate)
-     */
-    fun registeredArguments(): List<Argument> = _arguments.toList()
-
-    /**
-     * Get a read-only list of groups registered in this command (e.g. via [registerOptionGroup] or an [OptionGroup] delegate)
-     */
-    fun registeredParameterGroups(): List<ParameterGroup> = _groups.toList()
-
-    /**
-     * Register an option with this command.
-     *
-     * This is called automatically for the built-in options, but you need to call this if you want to add a
-     * custom option.
-     */
-    fun registerOption(option: Option) {
-        val names = registeredOptionNames()
-        for (name in option.names) {
-            require(name !in names) { "Duplicate option name $name" }
-        }
-        if (option.acceptsNumberValueWithoutName) {
-            require(_options.none { it.acceptsNumberValueWithoutName }) {
-                "Multiple options with acceptsNumberValueWithoutName"
-            }
-        }
-        _options += option
-    }
-
-    override fun registerOption(option: GroupableOption) = registerOption(option as Option)
-
-    /**
-     * Register an argument with this command.
-     *
-     * This is called automatically for the built-in arguments, but you need to call this if you want to add a
-     * custom argument.
-     */
-    fun registerArgument(argument: Argument) {
-        require(argument.nvalues > 0 || _arguments.none { it.nvalues < 0 }) {
-            "Cannot declare multiple arguments with variable numbers of values"
-        }
-        _arguments += argument
-    }
-
-    /**
-     * Register a group with this command.
-     *
-     * This is called automatically for built-in groups, but you need to call this if you want to
-     * add a custom group.
-     *
-     * If you call this manually, you also need to call [registerOption] for any options within the group.
-     */
-    fun registerOptionGroup(group: ParameterGroup) {
-        require(group !in _groups) { "Cannot register the same group twice" }
-        require(group.groupName == null || _groups.none { it.groupName == group.groupName }) {
-            "Cannot register the same group name twice"
-        }
-        _groups += group
-    }
-
-
-    /**
-     * Return the help string for this command, optionally with an [error].
-     *
-     * Return `null` if the error does not have a message (e.g. [ProgramResult])
-     */
-    fun getFormattedHelp(error: CliktError? = null): String? {
-        if (error != null && error !is ContextCliktError) {
-            return error.message
-        }
-
-        val ctx = (error as? ContextCliktError)?.context ?: _context ?: resetContext(null)
-        val cmd = ctx.command
-        val programName = cmd.getCommandNameWithParents()
-        return ctx.helpFormatter(ctx).formatHelp(
-            error as? UsageError,
-            cmd.commandHelp(ctx),
-            cmd.commandHelpEpilog(ctx),
-            cmd.allHelpParams(),
-            programName
-        )
-    }
-
-    /**
-     * Echo the string returned by [getFormattedHelp].
-     */
-    fun echoFormattedHelp(error: CliktError? = null) {
-        val msg = getFormattedHelp(error)
-        if (msg != null) {
-            echo(msg, err = error?.printError ?: false)
-        }
-    }
-
-    /**
-     * A list of command aliases.
-     *
-     * If the user enters a command that matches a key in this map, the command is replaced with the
-     * corresponding value in the map. The aliases aren't recursive, so aliases won't be looked up again while
-     * tokens from an existing alias are being parsed.
-     */
-    open fun aliases(): Map<String, List<String>> = emptyMap()
-
-    /** Print a line break to `stdout` */
-    fun echo() {
-        echo("")
-    }
-
-    /**
-     * Print the [message] to the screen.
-     *
-     * This is similar to [print] or [println], but converts newlines to the system line separator.
-     *
-     * @param message The message to print.
-     * @param trailingNewline If true, behave like [println], otherwise behave like [print]
-     * @param err If true, print to stderr instead of stdout
-     */
-    fun echo(
-        message: Any?,
-        trailingNewline: Boolean = true,
-        err: Boolean = false,
-    ) {
-        if (trailingNewline) {
-            currentContext.terminal.println(message, stderr = err)
-        } else {
-            currentContext.terminal.print(message, stderr = err)
-        }
-    }
-
-    /**
-     * Parse the command line and throw an exception if parsing fails.
-     *
-     * You should use [main] instead unless you want to handle output yourself.
-     */
-    fun parse(argv: List<String>, parentContext: Context? = null) {
-        generateCompletion()
-        Parser.parse(argv, this.currentContext)
-    }
-
-    fun parse(argv: Array<String>, parentContext: Context? = null) {
-        parse(argv.asList(), parentContext)
-    }
-
-    /**
-     * Parse the command line and print helpful output if any errors occur.
-     *
-     * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process with the specified
-     * [status code][CliktError.statusCode]. Other errors are allowed to pass through.
-     *
-     * If you don't want Clikt to exit your process, call [parse] instead.
-     */
-    fun main(argv: List<String>) {
-        try {
-            parse(argv)
-        } catch (e: CliktError) {
-            echoFormattedHelp(e)
-            exitProcessMpp(e.statusCode)
-        }
-    }
-
-    fun main(argv: Array<out String>) = main(argv.asList())
+    invokeWithoutSubcommand: Boolean = false,
+    printHelpOnEmptyArgs: Boolean = false,
+    helpTags: Map<String, String> = emptyMap(),
+    autoCompleteEnvvar: String? = "",
+    allowMultipleSubcommands: Boolean = false,
+    treatUnknownOptionsAsArgs: Boolean = false,
+    hidden: Boolean = false,
+) : BaseCliktCommand<() -> Unit>(
+    help,
+    epilog,
+    name,
+    invokeWithoutSubcommand,
+    printHelpOnEmptyArgs,
+    helpTags,
+    autoCompleteEnvvar,
+    allowMultipleSubcommands,
+    treatUnknownOptionsAsArgs,
+    hidden
+) {
+    final override val runner: () -> Unit = ::run
 
     /**
      * Perform actions after parsing is complete and this command is invoked.
      *
-     * This is called after command line parsing is complete. If this command is a subcommand, this will only
-     * be called if the subcommand is invoked.
+     * This is called after command line parsing is complete. If this command is a subcommand, this
+     * will only be called if the subcommand is invoked.
      *
-     * If one of this command's subcommands is invoked, this is called before the subcommand's arguments are
-     * parsed.
+     * If one of this command's subcommands is invoked, this is called before the subcommand's
+     * arguments are parsed.
      */
     abstract fun run()
-
-    override fun toString() = buildString {
-        append("<${this@BaseCliktCommand.classSimpleName()} name=$commandName")
-
-        if (_options.isNotEmpty()) {
-            _options.joinTo(this, prefix = " options=[", postfix = "]")
-        }
-
-        if (_arguments.isNotEmpty()) {
-            _arguments.joinTo(this, prefix = " arguments=[", postfix = "]")
-        }
-
-        if (_subcommands.isNotEmpty()) {
-            _subcommands.joinTo(this, prefix = " subcommands=[", postfix = "]")
-        }
-
-        append(">")
-    }
 }
 
-//abstract class CliktCommand : BaseCliktCommand<() -> Unit>() {
-//    override fun run() {
-//        throw PrintHelpMessage(currentContext)
-//    }
-//}
-
-/** Add the given commands as a subcommand of this command. */
-fun <RunnerT, CommandT> CommandT.subcommands(commands: Iterable<CommandT>): CommandT
-        where CommandT : BaseCliktCommand<RunnerT> = apply {
-    _subcommands = _subcommands + commands
-}
-
-/** Add the given commands as a subcommand of this command. */
-fun <RunnerT, CommandT> CommandT.subcommands(vararg commands: CommandT): CommandT
-        where CommandT : BaseCliktCommand<RunnerT> = apply {
-    _subcommands = _subcommands + commands
-}
+/**
+ * Parse the command line and print helpful output if any errors occur.
+ *
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
+ */
+fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asList())
 
 /**
- * Configure this command's [Context].
+ * Parse the command line and print helpful output if any errors occur.
  *
- * Context property values are normally inherited from the parent context, but you can override any of them
- * here.
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun <T : BaseCliktCommand<*>> T.context(block: Context.Builder.() -> Unit): T = apply {
-    // save the old config to allow multiple context calls
-    val c = _contextConfig
-    _contextConfig = {
-        c()
-        block()
+fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) {
+    try {
+        parse(argv)
+    } catch (e: CliktError) {
+        echoFormattedHelp(e)
+        exitProcessMpp(e.statusCode)
     }
 }
 
-private fun Any.classSimpleName(): String = this::class.simpleName.orEmpty().split("$").last()
-
-private fun BaseCliktCommand<*>.inferCommandName(): String {
-    val name = classSimpleName()
-
-    val suffixes = setOf("Command", "Commands")
-    if (name in suffixes) return name.lowercase()
-
-    val nameWithoutSuffixes = suffixes.fold(name) { acc, s -> acc.removeSuffix(s) }
-    val lowerUpperRegex = Regex("([a-z])([A-Z])")
-
-    return nameWithoutSuffixes.replace(lowerUpperRegex) {
-        "${it.groupValues[1]}-${it.groupValues[2]}"
-    }.lowercase()
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
+    parse(argv.asList())
 }
 
-/** A short for accessing the terminal from the [currentContext][CliktCommand.currentContext] */
-val BaseCliktCommand<*>.terminal: Terminal
-    get() = currentContext.terminal
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+fun BaseCliktCommand<() -> Unit>.parse(argv: List<String>) {
+// TODO   generateCompletion()
+    CommandLineParser.parse(this, argv)
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
index 746e8539..af32aaca 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
@@ -13,7 +13,7 @@ open class NoOpCliktCommand(
     autoCompleteEnvvar: String? = "",
     allowMultipleSubcommands: Boolean = false,
     hidden: Boolean = false,
-) : CliktCommand(
+) : BaseCliktCommand<() -> Unit>(
     help,
     epilog,
     name,
@@ -24,5 +24,5 @@ open class NoOpCliktCommand(
     allowMultipleSubcommands,
     hidden
 ) {
-    override fun run() = Unit
+    final override val runner: () -> Unit = {}
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
deleted file mode 100644
index 3509b59d..00000000
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/execution/CommandLineRunner.kt
+++ /dev/null
@@ -1,41 +0,0 @@
-package com.github.ajalt.clikt.execution
-
-import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktError
-import com.github.ajalt.clikt.mpp.exitProcessMpp
-import com.github.ajalt.clikt.tmp.CommandLineParser
-
-fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
-    val result = CommandLineParser.parse(this, argv.asList())
-    for (invocation in result.invocations) {
-        CommandLineParser.finalize(invocation)
-        invocation.command.runner()
-    }
-}
-
-//fun BaseCliktCommand<() -> Unit>.main(argv: Array<String>) {
-//    try {
-//        parse(argv)
-//    } catch (e: CliktError) {
-//        echoFormattedHelp(e)
-//        exitProcessMpp(e.statusCode)
-//    }
-//}
-
-suspend fun BaseCliktCommand<suspend () -> Unit>.parse(argv: Array<String>) {
-    val result = CommandLineParser.parse(this, argv.asList())
-    for (invocation in result.invocations) {
-        CommandLineParser.finalize(invocation)
-        invocation.command.runner()
-    }
-}
-
-fun <T> BaseCliktCommand<(T) -> T>.parse(initialValue: T, argv: Array<String>): T {
-    val result = CommandLineParser.parse(this, argv.asList())
-    var value = initialValue
-    for (invocation in result.invocations) {
-        CommandLineParser.finalize(invocation)
-        value = invocation.command.runner(value)
-    }
-    return value
-}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
index 93086370..dc53ba90 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
@@ -70,8 +70,8 @@ interface Argument {
 /** An argument that functions as a property delegate */
 interface ArgumentDelegate<out T> :
     Argument,
-    ReadOnlyProperty<CliktCommand, T>,
-    PropertyDelegateProvider<CliktCommand, ReadOnlyProperty<CliktCommand, T>> {
+    ReadOnlyProperty<BaseCliktCommand<*>, T>,
+    PropertyDelegateProvider<BaseCliktCommand<*>, ReadOnlyProperty<BaseCliktCommand<*>, T>> {
     /**
      * The value for this argument.
      *
@@ -79,7 +79,7 @@ interface ArgumentDelegate<out T> :
      */
     val value: T
 
-    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): T = value
+    override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): T = value
 }
 
 /** A receiver for argument transformers. */
@@ -185,10 +185,10 @@ class ProcessedArgumentImpl<AllT, ValueT> internal constructor(
         )
     }
 
-    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): AllT = value
+    override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): AllT = value
 
-    override operator fun provideDelegate(thisRef: CliktCommand, property: KProperty<*>):
-            ReadOnlyProperty<CliktCommand, AllT> {
+    override operator fun provideDelegate(thisRef: BaseCliktCommand<*>, property: KProperty<*>):
+            ReadOnlyProperty<BaseCliktCommand<*>, AllT> {
         if (name.isBlank()) name = property.name.uppercase().replace("-", "_")
         thisRef.registerArgument(this)
         return this
@@ -277,7 +277,7 @@ internal fun <T> defaultValidator(): ArgValidator<T> = {}
  * @param helpTags Extra information about this option to pass to the help formatter
  */
 @Suppress("UnusedReceiverParameter")
-fun CliktCommand.argument(
+fun BaseCliktCommand<*>.argument(
     name: String = "",
     help: String = "",
     helpTags: Map<String, String> = emptyMap(),
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
index 8de0b515..83d83723 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.parameters.groups
 
-import com.github.ajalt.clikt.core.BadParameterValue
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.core.MissingOption
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.internal.NullableLateinit
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.OptionDelegate
@@ -31,9 +28,9 @@ class ChoiceGroup<GroupT : OptionGroup, OutT> internal constructor(
     }
 
     override fun provideDelegate(
-        thisRef: CliktCommand,
+        thisRef: BaseCliktCommand<*>,
         property: KProperty<*>,
-    ): ReadOnlyProperty<CliktCommand, OutT> {
+    ): ReadOnlyProperty<BaseCliktCommand<*>, OutT> {
         option.provideDelegate(thisRef, property) // infer the option name and register it
         thisRef.registerOptionGroup(this)
         for ((_, group) in groups) {
@@ -46,7 +43,7 @@ class ChoiceGroup<GroupT : OptionGroup, OutT> internal constructor(
         return this
     }
 
-    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): OutT = value
+    override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): OutT = value
 
     override fun finalize(
         context: Context,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
index 5bdf0ae7..379eb43f 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
@@ -1,5 +1,6 @@
 package com.github.ajalt.clikt.parameters.groups
 
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.output.HelpFormatter
@@ -32,9 +33,9 @@ class CoOccurringOptionGroup<GroupT : OptionGroup, OutT> internal constructor(
     private var occurred = false
 
     override fun provideDelegate(
-        thisRef: CliktCommand,
+        thisRef: BaseCliktCommand<*>,
         property: KProperty<*>,
-    ): ReadOnlyProperty<CliktCommand, OutT> {
+    ): ReadOnlyProperty<BaseCliktCommand<*>, OutT> {
         thisRef.registerOptionGroup(this)
         for (option in group.options) {
 
@@ -45,7 +46,7 @@ class CoOccurringOptionGroup<GroupT : OptionGroup, OutT> internal constructor(
         return this
     }
 
-    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): OutT = value
+    override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): OutT = value
 
     override fun finalize(context: Context, invocationsByOption: Map<Option, List<Invocation>>) {
         occurred = invocationsByOption.isNotEmpty() || group.options.any {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
index dbe11179..e2f400b7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
@@ -25,9 +25,9 @@ class MutuallyExclusiveOptions<OptT : Any, OutT> internal constructor(
     private var value: OutT by NullableLateinit("Cannot read from group delegate before parsing command line")
 
     override operator fun provideDelegate(
-        thisRef: CliktCommand,
+        thisRef: BaseCliktCommand<*>,
         property: KProperty<*>,
-    ): ReadOnlyProperty<CliktCommand, OutT> {
+    ): ReadOnlyProperty<BaseCliktCommand<*>, OutT> {
         thisRef.registerOptionGroup(this)
 
         for (option in options) {
@@ -40,7 +40,7 @@ class MutuallyExclusiveOptions<OptT : Any, OutT> internal constructor(
         return this
     }
 
-    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): OutT = value
+    override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): OutT = value
 
     override fun finalize(
         context: Context,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
index d133ae3e..31232e0a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.parameters.groups
 
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.core.GroupableOption
-import com.github.ajalt.clikt.core.ParameterHolder
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.finalizeOptions
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.options.Option
@@ -49,13 +46,13 @@ interface ParameterGroup {
 /** A [ParameterGroup] that can be used as a property delegate */
 interface ParameterGroupDelegate<out T> :
     ParameterGroup,
-    ReadOnlyProperty<CliktCommand, T>,
-    PropertyDelegateProvider<CliktCommand, ReadOnlyProperty<CliktCommand, T>> {
-    /** Implementations must call [CliktCommand.registerOptionGroup] */
+    ReadOnlyProperty<BaseCliktCommand<*>, T>,
+    PropertyDelegateProvider<BaseCliktCommand<*>, ReadOnlyProperty<BaseCliktCommand<*>, T>> {
+    /** Implementations must call [BaseCliktCommand<*>.registerOptionGroup] */
     override operator fun provideDelegate(
-        thisRef: CliktCommand,
+        thisRef: BaseCliktCommand<*>,
         property: KProperty<*>,
-    ): ReadOnlyProperty<CliktCommand, T>
+    ): ReadOnlyProperty<BaseCliktCommand<*>, T>
 }
 
 /**
@@ -98,9 +95,9 @@ open class OptionGroup(
 }
 
 operator fun <T : OptionGroup> T.provideDelegate(
-    thisRef: CliktCommand,
+    thisRef: BaseCliktCommand<*>,
     prop: KProperty<*>,
-): ReadOnlyProperty<CliktCommand, T> {
+): ReadOnlyProperty<BaseCliktCommand<*>, T> {
     thisRef.registerOptionGroup(this)
     options.forEach { thisRef.registerOption(it) }
     return ReadOnlyProperty { _, _ -> this@provideDelegate }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
index 05761fa4..51ad3f18 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.parameters.options
 
-import com.github.ajalt.clikt.core.Abort
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.PrintMessage
-import com.github.ajalt.clikt.core.ProgramResult
+import com.github.ajalt.clikt.core.*
 
 
 /**
@@ -19,7 +16,7 @@ import com.github.ajalt.clikt.core.ProgramResult
  *   exception. If you want to exit normally without printing a message, you should throw
  *   [`Abort(error=false)`][Abort].
  */
-fun <T : CliktCommand> T.eagerOption(
+fun <T : BaseCliktCommand<*>> T.eagerOption(
     vararg names: String,
     help: String = "",
     hidden: Boolean = false,
@@ -41,7 +38,7 @@ fun <T : CliktCommand> T.eagerOption(
  *   exception. If you want to exit normally without printing a message, you should throw
  *   [`ProgramResult(0)`][ProgramResult].
  */
-fun <T : CliktCommand> T.eagerOption(
+fun <T : BaseCliktCommand<*>> T.eagerOption(
     names: Collection<String>,
     help: String = "",
     hidden: Boolean = false,
@@ -62,7 +59,7 @@ fun <T : CliktCommand> T.eagerOption(
 }
 
 /** Add an eager option to this command that, when invoked, prints a version message and exits. */
-inline fun <T : CliktCommand> T.versionOption(
+inline fun <T : BaseCliktCommand<*>> T.versionOption(
     /** The version to print */
     version: String,
     /** The help message for the option */
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
similarity index 84%
rename from clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
rename to clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 93a4ec1f..a427be42 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -1,12 +1,9 @@
-package com.github.ajalt.clikt.tmp
+package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.internal.finalizeParameters
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
-import com.github.ajalt.clikt.parsers.CommandInvocation
-import com.github.ajalt.clikt.parsers.CommandLineParseResult
-import com.github.ajalt.clikt.parsers.shlex
 
 // TODO: move this back to parsers package
 
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
deleted file mode 100644
index 3cd0494d..00000000
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
+++ /dev/null
@@ -1,565 +0,0 @@
-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.options.Option
-import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
-
-/** [i] is the argv index of the token that caused the error */
-private data class Err(val e: UsageError, val i: Int)
-
-private data class ArgsParseResult(
-    val excessCount: Int,
-    /** All arguments in the command and their parsed tokens (if any) */
-    val args: List<Pair<Argument, List<String>>>,
-    val err: Err?,
-)
-
-private data class OptInvocation(val opt: Option, val name: String, val values: List<String>) {
-    val inv get() = Invocation(name, values)
-}
-
-private data class OptParseResult(
-    val consumed: Int,
-    val unknown: List<String> = emptyList(),
-    val known: List<OptInvocation> = emptyList(),
-    val err: Err? = null,
-) {
-    constructor(consumed: Int, invocations: List<OptInvocation>) : this(
-        consumed,
-        emptyList(),
-        invocations
-    )
-
-    constructor(consumed: Int, opt: Option, name: String, values: List<String>)
-            : this(consumed, emptyList(), listOf(OptInvocation(opt, name, values)))
-}
-
-internal object Parser {
-    fun parse(argv: List<String>, context: Context) {
-        parse(argv, context, true)
-    }
-
-    private fun parse(
-        argv: List<String>,
-        context: Context,
-        canRun: Boolean,
-    ): List<String> {
-        var tokens = argv
-        val command = context.command
-        val aliases = command.aliases()
-        val subcommands = command._subcommands.associateBy { it.commandName }
-        val subcommandNames = subcommands.keys
-        val optionsByName = mutableMapOf<String, Option>()
-        val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
-        val arguments = command._arguments
-        val prefixes = mutableSetOf<String>()
-        val longNames = mutableSetOf<String>()
-        val hasMultipleSubAncestor = context.ancestors().any { it.command.allowMultipleSubcommands }
-        val positionalArgs = mutableListOf<Pair<Int, String>>()
-        var subcommand: CliktCommand? = null
-        var canParseOptions = true
-        var canExpandAtFiles = context.expandArgumentFiles
-        val invocations = mutableListOf<OptInvocation>()
-        val errors = mutableListOf<Err>()
-        var i = 0
-        var minAliasI = 0
-
-        for (option in command._options) {
-            require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
-                "options must have at least one name"
-            }
-
-            require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
-                "acceptsUnattachedValue must be true if the option accepts more than one value"
-            }
-
-            for (name in option.names + option.secondaryNames) {
-                optionsByName[name] = option
-                if (name.length > 2) longNames += name
-                prefixes += splitOptionPrefix(name).first
-            }
-        }
-        prefixes.remove("")
-
-        if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
-            throw PrintHelpMessage(context, error = true)
-        }
-
-        fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
-            if ("=" !in token) return false
-            if (prefix.isEmpty()) return false
-            if (prefix.length > 1) return true
-            if (context.tokenTransformer(
-                    context,
-                    token.substringBefore("=")
-                ) in longNames
-            ) return true
-            return context.tokenTransformer(context, token.take(2)) !in optionsByName
-        }
-
-        fun consumeParse(tokenIndex: Int, result: OptParseResult) {
-            positionalArgs += result.unknown.map { tokenIndex to it }
-            invocations += result.known
-            result.err?.let {
-                errors += it
-                context.errorEncountered = true
-            }
-            i += result.consumed
-        }
-
-        loop@ while (i <= tokens.lastIndex) {
-            val tok = tokens[i]
-            val normTok = context.tokenTransformer(context, tok)
-            val prefix = splitOptionPrefix(tok).first
-            when {
-                canExpandAtFiles
-                        && tok.startsWith("@")
-                        && normTok !in optionsByName -> {
-                    if (tok.startsWith("@@")) {
-                        positionalArgs += i to tok.drop(1)
-                        i += 1
-                    } else {
-                        val fileToks = loadArgFile(normTok.drop(1), context)
-                        tokens = fileToks + tokens.slice(i + 1..tokens.lastIndex)
-                        i = 0
-                        minAliasI = 0
-                    }
-                }
-
-                canParseOptions
-                        && tok == "--" -> {
-                    i += 1
-                    canParseOptions = false
-                    canExpandAtFiles = false
-                }
-
-                canParseOptions && (
-                        prefix.length > 1 && prefix in prefixes
-                                || normTok in longNames
-                                || isLongOptionWithEquals(prefix, tok)
-                                || !context.allowGroupedShortOptions
-                        ) -> {
-                    consumeParse(
-                        i,
-                        parseLongOpt(
-                            command.treatUnknownOptionsAsArgs,
-                            context,
-                            tokens,
-                            tok,
-                            i,
-                            optionsByName,
-                            subcommandNames
-                        )
-                    )
-                }
-
-                canParseOptions
-                        && tok.length >= 2
-                        && prefix.isNotEmpty()
-                        && prefix in prefixes -> {
-                    consumeParse(
-                        i,
-                        parseShortOpt(
-                            command.treatUnknownOptionsAsArgs,
-                            context,
-                            tokens,
-                            tok,
-                            i,
-                            optionsByName,
-                            numberOption,
-                            subcommandNames
-                        )
-                    )
-                }
-
-                i >= minAliasI && tok in aliases -> {
-                    tokens = aliases.getValue(tok) + tokens.slice(i + 1..tokens.lastIndex)
-                    i = 0
-                    minAliasI = aliases.getValue(tok).size
-                }
-
-                normTok in subcommands -> {
-                    subcommand = subcommands.getValue(normTok)
-                    i += 1
-                    break@loop
-                }
-
-                else -> {
-                    if (!context.allowInterspersedArgs) canParseOptions = false
-                    positionalArgs += i to tokens[i] // arguments aren't transformed
-                    i += 1
-                }
-            }
-        }
-
-        // Group options for finalization
-        val invocationsByOption = invocations.groupBy({ it.opt }, { it.inv })
-        val ungroupedOptions = command._options.filter {
-            !it.eager && (it as? GroupableOption)?.parameterGroup == null
-        }
-
-
-        // Finalize and validate everything as long as we aren't resuming a parse for multiple
-        // subcommands
-        try {
-            try {
-                if (canRun) {
-                    i = finalizeAndRun(
-                        context,
-                        i,
-                        command,
-                        subcommand,
-                        invocationsByOption,
-                        positionalArgs,
-                        arguments,
-                        hasMultipleSubAncestor,
-                        tokens,
-                        subcommands,
-                        errors,
-                        ungroupedOptions
-                    )
-                } 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) {
-                val nextTokens = parse(tokens.drop(i), subcommand.currentContext, true)
-                if (command.allowMultipleSubcommands && nextTokens.isNotEmpty()) {
-                    parse(nextTokens, context, false)
-                }
-                return nextTokens
-            }
-        } finally {
-            context.close()
-        }
-
-        return tokens.drop(i)
-    }
-
-    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>,
-    ): Int {
-        // Finalize and validate eager options
-        var nextArgvI = i
-
-        invocationsByOption.forEach { (o, inv) ->
-            if (o.eager) {
-                o.finalize(context, inv)
-                o.postValidate(context)
-            }
-        }
-
-        // Parse arguments
-        val argsParseResult = parseArguments(nextArgvI, positionalArgs, arguments)
-        argsParseResult.err?.let {
-            errors += it
-            context.errorEncountered = true
-        }
-
-        val excessResult = handleExcessArguments(
-            argsParseResult.excessCount,
-            hasMultipleSubAncestor,
-            nextArgvI,
-            tokens,
-            subcommands,
-            positionalArgs,
-            context
-        )
-        excessResult.second?.let {
-            errors += it
-            context.errorEncountered = true
-        }
-
-        val usageErrors = errors
-            .sortedBy { it.i }.mapTo(mutableListOf()) { it.e }
-
-        nextArgvI = excessResult.first
-
-        // Finalize arguments, groups, and options
-        gatherErrors(usageErrors, context) {
-            finalizeParameters(
-                context,
-                ungroupedOptions,
-                command._groups,
-                invocationsByOption,
-                argsParseResult.args.map { (a, v) -> ArgumentInvocation(a, v) },
-            )
-        }
-
-        // 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) }
-        }
-
-        MultiUsageError.buildOrNull(usageErrors)?.let { throw it }
-
-        if (subcommand == null && subcommands.isNotEmpty() && !command.invokeWithoutSubcommand) {
-            throw PrintHelpMessage(context, error = true)
-        }
-
-        command.currentContext.invokedSubcommand = subcommand
-        if (command.currentContext.printExtraMessages) {
-            for (warning in command.messages) {
-                command.terminal.warning(warning, stderr = true)
-            }
-        }
-
-        command.run()
-        return nextArgvI
-    }
-
-    /** Returns either the new argv index, or an error */
-    private fun handleExcessArguments(
-        excess: Int,
-        hasMultipleSubAncestor: Boolean,
-        i: Int,
-        tokens: List<String>,
-        subcommands: Map<String, CliktCommand>,
-        positionalArgs: List<Pair<Int, String>>,
-        context: Context,
-    ): Pair<Int, Err?> {
-        if (excess > 0) {
-            return when {
-                hasMultipleSubAncestor -> tokens.size - excess to null
-                excess == 1 && subcommands.isNotEmpty() -> {
-                    val actual = positionalArgs.last().second
-                    throw NoSuchSubcommand(
-                        actual, context.correctionSuggestor(actual, subcommands.keys.toList())
-                    )
-                }
-
-                else -> -1 to Err(excessArgsError(positionalArgs, excess, context), i)
-            }
-        }
-        return i to null
-    }
-
-    private fun parseLongOpt(
-        ignoreUnknown: Boolean,
-        context: Context,
-        tokens: List<String>,
-        tok: String,
-        index: Int,
-        optionsByName: Map<String, Option>,
-        subcommandNames: Set<String>,
-    ): OptParseResult {
-        val equalsIndex = tok.indexOf('=')
-        var (name, attachedValue) = if (equalsIndex >= 0) {
-            tok.substring(0, equalsIndex) to tok.substring(equalsIndex + 1)
-        } else {
-            tok to null
-        }
-        name = context.tokenTransformer(context, name)
-        val option = optionsByName[name] ?: if (ignoreUnknown) {
-            return OptParseResult(1, listOf(tok))
-        } else {
-            val possibilities = context.correctionSuggestor(
-                name,
-                optionsByName.filterNot { it.value.hidden }.keys.toList()
-            )
-            return OptParseResult(1, err = Err(NoSuchOption(name, possibilities), index))
-        }
-
-        return parseOptValues(
-            option,
-            name,
-            ignoreUnknown,
-            tokens,
-            index,
-            attachedValue,
-            optionsByName,
-            subcommandNames
-        )
-    }
-
-    private fun parseOptValues(
-        option: Option,
-        name: String,
-        ignoreUnknown: Boolean,
-        tokens: List<String>,
-        index: Int,
-        attachedValue: String?,
-        optionsByName: Map<String, Option>,
-        subcommandNames: Set<String>,
-    ): OptParseResult {
-        val values = mutableListOf<String>()
-        if (attachedValue != null) {
-            values += attachedValue
-        } else if (!option.acceptsUnattachedValue) {
-            return OptParseResult(1, option, name, emptyList())
-        }
-
-        for (i in (index + 1)..tokens.lastIndex) {
-            val tok = tokens[i]
-            if (values.size >= option.nvalues.last) break
-            if (values.size >= option.nvalues.first && (tok == "--"
-                        || tok in optionsByName
-                        || tok in subcommandNames
-                        || !ignoreUnknown && splitOptionPrefix(tok).first.isNotEmpty())
-            ) {
-                break
-            }
-
-            values += tok
-        }
-
-        val consumed = values.size + if (attachedValue == null) 1 else 0
-        if (values.size !in option.nvalues) {
-            return OptParseResult(
-                consumed,
-                err = Err(IncorrectOptionValueCount(option, name), index)
-            )
-        }
-
-        return OptParseResult(consumed, option, name, values)
-    }
-
-    private fun parseShortOpt(
-        ignoreUnknown: Boolean,
-        context: Context,
-        tokens: List<String>,
-        tok: String,
-        index: Int,
-        optionsByName: Map<String, Option>,
-        numberOption: Option?,
-        subcommandNames: Set<String>,
-    ): OptParseResult {
-        val prefix = tok[0].toString()
-
-        if (numberOption != null && tok.drop(1).all { it.isDigit() }) {
-            return OptParseResult(1, numberOption, "", listOf(tok.drop(1)))
-        }
-
-        val invocations = mutableListOf<OptInvocation>()
-
-        for ((i, opt) in tok.withIndex()) {
-            if (i == 0) continue // skip the dash
-
-            val name = context.tokenTransformer(context, prefix + opt)
-            val option = optionsByName[name] ?: if (ignoreUnknown) {
-                return OptParseResult(1, unknown = listOf(tok))
-            } else {
-                val possibilities = when {
-                    prefix == "-" && "-$tok" in optionsByName -> listOf("-$tok")
-                    else -> emptyList()
-                }
-                return OptParseResult(1, err = Err(NoSuchOption(name, possibilities), index))
-            }
-            if (option.nvalues.last > 0) {
-                val value = if (i < tok.lastIndex) tok.drop(i + 1) else null
-                val result = parseOptValues(
-                    option,
-                    name,
-                    ignoreUnknown,
-                    tokens,
-                    index,
-                    value,
-                    optionsByName,
-                    subcommandNames
-                )
-                return result.copy(known = invocations + result.known)
-            } else {
-                invocations += OptInvocation(option, name, emptyList())
-            }
-        }
-        return OptParseResult(1, invocations)
-    }
-
-    private fun parseArguments(
-        argvIndex: Int,
-        /** Parsed argument tokens and their index in argv */
-        positionalArgs: List<Pair<Int, String>>,
-        arguments: List<Argument>,
-    ): ArgsParseResult {
-        val out = linkedMapOf<Argument, List<String>>().withDefault { listOf() }
-        // The number of fixed size arguments that occur after an unlimited size argument. This
-        // includes optional single value args, so it might be bigger than the number of provided
-        // values.
-        val endSize = arguments.asReversed()
-            .takeWhile { it.nvalues > 0 }
-            .sumOf { it.nvalues }
-
-        var i = 0
-        for (argument in arguments) {
-            val remaining = positionalArgs.size - i
-            val consumed = when {
-                argument.nvalues <= 0 -> maxOf(if (argument.required) 1 else 0, remaining - endSize)
-                argument.nvalues > 0 && !argument.required && remaining == 0 -> 0
-                else -> argument.nvalues
-            }
-
-            if (consumed > remaining) {
-                val e = when (remaining) {
-                    0 -> MissingArgument(argument)
-                    else -> IncorrectArgumentValueCount(argument)
-                }
-                return ArgsParseResult(
-                    0,
-                    out.toList(),
-                    Err(e, positionalArgs.getOrNull(i)?.first ?: argvIndex)
-                )
-            }
-            out[argument] = out.getValue(argument) +
-                    positionalArgs.subList(i, i + consumed).map { it.second }
-            i += consumed
-        }
-
-        val excess = positionalArgs.size - i
-        return ArgsParseResult(excess, out.toList(), null)
-    }
-
-    private fun loadArgFile(filename: String, context: Context): List<String> {
-        return shlex(filename, context.argumentFileReader!!(filename), context.localization)
-    }
-
-    private fun excessArgsError(
-        positionalArgs: List<Pair<Int, String>>,
-        excess: Int,
-        context: Context,
-    ): UsageError {
-        val actual = positionalArgs.takeLast(excess).map { it.second }
-        return NoSuchArgument(actual).also { it.context = context }
-    }
-}
-
-private inline fun gatherErrors(
-    errors: MutableList<UsageError>,
-    context: Context,
-    block: () -> Unit,
-) {
-    try {
-        block()
-    } catch (e: UsageError) {
-        errors += e
-        context.errorEncountered = true
-    }
-}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
similarity index 99%
rename from clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
rename to clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index aae20295..f57b83a2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/tmp/NewParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -1,10 +1,9 @@
-package com.github.ajalt.clikt.tmp
+package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
-import com.github.ajalt.clikt.parsers.*
 
 internal fun <RunnerT : Function<*>> parseArgv(
     command: BaseCliktCommand<RunnerT>,
@@ -17,7 +16,7 @@ internal fun <RunnerT : Function<*>> parseArgv(
     do {
         val parent = results.lastOrNull()?.command?.currentContext
         val commandResult = parseCommand(command, parent, expandedArgv, i)
-        check(commandResult.i in expandedArgv.indices) {
+        check(i in expandedArgv.indices) {
             "Internal error: index $i out of bounds ${expandedArgv.indices}"
         }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
index 836fafb5..d0098f2a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
@@ -3,7 +3,9 @@ package com.github.ajalt.clikt.testing
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.parse
 import com.github.ajalt.clikt.mpp.readEnvvar
+import com.github.ajalt.clikt.parsers.CommandLineParser
 import com.github.ajalt.clikt.parsers.shlex
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
@@ -49,7 +51,7 @@ fun CliktCommand.test(
     width: Int = 79,
     height: Int = 24,
 ): CliktCommandTestResult {
-    val argvArray = shlex("test", argv, null)
+    val argvArray = CommandLineParser.tokenize(argv)
     return test(argvArray, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
 }
 
@@ -104,8 +106,9 @@ fun CliktCommand.test(
     ansiLevel: AnsiLevel = AnsiLevel.NONE,
     width: Int = 79,
     height: Int = 24,
-): CliktCommandTestResult =
-    test(argv.toTypedArray(), stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+): CliktCommandTestResult {
+    return test(argv.toTypedArray(), stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+}
 
 /**
  * Test this command, returning a result that captures the output and result status code.
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
index 2af5aab6..1bc28c08 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
@@ -63,6 +63,7 @@ class MordantHelpFormatterTest {
                 is Argument -> c.registerArgument(p)
                 is Option -> c.registerOption(p)
                 is CliktCommand -> c.subcommands(p)
+                else -> error("Unknown param type: $p")
             }
         }
         c.getFormattedHelp()?.lines()?.first() shouldBe expected
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index 0d766412..e06687ec 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -1,7 +1,9 @@
 package com.github.ajalt.clikt.testing
 
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.parse
 import com.github.ajalt.clikt.parsers.shlex
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
@@ -50,7 +52,7 @@ open class TestCommand(
     open fun run_() = Unit
 
     companion object {
-        fun assertCalled(cmd: CliktCommand) {
+        fun assertCalled(cmd: BaseCliktCommand<*>) {
             if (cmd is TestCommand) {
                 if (cmd.count != null) {
                     assertEquals(cmd.count, cmd.actualCount, "command call count")
diff --git a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
index 6edb71cb..c2ef8c93 100644
--- a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
+++ b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
@@ -2,6 +2,7 @@ package com.github.ajalt.clikt.samples.aliases
 
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.NoOpCliktCommand
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.options.multiple
 import com.github.ajalt.clikt.parameters.options.option
diff --git a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
index 631de656..13a235cf 100644
--- a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
+++ b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.copy
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.terminal
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
diff --git a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
index ab618f6d..1b747707 100644
--- a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
+++ b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
@@ -3,6 +3,7 @@ package com.github.ajalt.clikt.samples.helpformat
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.output.MordantHelpFormatter
 import com.github.ajalt.clikt.parameters.arguments.argument
diff --git a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
index 1f928c81..f70ccc95 100644
--- a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
+++ b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
@@ -2,6 +2,7 @@ package com.github.ajalt.clikt.samples.json
 
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.multiple
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
index b4cba017..007432e3 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.options.*
 import org.kodein.di.Kodein
diff --git a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
index 165fb3f7..2ea4e3b7 100644
--- a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
+++ b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.repo
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.requireObject
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.output.TermUi
diff --git a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
index a63123d4..f2f6a2ec 100644
--- a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
+++ b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.validation
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.convert
 import com.github.ajalt.clikt.parameters.options.*

From b3f4759fc9c4226071ed9bef585640b0b3c43c35 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 31 Mar 2024 10:01:52 -0700
Subject: [PATCH 06/43] Finalize and execute in parse

---
 .../github/ajalt/clikt/core/CliktCommand.kt   |  8 ++-
 .../com/github/ajalt/clikt/core/Context.kt    |  3 +
 .../ajalt/clikt/internal/Finalization.kt      | 42 +++++++++++++-
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 12 +++-
 .../github/ajalt/clikt/parsers/Invocation.kt  | 12 ++++
 .../ajalt/clikt/parsers/ParserInternals.kt    | 56 ++++++++++---------
 .../ajalt/clikt/parameters/OptionTest.kt      |  8 ++-
 .../github/ajalt/clikt/testing/TestCommand.kt | 15 ++---
 8 files changed, 111 insertions(+), 45 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 50c6740b..1fee436d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -4,6 +4,7 @@ import com.github.ajalt.clikt.mpp.exitProcessMpp
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parsers.CommandLineParser
+import com.github.ajalt.clikt.parsers.throwErrors
 
 /**
  * The [CliktCommand] is the core of command line interfaces in Clikt.
@@ -96,5 +97,10 @@ fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
  */
 fun BaseCliktCommand<() -> Unit>.parse(argv: List<String>) {
 // TODO   generateCompletion()
-    CommandLineParser.parse(this, argv)
+    val result = CommandLineParser.parse(this, argv)
+    result.throwErrors()
+    for (invocation in result.invocations) {
+        CommandLineParser.finalize(invocation)
+        invocation.command.runner()
+    }
 }
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 05e725e8..cf4b9cd9 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
@@ -212,6 +212,9 @@ class Context private constructor(
      */
     val expandArgumentFiles: Boolean get() = argumentFileReader != null
 
+    override fun toString(): String {
+        return "Context(command=${command.commandName}, parent=${parent?.command?.commandName})"
+    }
 
     class Builder(command: BaseCliktCommand<*>, val parent: Context? = null) {
         /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index dc6b6f87..05ae88cd 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -12,9 +12,10 @@ internal fun finalizeOptions(
     options: List<Option>,
     invocationsByOption: Map<Option, List<Invocation>>,
 ) {
-    finalizeParameters(
+    val errors = finalizeParameters(
         context, options, emptyList(), invocationsByOption, emptyList()
     )
+    MultiUsageError.buildOrNull(errors)?.let { throw it }
 }
 
 private sealed class Param
@@ -28,7 +29,7 @@ internal fun finalizeParameters(
     groups: List<ParameterGroup>,
     optionInvocations: Map<Option, List<Invocation>>,
     argumentInvocations: List<ArgumentInvocation>,
-) {
+): List<UsageError> {
     val allGroups = optionInvocations.entries
         .groupBy({ it.key.group }, { it.key to it.value })
         .mapValuesTo(mutableMapOf()) { it.value.toMap() }
@@ -65,6 +66,7 @@ internal fun finalizeParameters(
             } catch (e: IllegalStateException) {
                 nextRound += it
             } catch (e: UsageError) {
+                e.context = e.context ?: context
                 errors += e
                 context.errorEncountered = true
             } catch (e: Abort) {
@@ -77,7 +79,41 @@ internal fun finalizeParameters(
         nextRound.clear()
     }
 
-    MultiUsageError.buildOrNull(errors)?.let { throw it }
+    return errors
+}
+
+internal fun validateParameters(
+    context: Context,
+    optionInvocations: Map<Option, List<Invocation>>,
+): List<UsageError> {
+    val usageErrors = mutableListOf<UsageError>()
+    optionInvocations.keys.filter { it.group == null }.forEach {
+        gatherErrors(usageErrors, context) { it.postValidate(context) }
+    }
+    context.command.registeredParameterGroups().forEach {
+        gatherErrors(usageErrors, context) { it.postValidate(context) }
+    }
+    context.command.registeredArguments().forEach {
+        gatherErrors(
+            usageErrors,
+            context
+        ) { it.postValidate(context) }
+    }
+    return usageErrors
+}
+
+private inline fun gatherErrors(
+    errors: MutableList<UsageError>,
+    context: Context,
+    block: () -> Unit,
+) {
+    try {
+        block()
+    } catch (e: UsageError) {
+        e.context = e.context ?: context
+        errors += e
+        context.errorEncountered = true
+    }
 }
 
 private val Option.group: ParameterGroup? get() = (this as? GroupableOption)?.parameterGroup
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index a427be42..ba0f05d7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -1,7 +1,9 @@
 package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.MultiUsageError
 import com.github.ajalt.clikt.internal.finalizeParameters
+import com.github.ajalt.clikt.internal.validateParameters
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
@@ -24,12 +26,20 @@ object CommandLineParser {
     }
 
     fun finalize(invocation: CommandInvocation<*>) {
-        finalizeParameters(
+        val usageErrors = finalizeParameters(
             invocation.command.currentContext,
             invocation.command.registeredOptions(),
             invocation.command.registeredParameterGroups(),
             invocation.optionInvocations,
             invocation.argumentInvocations,
         )
+
+        // Now that all parameters have been finalized, we can validate everything
+        val validationErrors = validateParameters(
+            invocation.command.currentContext,
+            invocation.optionInvocations
+        )
+
+        MultiUsageError.buildOrNull(usageErrors + validationErrors)?.let { throw it }
     }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 65ee7082..503b0cb4 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -2,6 +2,8 @@ package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktError
+import com.github.ajalt.clikt.core.MultiUsageError
+import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 
@@ -30,3 +32,13 @@ class CommandLineParseResult<RunnerT : Function<*>>(
     val expandedArgv: List<String>,
     val errors: List<CliktError>,
 )
+
+fun CommandLineParseResult<*>.throwErrors() {
+    when (val first = errors.firstOrNull()) {
+        is UsageError -> MultiUsageError.buildOrNull(
+            errors.takeWhile { it is UsageError }.filterIsInstance<UsageError>()
+        )?.let { throw it }
+
+        is CliktError -> throw first
+    }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index f57b83a2..469e8bf4 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -11,18 +11,20 @@ internal fun <RunnerT : Function<*>> parseArgv(
 ): CommandLineParseResult<RunnerT> {
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
+    var nextCommand: BaseCliktCommand<RunnerT>? = command
     val errors = mutableListOf<CliktError>()
     var i = 0
-    do {
+    while (nextCommand != null) {
         val parent = results.lastOrNull()?.command?.currentContext
-        val commandResult = parseCommand(command, parent, expandedArgv, i)
-        check(i in expandedArgv.indices) {
+        val commandResult = parseCommand(nextCommand, parent, expandedArgv, i)
+        check(expandedArgv.isEmpty() || i in expandedArgv.indices) {
             "Internal error: index $i out of bounds ${expandedArgv.indices}"
         }
 
         i = commandResult.i
         errors += commandResult.errors
         expandedArgv = commandResult.expandedArgv
+        nextCommand = commandResult.subcommand
         if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
 
         val argResult = parseArguments(commandResult.argumentTokens, command._arguments)
@@ -33,9 +35,9 @@ internal fun <RunnerT : Function<*>> parseArgv(
             (e as? UsageError)?.let { it.context = it.context ?: command.currentContext }
         }
         results += CommandInvocation(command, commandResult.optInvocations, argResult.invocations)
-    } while (commandResult.subcommand != null)
+    }
     val lastInvocation = results.lastOrNull()
-    if (lastInvocation != null && i != expandedArgv.lastIndex) {
+    if (lastInvocation != null && i != expandedArgv.size) {
         errors += NoSuchArgument(expandedArgv.drop(i + 1)).also {
             it.context = command.currentContext
         }
@@ -72,28 +74,6 @@ private fun <RunnerT : Function<*>> parseCommand(
         return CommandParseResult(subcommand, i, errors, tokens, opts, argumentTokens)
     }
 
-    for (option in command._options) {
-        require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
-            "options must have at least one name"
-        }
-
-        require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
-            "acceptsUnattachedValue must be true if the option accepts more than one value"
-        }
-
-        for (name in option.names + option.secondaryNames) {
-            optionsByName[name] = option
-            if (name.length > 2) longNames += name
-            prefixes += splitOptionPrefix(name).first
-        }
-    }
-    prefixes.remove("")
-
-    if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
-        errors += PrintHelpMessage(context, error = true)
-        return makeResult()
-    }
-
     fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
         if ("=" !in token) return false
         if (prefix.isEmpty()) return false
@@ -125,6 +105,28 @@ private fun <RunnerT : Function<*>> parseCommand(
         minAliasI = i + newTokens.size
     }
 
+    for (option in command._options) {
+        require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
+            "options must have at least one name"
+        }
+
+        require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
+            "acceptsUnattachedValue must be true if the option accepts more than one value"
+        }
+
+        for (name in option.names + option.secondaryNames) {
+            optionsByName[name] = option
+            if (name.length > 2) longNames += name
+            prefixes += splitOptionPrefix(name).first
+        }
+    }
+    prefixes.remove("")
+
+    if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
+        errors += PrintHelpMessage(context, error = true)
+        return makeResult()
+    }
+
     loop@ while (i <= tokens.lastIndex) {
         val tok = tokens[i]
         val normTok = context.tokenTransformer(context, tok)
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
index 27d3514f..1c1645bf 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/OptionTest.kt
@@ -332,8 +332,12 @@ class OptionTest {
     fun `flag convert validate`() {
         class C : TestCommand() {
             val x by option().flag("--no-x")
-                .convert { if (it) E.A else E.B }
-                .validate { require(it == E.A) }
+                .convert {
+                    if (it) E.A else E.B
+                }
+                .validate {
+                    require(it == E.A)
+                }
         }
 
         C().parse("--x").x shouldBe E.A
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index e06687ec..2d5a634f 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -7,13 +7,11 @@ import com.github.ajalt.clikt.core.parse
 import com.github.ajalt.clikt.parsers.shlex
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
-import io.kotest.matchers.shouldBe
 import kotlin.test.assertEquals
-import kotlin.test.fail
 
 open class TestCommand(
-    private val called: Boolean = true,
-    private val count: Int? = null,
+    called: Boolean = true,
+    count: Int? = null,
     help: String = "",
     epilog: String = "",
     name: String? = null,
@@ -42,9 +40,9 @@ open class TestCommand(
         }
     }
 
+    private val count = count ?: if (called) 1 else 0
     private var actualCount = 0
     final override fun run() {
-        if (count == null) actualCount shouldBe 0
         actualCount++
         run_()
     }
@@ -54,12 +52,7 @@ open class TestCommand(
     companion object {
         fun assertCalled(cmd: BaseCliktCommand<*>) {
             if (cmd is TestCommand) {
-                if (cmd.count != null) {
-                    assertEquals(cmd.count, cmd.actualCount, "command call count")
-                } else {
-                    if (cmd.called && cmd.actualCount == 0) fail("${cmd.commandName} should have been called")
-                    if (!cmd.called && cmd.actualCount > 0) fail("${cmd.commandName} should not be called")
-                }
+                assertEquals(cmd.count, cmd.actualCount, "${cmd.commandName} call count")
             }
             for (sub in cmd.registeredSubcommands()) {
                 assertCalled(sub)

From cd3a24c849896f03b043634c15b7d91b99f68057 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 31 Mar 2024 10:34:03 -0700
Subject: [PATCH 07/43] Move command parser into a class

---
 .../ajalt/clikt/parsers/ParserInternals.kt    | 481 ++++++++----------
 1 file changed, 211 insertions(+), 270 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 469e8bf4..f8438f77 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -16,7 +16,7 @@ internal fun <RunnerT : Function<*>> parseArgv(
     var i = 0
     while (nextCommand != null) {
         val parent = results.lastOrNull()?.command?.currentContext
-        val commandResult = parseCommand(nextCommand, parent, expandedArgv, i)
+        val commandResult = CommandParser(nextCommand, parent, expandedArgv, i).parse()
         check(expandedArgv.isEmpty() || i in expandedArgv.indices) {
             "Internal error: index $i out of bounds ${expandedArgv.indices}"
         }
@@ -45,36 +45,119 @@ internal fun <RunnerT : Function<*>> parseArgv(
     return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
 }
 
-private fun <RunnerT : Function<*>> parseCommand(
-    command: BaseCliktCommand<RunnerT>,
+private class CommandParser<RunnerT : Function<*>>(
+    private val command: BaseCliktCommand<RunnerT>,
     parentContext: Context?,
     argv: List<String>,
     startingIndex: Int,
-): CommandParseResult<RunnerT> {
-    var tokens = argv
-    val context = command.resetContext(parentContext)
-    val aliases = command.aliases()
-    val subcommands = command._subcommands.associateBy { it.commandName }
-    val subcommandNames = subcommands.keys
-    val optionsByName = mutableMapOf<String, Option>()
-    val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
-    val prefixes = mutableSetOf<String>()
-    val longNames = mutableSetOf<String>()
-    val argumentTokens = mutableListOf<String>()
-    var subcommand: BaseCliktCommand<RunnerT>? = null
-    var canParseOptions = true
-    var canExpandAtFiles = context.expandArgumentFiles
-    val optInvocations = mutableListOf<OptInvocation>()
-    val errors = mutableListOf<CliktError>()
-    var i = startingIndex
-    var minAliasI = i
+) {
+    private var tokens = argv
+    private val context = command.resetContext(parentContext)
+    private val aliases = command.aliases()
+    private val subcommands = command._subcommands.associateBy { it.commandName }
+    private val subcommandNames = subcommands.keys
+    private val optionsByName = mutableMapOf<String, Option>()
+    private val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
+    private val prefixes = mutableSetOf<String>()
+    private val longNames = mutableSetOf<String>()
+    private val argumentTokens = mutableListOf<String>()
+    private var subcommand: BaseCliktCommand<RunnerT>? = null
+    private var canParseOptions = true
+    private var canExpandAtFiles = context.expandArgumentFiles
+    private val optInvocations = mutableListOf<OptInvocation>()
+    private val errors = mutableListOf<CliktError>()
+    private var i = startingIndex
+    private var minAliasI = i
+
+    fun parse(): CommandParseResult<RunnerT> {
+        for (option in command._options) {
+            require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
+                "options must have at least one name"
+            }
+
+            require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
+                "acceptsUnattachedValue must be true if the option accepts more than one value"
+            }
+
+            for (name in option.names + option.secondaryNames) {
+                optionsByName[name] = option
+                if (name.length > 2) longNames += name
+                prefixes += splitOptionPrefix(name).first
+            }
+        }
+        prefixes.remove("")
+
+        if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
+            errors += PrintHelpMessage(context, error = true)
+            return makeResult()
+        }
+
+        loop@ while (i <= tokens.lastIndex) {
+            val tok = tokens[i]
+            val normTok = context.tokenTransformer(context, tok)
+            val prefix = splitOptionPrefix(tok).first
+            when {
+                canExpandAtFiles
+                        && tok.startsWith("@")
+                        && normTok !in optionsByName -> {
+                    if (tok.startsWith("@@")) {
+                        argumentTokens += tok.drop(1)
+                        i += 1
+                    } else {
+                        insertTokens(loadArgFile(normTok.drop(1), context))
+                    }
+                }
+
+                canParseOptions
+                        && tok == "--" -> {
+                    i += 1
+                    canParseOptions = false
+                    canExpandAtFiles = false
+                }
+
+                canParseOptions && (
+                        prefix.length > 1 && prefix in prefixes
+                                || normTok in longNames
+                                || isLongOptionWithEquals(prefix, tok)
+                                || !context.allowGroupedShortOptions
+                        ) -> {
+                    consumeOptionParse(parseLongOpt(tok))
+                }
+
+                canParseOptions
+                        && tok.length >= 2
+                        && prefix.isNotEmpty()
+                        && prefix in prefixes -> {
+                    consumeOptionParse(parseShortOpt(tok))
+                }
 
-    fun makeResult(): CommandParseResult<RunnerT> {
+                i >= minAliasI && tok in aliases -> {
+                    insertTokens(aliases.getValue(tok))
+                }
+
+                normTok in subcommands -> {
+                    subcommand = subcommands.getValue(normTok)
+                    i += 1
+                    break@loop
+                }
+
+                else -> {
+                    if (!context.allowInterspersedArgs) canParseOptions = false
+                    argumentTokens += tok // arguments aren't transformed
+                    i += 1
+                }
+            }
+        }
+
+        return makeResult()
+    }
+
+    private fun makeResult(): CommandParseResult<RunnerT> {
         val opts = optInvocations.groupBy({ it.opt }, { it.inv })
         return CommandParseResult(subcommand, i, errors, tokens, opts, argumentTokens)
     }
 
-    fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
+    private fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
         if ("=" !in token) return false
         if (prefix.isEmpty()) return false
         if (prefix.length > 1) return true
@@ -86,7 +169,7 @@ private fun <RunnerT : Function<*>> parseCommand(
         return context.tokenTransformer(context, token.take(2)) !in optionsByName
     }
 
-    fun consumeOptionParse(result: OptParseResult) {
+    private fun consumeOptionParse(result: OptParseResult) {
         argumentTokens += result.unknown
         optInvocations += result.known
         result.err?.let {
@@ -96,7 +179,7 @@ private fun <RunnerT : Function<*>> parseCommand(
         i += result.consumed
     }
 
-    fun insertTokens(newTokens: List<String>) {
+    private fun insertTokens(newTokens: List<String>) {
         tokens = buildList(tokens.size + newTokens.size) {
             addAll(tokens.take(i))
             addAll(newTokens)
@@ -105,275 +188,99 @@ private fun <RunnerT : Function<*>> parseCommand(
         minAliasI = i + newTokens.size
     }
 
-    for (option in command._options) {
-        require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
-            "options must have at least one name"
-        }
-
-        require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
-            "acceptsUnattachedValue must be true if the option accepts more than one value"
+    private fun parseLongOpt(tok: String): OptParseResult {
+        val equalsIndex = tok.indexOf('=')
+        var (name, attachedValue) = if (equalsIndex >= 0) {
+            tok.substring(0, equalsIndex) to tok.substring(equalsIndex + 1)
+        } else {
+            tok to null
         }
-
-        for (name in option.names + option.secondaryNames) {
-            optionsByName[name] = option
-            if (name.length > 2) longNames += name
-            prefixes += splitOptionPrefix(name).first
+        name = context.tokenTransformer(context, name)
+        val option = optionsByName[name] ?: if (command.treatUnknownOptionsAsArgs) {
+            return OptParseResult(1, listOf(tok))
+        } else {
+            val possibilities = context.correctionSuggestor(
+                name,
+                optionsByName.filterNot { it.value.hidden }.keys.toList()
+            )
+            return OptParseResult(1, err = NoSuchOption(name, possibilities))
         }
-    }
-    prefixes.remove("")
 
-    if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
-        errors += PrintHelpMessage(context, error = true)
-        return makeResult()
+        return parseOptValues(option, name, attachedValue)
     }
 
-    loop@ while (i <= tokens.lastIndex) {
-        val tok = tokens[i]
-        val normTok = context.tokenTransformer(context, tok)
-        val prefix = splitOptionPrefix(tok).first
-        when {
-            canExpandAtFiles
-                    && tok.startsWith("@")
-                    && normTok !in optionsByName -> {
-                if (tok.startsWith("@@")) {
-                    argumentTokens += tok.drop(1)
-                    i += 1
-                } else {
-                    insertTokens(loadArgFile(normTok.drop(1), context))
-                }
-            }
-
-            canParseOptions
-                    && tok == "--" -> {
-                i += 1
-                canParseOptions = false
-                canExpandAtFiles = false
-            }
+    private fun parseShortOpt(tok: String): OptParseResult {
+        val prefix = tok[0].toString()
 
-            canParseOptions && (
-                    prefix.length > 1 && prefix in prefixes
-                            || normTok in longNames
-                            || isLongOptionWithEquals(prefix, tok)
-                            || !context.allowGroupedShortOptions
-                    ) -> {
-                consumeOptionParse(
-                    parseLongOpt(
-                        command.treatUnknownOptionsAsArgs,
-                        context,
-                        tokens,
-                        tok,
-                        i,
-                        optionsByName,
-                        subcommandNames
-                    )
-                )
-            }
+        if (numberOption != null && tok.drop(1).all { it.isDigit() }) {
+            return OptParseResult(1, numberOption, "", listOf(tok.drop(1)))
+        }
 
-            canParseOptions
-                    && tok.length >= 2
-                    && prefix.isNotEmpty()
-                    && prefix in prefixes -> {
-                consumeOptionParse(
-                    parseShortOpt(
-                        command.treatUnknownOptionsAsArgs,
-                        context,
-                        tokens,
-                        tok,
-                        i,
-                        optionsByName,
-                        numberOption,
-                        subcommandNames
-                    )
-                )
-            }
+        val invocations = mutableListOf<OptInvocation>()
 
-            i >= minAliasI && tok in aliases -> {
-                insertTokens(aliases.getValue(tok))
-            }
+        for ((i, opt) in tok.withIndex()) {
+            if (i == 0) continue // skip the dash
 
-            normTok in subcommands -> {
-                subcommand = subcommands.getValue(normTok)
-                i += 1
-                break@loop
+            val name = context.tokenTransformer(context, prefix + opt)
+            val option = optionsByName[name] ?: if (command.treatUnknownOptionsAsArgs) {
+                return OptParseResult(1, unknown = listOf(tok))
+            } else {
+                val possibilities = when {
+                    prefix == "-" && "-$tok" in optionsByName -> listOf("-$tok")
+                    else -> emptyList()
+                }
+                return OptParseResult(1, err = NoSuchOption(name, possibilities))
             }
-
-            else -> {
-                if (!context.allowInterspersedArgs) canParseOptions = false
-                argumentTokens += tok // arguments aren't transformed
-                i += 1
+            if (option.nvalues.last > 0) {
+                val value = if (i < tok.lastIndex) tok.drop(i + 1) else null
+                val result = parseOptValues(option, name, value)
+                return result.copy(known = invocations + result.known)
+            } else {
+                invocations += OptInvocation(option, name, emptyList())
             }
         }
+        return OptParseResult(1, invocations)
     }
 
-    return makeResult()
-}
-
-/** Returns the new argv index and any errors */
-private fun <RunnerT : Function<*>> handleExcessArgs(
-    argResult: ArgsParseResult,
-    command: BaseCliktCommand<RunnerT>,
-    i: Int,
-    expandedArgv: List<String>,
-    commandResult: CommandParseResult<RunnerT>,
-): Pair<Int, List<CliktError>> {
-    if (argResult.excessCount <= 0) return i to emptyList()
-    val hasMultipleSubAncestor = command.currentContext.ancestors().any {
-        it.command.allowMultipleSubcommands
-    }
-    if (hasMultipleSubAncestor) {
-        return expandedArgv.size - argResult.excessCount to emptyList()
-    } else {
-        val subcommandNames = command._subcommands.map { it.commandName }
-        val error = when {
-            argResult.excessCount == 1 && subcommandNames.isNotEmpty() -> {
-                val actual = commandResult.argumentTokens.last()
-                val possibilities = command.currentContext.correctionSuggestor(
-                    actual, subcommandNames
-                )
-                NoSuchSubcommand(actual, possibilities)
-            }
-
-            else -> {
-                NoSuchArgument(commandResult.argumentTokens.takeLast(argResult.excessCount))
-            }
+    private fun parseOptValues(
+        option: Option,
+        name: String,
+        attachedValue: String?,
+    ): OptParseResult {
+        val values = mutableListOf<String>()
+        if (attachedValue != null) {
+            values += attachedValue
+        } else if (!option.acceptsUnattachedValue) {
+            return OptParseResult(1, option, name, emptyList())
         }
-        return i to listOf(error)
-    }
-}
-
-
-private fun parseLongOpt(
-    ignoreUnknown: Boolean,
-    context: Context,
-    tokens: List<String>,
-    tok: String,
-    index: Int,
-    optionsByName: Map<String, Option>,
-    subcommandNames: Set<String>,
-): OptParseResult {
-    val equalsIndex = tok.indexOf('=')
-    var (name, attachedValue) = if (equalsIndex >= 0) {
-        tok.substring(0, equalsIndex) to tok.substring(equalsIndex + 1)
-    } else {
-        tok to null
-    }
-    name = context.tokenTransformer(context, name)
-    val option = optionsByName[name] ?: if (ignoreUnknown) {
-        return OptParseResult(1, listOf(tok))
-    } else {
-        val possibilities = context.correctionSuggestor(
-            name,
-            optionsByName.filterNot { it.value.hidden }.keys.toList()
-        )
-        return OptParseResult(1, err = NoSuchOption(name, possibilities))
-    }
 
-    return parseOptValues(
-        option,
-        name,
-        ignoreUnknown,
-        tokens,
-        index,
-        attachedValue,
-        optionsByName,
-        subcommandNames
-    )
-}
-
-private fun parseOptValues(
-    option: Option,
-    name: String,
-    ignoreUnknown: Boolean,
-    tokens: List<String>,
-    index: Int,
-    attachedValue: String?,
-    optionsByName: Map<String, Option>,
-    subcommandNames: Set<String>,
-): OptParseResult {
-    val values = mutableListOf<String>()
-    if (attachedValue != null) {
-        values += attachedValue
-    } else if (!option.acceptsUnattachedValue) {
-        return OptParseResult(1, option, name, emptyList())
-    }
-
-    for (i in (index + 1)..tokens.lastIndex) {
-        val tok = tokens[i]
-        if (values.size >= option.nvalues.last) break
-        if (values.size >= option.nvalues.first && (tok == "--"
-                    || tok in optionsByName
-                    || tok in subcommandNames
-                    || !ignoreUnknown && splitOptionPrefix(tok).first.isNotEmpty())
-        ) {
-            break
+        for (j in (i + 1)..tokens.lastIndex) {
+            val tok = tokens[j]
+            if (values.size >= option.nvalues.last) break
+            if ((values.size >= option.nvalues.first) &&
+                ((tok == "--")
+                        || (tok in optionsByName)
+                        || (tok in subcommandNames)
+                        || (!command.treatUnknownOptionsAsArgs
+                        && splitOptionPrefix(tok).first.isNotEmpty()))
+            ) break
+            values += tok
         }
 
-        values += tok
-    }
-
-    val consumed = values.size + if (attachedValue == null) 1 else 0
-    if (values.size !in option.nvalues) {
-        return OptParseResult(
-            consumed,
-            err = IncorrectOptionValueCount(option, name)
-        )
-    }
-
-    return OptParseResult(consumed, option, name, values)
-}
+        val consumed = values.size + if (attachedValue == null) 1 else 0
+        if (values.size !in option.nvalues) {
+            return OptParseResult(
+                consumed,
+                err = IncorrectOptionValueCount(option, name)
+            )
+        }
 
-private fun parseShortOpt(
-    ignoreUnknown: Boolean,
-    context: Context,
-    tokens: List<String>,
-    tok: String,
-    index: Int,
-    optionsByName: Map<String, Option>,
-    numberOption: Option?,
-    subcommandNames: Set<String>,
-): OptParseResult {
-    val prefix = tok[0].toString()
-
-    if (numberOption != null && tok.drop(1).all { it.isDigit() }) {
-        return OptParseResult(1, numberOption, "", listOf(tok.drop(1)))
+        return OptParseResult(consumed, option, name, values)
     }
 
-    val invocations = mutableListOf<OptInvocation>()
-
-    for ((i, opt) in tok.withIndex()) {
-        if (i == 0) continue // skip the dash
 
-        val name = context.tokenTransformer(context, prefix + opt)
-        val option = optionsByName[name] ?: if (ignoreUnknown) {
-            return OptParseResult(1, unknown = listOf(tok))
-        } else {
-            val possibilities = when {
-                prefix == "-" && "-$tok" in optionsByName -> listOf("-$tok")
-                else -> emptyList()
-            }
-            return OptParseResult(1, err = NoSuchOption(name, possibilities))
-        }
-        if (option.nvalues.last > 0) {
-            val value = if (i < tok.lastIndex) tok.drop(i + 1) else null
-            val result = parseOptValues(
-                option,
-                name,
-                ignoreUnknown,
-                tokens,
-                index,
-                value,
-                optionsByName,
-                subcommandNames
-            )
-            return result.copy(known = invocations + result.known)
-        } else {
-            invocations += OptInvocation(option, name, emptyList())
-        }
-    }
-    return OptParseResult(1, invocations)
 }
 
-
 private fun parseArguments(
     argumentTokens: List<String>,
     arguments: List<Argument>,
@@ -410,6 +317,40 @@ private fun parseArguments(
     return ArgsParseResult(excess, invocations, null)
 }
 
+/** Returns the new argv index and any errors */
+private fun <RunnerT : Function<*>> handleExcessArgs(
+    argResult: ArgsParseResult,
+    command: BaseCliktCommand<RunnerT>,
+    i: Int,
+    expandedArgv: List<String>,
+    commandResult: CommandParseResult<RunnerT>,
+): Pair<Int, List<CliktError>> {
+    if (argResult.excessCount <= 0) return i to emptyList()
+    val hasMultipleSubAncestor = command.currentContext.ancestors().any {
+        it.command.allowMultipleSubcommands
+    }
+    if (hasMultipleSubAncestor) {
+        return expandedArgv.size - argResult.excessCount to emptyList()
+    } else {
+        val subcommandNames = command._subcommands.map { it.commandName }
+        val error = when {
+            argResult.excessCount == 1 && subcommandNames.isNotEmpty() -> {
+                val actual = commandResult.argumentTokens.last()
+                val possibilities = command.currentContext.correctionSuggestor(
+                    actual, subcommandNames
+                )
+                NoSuchSubcommand(actual, possibilities)
+            }
+
+            else -> {
+                NoSuchArgument(commandResult.argumentTokens.takeLast(argResult.excessCount))
+            }
+        }
+        return i to listOf(error)
+    }
+}
+
+
 private fun loadArgFile(filename: String, context: Context): List<String> {
     return shlex(filename, context.argumentFileReader!!(filename), context.localization)
 }

From 942d7cad51a37bf0e9d34ca2f78f47941b8661d2 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 31 Mar 2024 13:05:35 -0700
Subject: [PATCH 08/43] Fix finalization context

---
 .../ajalt/clikt/internal/Finalization.kt      | 53 +++++++++++++------
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 41 +++++++++-----
 .../ajalt/clikt/parsers/ParserInternals.kt    | 28 +++++-----
 .../ajalt/clikt/core/CliktCommandTest.kt      |  1 -
 .../ajalt/clikt/parameters/ArgumentTest.kt    | 10 ++--
 .../clikt/parameters/EagerOptionsTest.kt      |  1 +
 .../ajalt/clikt/parameters/SubcommandTest.kt  | 21 ++++++--
 7 files changed, 101 insertions(+), 54 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index 05ae88cd..188d1622 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -13,7 +13,7 @@ internal fun finalizeOptions(
     invocationsByOption: Map<Option, List<Invocation>>,
 ) {
     val errors = finalizeParameters(
-        context, options, emptyList(), invocationsByOption, emptyList()
+        context, options, emptyList(), emptyList(), invocationsByOption, emptyList()
     )
     MultiUsageError.buildOrNull(errors)?.let { throw it }
 }
@@ -27,29 +27,41 @@ internal fun finalizeParameters(
     context: Context,
     options: List<Option>,
     groups: List<ParameterGroup>,
+    arguments: List<Argument>,
     optionInvocations: Map<Option, List<Invocation>>,
     argumentInvocations: List<ArgumentInvocation>,
 ): List<UsageError> {
-    val allGroups = optionInvocations.entries
-        .groupBy({ it.key.group }, { it.key to it.value })
-        .mapValuesTo(mutableMapOf()) { it.value.toMap() }
-
     // Add uninvoked params last so that e.g. we can skip prompting if there's an error in an
     // invoked option
-    for (group in groups) {
-        if (group !in allGroups) allGroups[group] = emptyMap()
+
+    val allGroups = buildMap<ParameterGroup?, Map<Option, List<Invocation>>> {
+        optionInvocations.entries
+            .groupBy({ it.key.group }, { it.key to it.value })
+            .mapValuesTo(this) { it.value.toMap() }
+        for (group in groups) {
+            if (group !in this) set(group, emptyMap())
+        }
     }
 
-    val allOptions = (allGroups[null] ?: emptyMap()).toMutableMap()
-    for (opt in options) {
-        if (opt !in allOptions) allOptions[opt] = emptyList()
+    val allOptions = buildMap<Option, List<Invocation>> {
+        allGroups[null]?.toMap(this)
+        for (opt in options) {
+            if (opt !in this) set(opt, emptyList())
+        }
     }
 
-    val allParams: List<Param> =
-        argumentInvocations.map { Arg(it.argument, it.values) } +
-                allOptions.map { Opt(it.key, it.value) } +
-                allGroups.mapNotNull { it.key?.let { k -> Group(k, it.value) } }
+    val allArguments = buildMap<Argument, List<String>> {
+        argumentInvocations.associateTo(this) { it.argument to it.values }
+        for (arg in arguments) {
+            if (arg !in this) set(arg, emptyList())
+        }
+    }
 
+    val allParams: List<Param> = buildList {
+        allArguments.keys.mapTo(this) { Arg(it, allArguments.getValue(it)) }
+        allOptions.keys.mapTo(this) { Opt(it, allOptions.getValue(it)) }
+        allGroups.mapNotNullTo(this) { it.key?.let { k -> Group(k, it.value) } }
+    }
 
     val errors = mutableListOf<UsageError>()
     var currentRound = allParams.toList()
@@ -74,7 +86,7 @@ internal fun finalizeParameters(
                 if (!context.errorEncountered) throw e
             }
         }
-        if (currentRound.size <= nextRound.size) break
+        if (nextRound.isEmpty() || currentRound.size <= nextRound.size) break
         currentRound = nextRound.toList()
         nextRound.clear()
     }
@@ -82,7 +94,7 @@ internal fun finalizeParameters(
     return errors
 }
 
-internal fun validateParameters(
+internal fun validateOptions(
     context: Context,
     optionInvocations: Map<Option, List<Invocation>>,
 ): List<UsageError> {
@@ -90,6 +102,15 @@ internal fun validateParameters(
     optionInvocations.keys.filter { it.group == null }.forEach {
         gatherErrors(usageErrors, context) { it.postValidate(context) }
     }
+    return usageErrors
+}
+
+internal fun validateParameters(
+    context: Context,
+    optionInvocations: Map<Option, List<Invocation>>,
+): List<UsageError> {
+    val usageErrors = mutableListOf<UsageError>()
+    usageErrors += validateOptions(context, optionInvocations)
     context.command.registeredParameterGroups().forEach {
         gatherErrors(usageErrors, context) { it.postValidate(context) }
     }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index ba0f05d7..3b8d5fc0 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -2,13 +2,14 @@ package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.MultiUsageError
+import com.github.ajalt.clikt.core.UsageError
+import com.github.ajalt.clikt.internal.finalizeOptions
 import com.github.ajalt.clikt.internal.finalizeParameters
+import com.github.ajalt.clikt.internal.validateOptions
 import com.github.ajalt.clikt.internal.validateParameters
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
-// TODO: move this back to parsers package
-
 object CommandLineParser {
     fun tokenize(
         commandLine: String,
@@ -19,27 +20,41 @@ object CommandLineParser {
 
     // TODO: docs does not throw
     fun <RunnerT : Function<*>> parse(
-        command: BaseCliktCommand<RunnerT>,
-        originalArgv: List<String>,
+        command: BaseCliktCommand<RunnerT>, originalArgv: List<String>,
     ): CommandLineParseResult<RunnerT> {
         return parseArgv(command, originalArgv)
     }
 
+    // TODO: docs throws
     fun finalize(invocation: CommandInvocation<*>) {
-        val usageErrors = finalizeParameters(
+        val (eagerOpts, nonEagerOpts) = invocation.command.registeredOptions()
+            .partition { it.eager }
+
+        val (eagerInvs, nonEagerInvs) = invocation.optionInvocations.entries
+            .partition { it.key.eager }
+            .toList().map { it.associate { (k, v) -> k to v } }
+
+        // finalize and validate eager options first
+        finalizeOptions(invocation.command.currentContext, eagerOpts, eagerInvs)
+        validateOptions(invocation.command.currentContext, eagerInvs).throwErrors()
+
+        // then finalize and validate everything else
+        finalizeParameters(
             invocation.command.currentContext,
-            invocation.command.registeredOptions(),
+            nonEagerOpts,
             invocation.command.registeredParameterGroups(),
-            invocation.optionInvocations,
+            invocation.command.registeredArguments(),
+            nonEagerInvs,
             invocation.argumentInvocations,
-        )
+        ).throwErrors()
 
-        // Now that all parameters have been finalized, we can validate everything
-        val validationErrors = validateParameters(
+        validateParameters(
             invocation.command.currentContext,
             invocation.optionInvocations
-        )
-
-        MultiUsageError.buildOrNull(usageErrors + validationErrors)?.let { throw it }
+        ).throwErrors()
     }
 }
+
+private fun List<UsageError>.throwErrors() {
+    MultiUsageError.buildOrNull(this)?.let { throw it }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index f8438f77..70c11a15 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -6,40 +6,40 @@ import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
 internal fun <RunnerT : Function<*>> parseArgv(
-    command: BaseCliktCommand<RunnerT>,
+    rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
-    var nextCommand: BaseCliktCommand<RunnerT>? = command
+    var command: BaseCliktCommand<RunnerT>? = rootCommand
     val errors = mutableListOf<CliktError>()
     var i = 0
-    while (nextCommand != null) {
+    while (command != null) {
         val parent = results.lastOrNull()?.command?.currentContext
-        val commandResult = CommandParser(nextCommand, parent, expandedArgv, i).parse()
-        check(expandedArgv.isEmpty() || i in expandedArgv.indices) {
-            "Internal error: index $i out of bounds ${expandedArgv.indices}"
-        }
-
+        val commandResult = CommandParser(command, parent, expandedArgv, i).parse()
         i = commandResult.i
         errors += commandResult.errors
         expandedArgv = commandResult.expandedArgv
-        nextCommand = commandResult.subcommand
         if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
 
         val argResult = parseArguments(commandResult.argumentTokens, command._arguments)
+        argResult.err?.let { errors += it }
+
         val excessArgResult = handleExcessArgs(argResult, command, i, expandedArgv, commandResult)
         i = excessArgResult.first
         errors += excessArgResult.second
-        errors.forEach { e ->
-            (e as? UsageError)?.let { it.context = it.context ?: command.currentContext }
+        for (e in errors) {
+            if (e is UsageError) e.context = e.context ?: command.currentContext
         }
-        results += CommandInvocation(command, commandResult.optInvocations, argResult.invocations)
+        results += CommandInvocation(
+            command, commandResult.optInvocations, argResult.invocations
+        )
+        command = commandResult.subcommand
     }
     val lastInvocation = results.lastOrNull()
     if (lastInvocation != null && i != expandedArgv.size) {
         errors += NoSuchArgument(expandedArgv.drop(i + 1)).also {
-            it.context = command.currentContext
+            it.context = rootCommand.currentContext
         }
     }
     return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
@@ -87,7 +87,7 @@ private class CommandParser<RunnerT : Function<*>>(
         }
         prefixes.remove("")
 
-        if (tokens.isEmpty() && command.printHelpOnEmptyArgs) {
+        if (i > tokens.lastIndex && command.printHelpOnEmptyArgs) {
             errors += PrintHelpMessage(context, error = true)
             return makeResult()
         }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
index cf3726f0..3219adb7 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
@@ -75,7 +75,6 @@ class CliktCommandTest {
         }
     }
 
-
     @Test
     @JsName("printHelpOnEmptyArgs__true")
     fun `printHelpOnEmptyArgs = true`() {
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
index 8af41685..ce64829b 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
@@ -305,19 +305,17 @@ class ArgumentTest {
 
     @Test
     @JsName("value_minus_minus_with_argument")
-    fun `value -- with argument`() = forAll(
-        row("--xx --xx -- --xx", "--xx", "--xx")
-    ) { argv, ex, ey ->
+    fun `value -- with argument`() {
         class C : TestCommand() {
             val x by option("-x", "--xx")
             val y by argument()
             override fun run_() {
-                x shouldBe ex
-                y shouldBe ey
+                x shouldBe "--xx"
+                y shouldBe  "--xx"
             }
         }
 
-        C().parse(argv)
+        C().parse("--xx --xx -- --xx")
     }
 
     @Test
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
index b17dbf71..421ed31e 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
@@ -51,6 +51,7 @@ class EagerOptionsTest {
             val o by option().flag().validate { error("fail") }
         }
 
+
         shouldThrow<PrintHelpMessage> { C().parse("-h --o") }
         shouldThrow<PrintHelpMessage> { C().parse("--o -h") }
         shouldThrow<IllegalStateException> { C().parse("--o") }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index 13a0af02..e1ffe5ff 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.parameters
 
-import com.github.ajalt.clikt.core.NoSuchSubcommand
-import com.github.ajalt.clikt.core.UsageError
-import com.github.ajalt.clikt.core.context
-import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
 import com.github.ajalt.clikt.parameters.arguments.pair
@@ -13,6 +10,7 @@ import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.testing.TestCommand
 import com.github.ajalt.clikt.testing.formattedMessage
 import com.github.ajalt.clikt.testing.parse
+import com.github.ajalt.clikt.testing.test
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.data.blocking.forAll
 import io.kotest.data.row
@@ -265,6 +263,21 @@ class SubcommandTest {
             """.trimMargin()
     }
 
+    @Test
+    @JsName("subcommandprintHelpOnEmptyArgs__true")
+    fun `subcommand printHelpOnEmptyArgs = true`() {
+        class C : TestCommand(called = false, printHelpOnEmptyArgs = true)
+        class S : TestCommand(called = false, printHelpOnEmptyArgs = true) {
+            val x by argument()
+        }
+
+        shouldThrow<PrintHelpMessage> {
+            C().subcommands(S()).parse("s")
+        }.error shouldBe true
+        val c = C().subcommands(S().context { helpOptionNames = emptyList() })
+        c.test("s").output.trim() shouldBe "Usage: c s <x>"
+    }
+
     @Test
     fun noSuchSubcommand() = forAll(
         row("qux", "no such subcommand qux"),

From ff02f3e2545b50e1ce61ba86e60198820bf4e990 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 31 Mar 2024 16:57:45 -0700
Subject: [PATCH 09/43] Fix excess arguments inside a multiple subcommand

---
 CHANGELOG.md                                  |   3 +
 .../ajalt/clikt/parsers/ParserInternals.kt    | 195 +++++++++---------
 .../ajalt/clikt/parameters/SubcommandTest.kt  |   9 +-
 3 files changed, 104 insertions(+), 103 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8cc0d9e7..672806b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@
 ### Added
 - Publish `linuxArm64` and `wasmJs` targets.
 
+### Fixed
+- Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
+
 ## 4.3.0
 ### 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))
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 70c11a15..089e86a4 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -1,7 +1,6 @@
 package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.*
-import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
@@ -22,17 +21,11 @@ internal fun <RunnerT : Function<*>> parseArgv(
         expandedArgv = commandResult.expandedArgv
         if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
 
-        val argResult = parseArguments(commandResult.argumentTokens, command._arguments)
-        argResult.err?.let { errors += it }
-
-        val excessArgResult = handleExcessArgs(argResult, command, i, expandedArgv, commandResult)
-        i = excessArgResult.first
-        errors += excessArgResult.second
         for (e in errors) {
             if (e is UsageError) e.context = e.context ?: command.currentContext
         }
         results += CommandInvocation(
-            command, commandResult.optInvocations, argResult.invocations
+            command, commandResult.optInvocations, commandResult.argInvocations
         )
         command = commandResult.subcommand
     }
@@ -54,7 +47,18 @@ private class CommandParser<RunnerT : Function<*>>(
     private var tokens = argv
     private val context = command.resetContext(parentContext)
     private val aliases = command.aliases()
-    private val subcommands = command._subcommands.associateBy { it.commandName }
+    private val subcommands = buildMap {
+        // If the parent command allows multiple subcommands, include the parent's subcommands so
+        // that we can chain into them
+        if (parentContext != null && parentContext.command.allowMultipleSubcommands) {
+            parentContext.command._subcommands.associateTo(this) {
+                // We could avoid this cast if Context was generic, but it doesn't seem worth it
+                @Suppress("UNCHECKED_CAST")
+                it.commandName to it as BaseCliktCommand<RunnerT>
+            }
+        }
+        command._subcommands.associateByTo(this) { it.commandName }
+    }
     private val subcommandNames = subcommands.keys
     private val optionsByName = mutableMapOf<String, Option>()
     private val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
@@ -62,37 +66,29 @@ private class CommandParser<RunnerT : Function<*>>(
     private val longNames = mutableSetOf<String>()
     private val argumentTokens = mutableListOf<String>()
     private var subcommand: BaseCliktCommand<RunnerT>? = null
-    private var canParseOptions = true
-    private var canExpandAtFiles = context.expandArgumentFiles
     private val optInvocations = mutableListOf<OptInvocation>()
+    private val argInvocations = mutableListOf<ArgumentInvocation>()
     private val errors = mutableListOf<CliktError>()
     private var i = startingIndex
     private var minAliasI = i
+    private val minArgCount = when {
+        command._arguments.any { it.nvalues < 0 } -> Int.MAX_VALUE
+        else -> command._arguments.sumOf { it.nvalues }
+    }
+    private val canParseSubcommands get() = argumentTokens.size >= minArgCount
+    private var canParseOptions = true
+    private var canExpandAtFiles = context.expandArgumentFiles
 
     fun parse(): CommandParseResult<RunnerT> {
-        for (option in command._options) {
-            require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
-                "options must have at least one name"
-            }
-
-            require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
-                "acceptsUnattachedValue must be true if the option accepts more than one value"
-            }
-
-            for (name in option.names + option.secondaryNames) {
-                optionsByName[name] = option
-                if (name.length > 2) longNames += name
-                prefixes += splitOptionPrefix(name).first
-            }
-        }
-        prefixes.remove("")
-
-        if (i > tokens.lastIndex && command.printHelpOnEmptyArgs) {
-            errors += PrintHelpMessage(context, error = true)
-            return makeResult()
-        }
+        splitOptionPrefixes()
+        if (printHelpOnEmptyArgsIfNecessary()) return makeResult()
+        consumeTokens()
+        parseArguments()
+        return makeResult()
+    }
 
-        loop@ while (i <= tokens.lastIndex) {
+    private fun consumeTokens() {
+        while (i <= tokens.lastIndex) {
             val tok = tokens[i]
             val normTok = context.tokenTransformer(context, tok)
             val prefix = splitOptionPrefix(tok).first
@@ -135,10 +131,10 @@ private class CommandParser<RunnerT : Function<*>>(
                     insertTokens(aliases.getValue(tok))
                 }
 
-                normTok in subcommands -> {
+                canParseSubcommands && normTok in subcommands -> {
                     subcommand = subcommands.getValue(normTok)
                     i += 1
-                    break@loop
+                    break
                 }
 
                 else -> {
@@ -148,13 +144,38 @@ private class CommandParser<RunnerT : Function<*>>(
                 }
             }
         }
+    }
 
-        return makeResult()
+    private fun printHelpOnEmptyArgsIfNecessary(): Boolean {
+        if (i > tokens.lastIndex && command.printHelpOnEmptyArgs) {
+            errors += PrintHelpMessage(context, error = true)
+            return true
+        }
+        return false
+    }
+
+    private fun splitOptionPrefixes() {
+        for (option in command._options) {
+            require(option.names.isNotEmpty() || option.secondaryNames.isNotEmpty()) {
+                "options must have at least one name"
+            }
+
+            require(option.acceptsUnattachedValue || option.nvalues.last <= 1) {
+                "acceptsUnattachedValue must be true if the option accepts more than one value"
+            }
+
+            for (name in option.names + option.secondaryNames) {
+                optionsByName[name] = option
+                if (name.length > 2) longNames += name
+                prefixes += splitOptionPrefix(name).first
+            }
+        }
+        prefixes.remove("")
     }
 
     private fun makeResult(): CommandParseResult<RunnerT> {
         val opts = optInvocations.groupBy({ it.opt }, { it.inv })
-        return CommandParseResult(subcommand, i, errors, tokens, opts, argumentTokens)
+        return CommandParseResult(subcommand, i, errors, tokens, opts, argInvocations)
     }
 
     private fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
@@ -278,75 +299,53 @@ private class CommandParser<RunnerT : Function<*>>(
         return OptParseResult(consumed, option, name, values)
     }
 
+    private fun parseArguments() {
+        // The number of fixed size arguments that occur after an unlimited size argument. This
+        // includes optional args, so it might be bigger than the number of provided values.
+        val endSize = command._arguments.asReversed()
+            .takeWhile { it.nvalues > 0 }
+            .sumOf { it.nvalues }
+
+        var tokenI = 0
+        for (argument in command._arguments) {
+            val remaining = argumentTokens.size - tokenI
+            val consumed = when {
+                argument.nvalues <= 0 -> maxOf(if (argument.required) 1 else 0, remaining - endSize)
+                argument.nvalues > 0 && !argument.required && remaining == 0 -> 0
+                else -> argument.nvalues
+            }
 
-}
-
-private fun parseArguments(
-    argumentTokens: List<String>,
-    arguments: List<Argument>,
-): ArgsParseResult {
-    val invocations = mutableListOf<ArgumentInvocation>()
-    // The number of fixed size arguments that occur after an unlimited size argument. This
-    // includes optional args, so it might be bigger than the number of provided values.
-    val endSize = arguments.asReversed()
-        .takeWhile { it.nvalues > 0 }
-        .sumOf { it.nvalues }
-
-    var i = 0
-    for (argument in arguments) {
-        val remaining = argumentTokens.size - i
-        val consumed = when {
-            argument.nvalues <= 0 -> maxOf(if (argument.required) 1 else 0, remaining - endSize)
-            argument.nvalues > 0 && !argument.required && remaining == 0 -> 0
-            else -> argument.nvalues
-        }
-
-        if (consumed > remaining) {
-            val e = when (remaining) {
-                0 -> MissingArgument(argument)
-                else -> IncorrectArgumentValueCount(argument)
+            if (consumed > remaining) {
+                val e = when (remaining) {
+                    0 -> MissingArgument(argument)
+                    else -> IncorrectArgumentValueCount(argument)
+                }
+                errors += e
+                return
             }
-            return ArgsParseResult(0, invocations, e)
+            val values = argumentTokens.subList(tokenI, tokenI + consumed)
+            argInvocations += ArgumentInvocation(argument, values)
+            tokenI += consumed
         }
-        val values = argumentTokens.subList(i, i + consumed)
-        invocations += ArgumentInvocation(argument, values)
-        i += consumed
-    }
-
-    val excess = argumentTokens.size - i
-    return ArgsParseResult(excess, invocations, null)
-}
 
-/** Returns the new argv index and any errors */
-private fun <RunnerT : Function<*>> handleExcessArgs(
-    argResult: ArgsParseResult,
-    command: BaseCliktCommand<RunnerT>,
-    i: Int,
-    expandedArgv: List<String>,
-    commandResult: CommandParseResult<RunnerT>,
-): Pair<Int, List<CliktError>> {
-    if (argResult.excessCount <= 0) return i to emptyList()
-    val hasMultipleSubAncestor = command.currentContext.ancestors().any {
-        it.command.allowMultipleSubcommands
+        handleExcessArgs(argumentTokens.size - tokenI)
     }
-    if (hasMultipleSubAncestor) {
-        return expandedArgv.size - argResult.excessCount to emptyList()
-    } else {
-        val subcommandNames = command._subcommands.map { it.commandName }
-        val error = when {
-            argResult.excessCount == 1 && subcommandNames.isNotEmpty() -> {
-                val actual = commandResult.argumentTokens.last()
+
+    private fun handleExcessArgs(excessCount: Int) {
+        when {
+            excessCount == 0 -> {}
+            excessCount == 1 && subcommandNames.isNotEmpty() -> {
+                val actual = argumentTokens.last()
                 val possibilities = command.currentContext.correctionSuggestor(
-                    actual, subcommandNames
+                    actual, subcommandNames.toList()
                 )
-                NoSuchSubcommand(actual, possibilities)
+                errors += NoSuchSubcommand(actual, possibilities)
             }
 
             else -> {
-                NoSuchArgument(commandResult.argumentTokens.takeLast(argResult.excessCount))
+                errors += NoSuchArgument(argumentTokens.takeLast(excessCount))
             }
         }
-        return i to listOf(error)
     }
 }
 
@@ -361,13 +360,7 @@ private data class CommandParseResult<RunnerT : Function<*>>(
     val errors: List<CliktError>,
     val expandedArgv: List<String>,
     val optInvocations: Map<Option, List<Invocation>>,
-    val argumentTokens: List<String>,
-)
-
-private data class ArgsParseResult(
-    val excessCount: Int,
-    val invocations: List<ArgumentInvocation>,
-    val err: CliktError?,
+    val argInvocations: List<ArgumentInvocation>,
 )
 
 private data class OptInvocation(val opt: Option, val name: String, val values: List<String>) {
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index e1ffe5ff..c984b93c 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -403,9 +403,14 @@ class SubcommandTest {
             }
         }
 
-        val c = C()
-        c.subcommands(MultiSub1(1), MultiSub2(1)).parse("--x=xx foo 1 bar 2")
+        val c = C().subcommands(MultiSub1(1), MultiSub2(1))
+        c.parse("--x=xx foo 1 bar 2")
         c.x shouldBe "xx"
+
+        val c2 = C().subcommands(MultiSub1(1), MultiSub2(1))
+        shouldThrow<NoSuchSubcommand> {
+            c2.parse("--x=xx foo 1 z bar 2")
+        }
     }
 
     @Test

From 8af13e9f44b90c7b90d9cd977002d561c6e2a561 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Mon, 1 Apr 2024 10:10:17 -0700
Subject: [PATCH 10/43] Add reusable main implementation

---
 .../github/ajalt/clikt/core/BaseCliktCommand.kt  |  8 ++++----
 .../com/github/ajalt/clikt/core/CliktCommand.kt  | 12 ++----------
 .../com/github/ajalt/clikt/core/execution.kt     | 16 ++++++++++++++++
 .../github/ajalt/clikt/core/CliktCommandTest.kt  |  1 +
 4 files changed, 23 insertions(+), 14 deletions(-)
 mode change 100755 => 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
old mode 100755
new mode 100644
index e1b49e6f..74dc9e9e
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -372,15 +372,15 @@ abstract class BaseCliktCommand<RunnerT : Function<*>>(
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT, BaseT : BaseCliktCommand<RunnerT>, CommandT : BaseT> CommandT.subcommands(
-    commands: Iterable<BaseT>,
+fun <RunnerT : Function<*>, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
+    commands: Iterable<BaseCliktCommand<RunnerT>>,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT, BaseT : BaseCliktCommand<RunnerT>, CommandT : BaseT> CommandT.subcommands(
-    vararg commands: BaseT,
+fun <RunnerT : Function<*>, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
+    vararg commands: BaseCliktCommand<RunnerT>,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 1fee436d..17e1b25c 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -1,6 +1,5 @@
 package com.github.ajalt.clikt.core
 
-import com.github.ajalt.clikt.mpp.exitProcessMpp
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parsers.CommandLineParser
@@ -38,7 +37,7 @@ abstract class CliktCommand(
     treatUnknownOptionsAsArgs,
     hidden
 ) {
-    final override val runner: () -> Unit = ::run
+    final override val runner: () -> Unit get() = ::run
 
     /**
      * Perform actions after parsing is complete and this command is invoked.
@@ -72,14 +71,7 @@ fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asLis
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) {
-    try {
-        parse(argv)
-    } catch (e: CliktError) {
-        echoFormattedHelp(e)
-        exitProcessMpp(e.statusCode)
-    }
-}
+fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) = main(argv) { parse(argv) }
 
 /**
  * Parse the command line and throw an exception if parsing fails.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
new file mode 100644
index 00000000..905f3e00
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
@@ -0,0 +1,16 @@
+package com.github.ajalt.clikt.core
+
+import com.github.ajalt.clikt.mpp.exitProcessMpp
+
+// TODO: docs
+fun <RunnerT : Function<*>> BaseCliktCommand<RunnerT>.main(
+    argv: List<String>,
+    parse: BaseCliktCommand<RunnerT>.(List<String>) -> Unit,
+) {
+    try {
+        parse(argv)
+    } catch (e: CliktError) {
+        echoFormattedHelp(e)
+        exitProcessMpp(e.statusCode)
+    }
+}
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
index 3219adb7..8141b020 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
@@ -296,6 +296,7 @@ class CliktCommandTest {
     @JsName("treat_unknown_options_as_arguments")
     fun `treat unknown options as arguments`() {
         class C : TestCommand(treatUnknownOptionsAsArgs = true) {
+
             val foo by option().flag()
             val args by argument().multiple()
 

From 5b33996e643bdd3e14cb5bba02adf23a200f9a8f Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Mon, 1 Apr 2024 10:42:04 -0700
Subject: [PATCH 11/43] Set context eagerly

---
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 21 +++++++++++-----
 .../ajalt/clikt/parsers/ParserInternals.kt    | 16 ++++++-------
 .../ajalt/clikt/parameters/SubcommandTest.kt  | 24 +++++++++----------
 3 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 74dc9e9e..970a6d11 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -122,11 +122,16 @@ abstract class BaseCliktCommand<RunnerT : Function<*>>(
 
     private fun registeredOptionNames() = _options.flatMapTo(mutableSetOf()) { it.names }
 
+    /**
+     * Create a new context for this command and all its subcommands recursively.
+     *
+     * @return The new context.
+     */
     fun resetContext(parent: Context?): Context {
-        //TODO ("doc that each run get a fresh context now")
         _context?.close()
         // TODO either pass argv or remove it from ctx
-        _context = Context.build(this, parent, emptyList(), _contextConfig)
+        val ctx = Context.build(this, parent, emptyList(), _contextConfig)
+        _context = ctx
 
         if (allowMultipleSubcommands) {
             require(currentContext.ancestors().none { it.command.allowMultipleSubcommands }) {
@@ -143,10 +148,14 @@ abstract class BaseCliktCommand<RunnerT : Function<*>>(
                 }
             }
         }
-        // TODO
-        //  val a = (ancestors + parent?.command).filterNotNull()
-        //  check(command !in a) { "Command ${command.commandName} already registered" }
-        return _context!!
+
+        val a = ctx.ancestors().map { it.command }.toList()
+        for (command in _subcommands) {
+            check(command !in a) {
+                "Command ${command.commandName} already registered" }
+            command.resetContext(ctx)
+        }
+        return ctx
     }
 
     /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 089e86a4..837a282a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -8,6 +8,7 @@ internal fun <RunnerT : Function<*>> parseArgv(
     rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
+    rootCommand.resetContext(null)
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
     var command: BaseCliktCommand<RunnerT>? = rootCommand
@@ -45,18 +46,18 @@ private class CommandParser<RunnerT : Function<*>>(
     startingIndex: Int,
 ) {
     private var tokens = argv
-    private val context = command.resetContext(parentContext)
+    private val context = command.currentContext
     private val aliases = command.aliases()
     private val subcommands = buildMap {
-        // If the parent command allows multiple subcommands, include the parent's subcommands so
+        // If an ancestor command allows multiple subcommands, include its subcommands so
         // that we can chain into them
-        if (parentContext != null && parentContext.command.allowMultipleSubcommands) {
-            parentContext.command._subcommands.associateTo(this) {
+        parentContext?.selfAndAncestors()
+            ?.firstOrNull { it.command.allowMultipleSubcommands }?.command
+            ?._subcommands?.associateTo(this) {
                 // We could avoid this cast if Context was generic, but it doesn't seem worth it
                 @Suppress("UNCHECKED_CAST")
                 it.commandName to it as BaseCliktCommand<RunnerT>
             }
-        }
         command._subcommands.associateByTo(this) { it.commandName }
     }
     private val subcommandNames = subcommands.keys
@@ -71,10 +72,7 @@ private class CommandParser<RunnerT : Function<*>>(
     private val errors = mutableListOf<CliktError>()
     private var i = startingIndex
     private var minAliasI = i
-    private val minArgCount = when {
-        command._arguments.any { it.nvalues < 0 } -> Int.MAX_VALUE
-        else -> command._arguments.sumOf { it.nvalues }
-    }
+    private val minArgCount = command._arguments.sumOf { it.nvalues.coerceAtLeast(0) }
     private val canParseSubcommands get() = argumentTokens.size >= minArgCount
     private var canParseOptions = true
     private var canExpandAtFiles = context.expandArgumentFiles
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index c984b93c..cb4ee7af 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -321,8 +321,8 @@ class SubcommandTest {
         row("foo a bar --opt=o b foo c bar d", 2, 2, "c", null, "d"),
         row("foo a bar b foo c bar --opt=o d", 2, 2, "c", "o", "d")
     ) { argv, fc, bc, fa, bo, ba ->
-        val foo = MultiSub1(count = fc)
-        val bar = MultiSub2(count = bc)
+        val foo = MultiSubFoo(count = fc)
+        val bar = MultiSubBar(count = bc)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(
             foo,
             bar,
@@ -339,8 +339,8 @@ class SubcommandTest {
     @Test
     @JsName("multiple_subcommands_with_nesting")
     fun `multiple subcommands with nesting`() {
-        val foo = MultiSub1(count = 2)
-        val bar = MultiSub2(count = 2)
+        val foo = MultiSubFoo(count = 2)
+        val bar = MultiSubBar(count = 2)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(foo.subcommands(bar))
         c.parse("foo f1 bar --opt=1 b1 foo f2 bar b2")
         foo.arg shouldBe "f2"
@@ -351,8 +351,8 @@ class SubcommandTest {
     @Test
     @JsName("multiple_subcommands_nesting_the_same_name")
     fun `multiple subcommands nesting the same name`() {
-        val bar1 = MultiSub2(count = 2)
-        val bar2 = MultiSub2(count = 2)
+        val bar1 = MultiSubBar(count = 2)
+        val bar2 = MultiSubBar(count = 2)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(bar1.subcommands(bar2))
         c.parse("bar a11 bar a12 bar a12 bar --opt=o a22")
         bar1.arg shouldBe "a12"
@@ -373,7 +373,7 @@ class SubcommandTest {
             val arg by argument().multiple()
         }
 
-        val foo = MultiSub1(count = fc)
+        val foo = MultiSubFoo(count = fc)
         val baz = Baz()
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(foo, baz)
         c.parse(argv)
@@ -403,11 +403,11 @@ class SubcommandTest {
             }
         }
 
-        val c = C().subcommands(MultiSub1(1), MultiSub2(1))
+        val c = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
         c.parse("--x=xx foo 1 bar 2")
         c.x shouldBe "xx"
 
-        val c2 = C().subcommands(MultiSub1(1), MultiSub2(1))
+        val c2 = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
         shouldThrow<NoSuchSubcommand> {
             c2.parse("--x=xx foo 1 z bar 2")
         }
@@ -424,7 +424,7 @@ class SubcommandTest {
             }
         }
 
-        C().subcommands(MultiSub1(1), MultiSub2(1)).parse("--x=xx foo 1 bar 2")
+        C().subcommands(MultiSubFoo(1), MultiSubBar(1)).parse("--x=xx foo 1 bar 2")
     }
 
     @Test
@@ -455,11 +455,11 @@ class SubcommandTest {
     }
 }
 
-private class MultiSub1(count: Int) : TestCommand(name = "foo", count = count) {
+private class MultiSubFoo(count: Int) : TestCommand(name = "foo", count = count) {
     val arg by argument()
 }
 
-private class MultiSub2(count: Int) : TestCommand(name = "bar", count = count) {
+private class MultiSubBar(count: Int) : TestCommand(name = "bar", count = count) {
     val opt by option()
     val arg by argument()
 }

From 2d1b262e59aebf995504f56f2adc3a14f2aa7953 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Mon, 1 Apr 2024 13:54:42 -0700
Subject: [PATCH 12/43] Remove Function bound on generic

---
 .../kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt  | 6 +++---
 .../kotlin/com/github/ajalt/clikt/core/execution.kt         | 2 +-
 .../com/github/ajalt/clikt/parsers/CommandLineParser.kt     | 2 +-
 .../kotlin/com/github/ajalt/clikt/parsers/Invocation.kt     | 4 ++--
 .../com/github/ajalt/clikt/parsers/ParserInternals.kt       | 6 +++---
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 970a6d11..7d8a09a6 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -16,7 +16,7 @@ import com.github.ajalt.mordant.terminal.Terminal
  */
 @Suppress("PropertyName")
 @ParameterHolderDsl
-abstract class BaseCliktCommand<RunnerT : Function<*>>(
+abstract class BaseCliktCommand<RunnerT>(
     /**
      * The help for this command. The first line is used in the usage string, and the entire string
      * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
@@ -381,14 +381,14 @@ abstract class BaseCliktCommand<RunnerT : Function<*>>(
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT : Function<*>, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
+fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
     commands: Iterable<BaseCliktCommand<RunnerT>>,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT : Function<*>, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
+fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
     vararg commands: BaseCliktCommand<RunnerT>,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
index 905f3e00..cee8f8b7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
@@ -3,7 +3,7 @@ package com.github.ajalt.clikt.core
 import com.github.ajalt.clikt.mpp.exitProcessMpp
 
 // TODO: docs
-fun <RunnerT : Function<*>> BaseCliktCommand<RunnerT>.main(
+fun <RunnerT> BaseCliktCommand<RunnerT>.main(
     argv: List<String>,
     parse: BaseCliktCommand<RunnerT>.(List<String>) -> Unit,
 ) {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 3b8d5fc0..df1aa92d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -19,7 +19,7 @@ object CommandLineParser {
     }
 
     // TODO: docs does not throw
-    fun <RunnerT : Function<*>> parse(
+    fun <RunnerT> parse(
         command: BaseCliktCommand<RunnerT>, originalArgv: List<String>,
     ): CommandLineParseResult<RunnerT> {
         return parseArgv(command, originalArgv)
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 503b0cb4..96df6325 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -20,13 +20,13 @@ data class Invocation(val name: String, val values: List<String>)
 // TODO: docs
 data class ArgumentInvocation(val argument: Argument, val values: List<String>)
 
-data class CommandInvocation<RunnerT : Function<*>>(
+data class CommandInvocation<RunnerT>(
     val command: BaseCliktCommand<RunnerT>,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
 )
 
-class CommandLineParseResult<RunnerT : Function<*>>(
+class CommandLineParseResult<RunnerT>(
     val invocations: List<CommandInvocation<RunnerT>>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 837a282a..682ec533 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -4,7 +4,7 @@ import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
-internal fun <RunnerT : Function<*>> parseArgv(
+internal fun <RunnerT> parseArgv(
     rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
@@ -39,7 +39,7 @@ internal fun <RunnerT : Function<*>> parseArgv(
     return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
 }
 
-private class CommandParser<RunnerT : Function<*>>(
+private class CommandParser<RunnerT>(
     private val command: BaseCliktCommand<RunnerT>,
     parentContext: Context?,
     argv: List<String>,
@@ -352,7 +352,7 @@ private fun loadArgFile(filename: String, context: Context): List<String> {
     return shlex(filename, context.argumentFileReader!!(filename), context.localization)
 }
 
-private data class CommandParseResult<RunnerT : Function<*>>(
+private data class CommandParseResult<RunnerT>(
     val subcommand: BaseCliktCommand<RunnerT>?,
     val i: Int,
     val errors: List<CliktError>,

From 9706b8f96ab9dfe587099124a2713c2878a832fe Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 2 Apr 2024 11:29:25 -0700
Subject: [PATCH 13/43] Change multi arg parsing with allowMultipleSubcommands

---
 CHANGELOG.md                                  |  3 ++
 .../ajalt/clikt/core/BaseCliktCommand.kt      |  3 +-
 .../ajalt/clikt/parsers/ParserInternals.kt    | 35 +++++++++----------
 .../ajalt/clikt/parameters/SubcommandTest.kt  | 12 +++----
 docs/commands.md                              | 18 ++++------
 5 files changed, 32 insertions(+), 39 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 672806b4..7a43ff94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@
 ### Added
 - Publish `linuxArm64` and `wasmJs` targets.
 
+### Changed
+- In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
+
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 7d8a09a6..66bc8b40 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -151,8 +151,7 @@ abstract class BaseCliktCommand<RunnerT>(
 
         val a = ctx.ancestors().map { it.command }.toList()
         for (command in _subcommands) {
-            check(command !in a) {
-                "Command ${command.commandName} already registered" }
+            check(command !in a) { "Command ${command.commandName} already registered" }
             command.resetContext(ctx)
         }
         return ctx
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 682ec533..6e4fab3a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -48,19 +48,18 @@ private class CommandParser<RunnerT>(
     private var tokens = argv
     private val context = command.currentContext
     private val aliases = command.aliases()
-    private val subcommands = buildMap {
-        // If an ancestor command allows multiple subcommands, include its subcommands so
-        // that we can chain into them
-        parentContext?.selfAndAncestors()
-            ?.firstOrNull { it.command.allowMultipleSubcommands }?.command
-            ?._subcommands?.associateTo(this) {
-                // We could avoid this cast if Context was generic, but it doesn't seem worth it
-                @Suppress("UNCHECKED_CAST")
-                it.commandName to it as BaseCliktCommand<RunnerT>
-            }
-        command._subcommands.associateByTo(this) { it.commandName }
-    }
-    private val subcommandNames = subcommands.keys
+    private val extraSubcommands = parentContext?.selfAndAncestors()
+        ?.firstOrNull { it.command.allowMultipleSubcommands }?.command
+        ?._subcommands?.associate {
+            // We could avoid this cast if Context was generic, but it doesn't seem worth it
+            @Suppress("UNCHECKED_CAST")
+            it.commandName to it as BaseCliktCommand<RunnerT>
+        } ?: emptyMap()
+    private val localSubcommands = command._subcommands.associateBy { it.commandName }
+
+    // If an ancestor command allows multiple subcommands, include its subcommands so
+    // that we can chain into them
+    private val allSubcommands = extraSubcommands + localSubcommands
     private val optionsByName = mutableMapOf<String, Option>()
     private val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
     private val prefixes = mutableSetOf<String>()
@@ -129,8 +128,8 @@ private class CommandParser<RunnerT>(
                     insertTokens(aliases.getValue(tok))
                 }
 
-                canParseSubcommands && normTok in subcommands -> {
-                    subcommand = subcommands.getValue(normTok)
+                canParseSubcommands && normTok in allSubcommands -> {
+                    subcommand = allSubcommands.getValue(normTok)
                     i += 1
                     break
                 }
@@ -279,7 +278,7 @@ private class CommandParser<RunnerT>(
             if ((values.size >= option.nvalues.first) &&
                 ((tok == "--")
                         || (tok in optionsByName)
-                        || (tok in subcommandNames)
+                        || (tok in allSubcommands)
                         || (!command.treatUnknownOptionsAsArgs
                         && splitOptionPrefix(tok).first.isNotEmpty()))
             ) break
@@ -332,10 +331,10 @@ private class CommandParser<RunnerT>(
     private fun handleExcessArgs(excessCount: Int) {
         when {
             excessCount == 0 -> {}
-            excessCount == 1 && subcommandNames.isNotEmpty() -> {
+            excessCount == 1 && localSubcommands.isNotEmpty() -> {
                 val actual = argumentTokens.last()
                 val possibilities = command.currentContext.correctionSuggestor(
-                    actual, subcommandNames.toList()
+                    actual, localSubcommands.keys.toList()
                 )
                 errors += NoSuchSubcommand(actual, possibilities)
             }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index cb4ee7af..b4e86a53 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -281,7 +281,6 @@ class SubcommandTest {
     @Test
     fun noSuchSubcommand() = forAll(
         row("qux", "no such subcommand qux"),
-        row("qux --opt", "no such subcommand qux"),
         row("fo", "no such subcommand fo. Did you mean foo?"),
         row("fop", "no such subcommand fop. Did you mean foo?"),
         row("bart", "no such subcommand bart. Did you mean bar?"),
@@ -365,9 +364,9 @@ class SubcommandTest {
     fun `multiple subcommands with varargs`() = forAll(
         row("foo f1 baz", 1, 1, "f1", emptyList()),
         row("foo f1 foo f2 baz", 2, 1, "f2", emptyList()),
-        row("baz foo", 0, 1, "", listOf("foo")),
-        row("baz foo baz foo", 0, 1, "", listOf("foo", "baz", "foo")),
-        row("foo f1 baz foo f2", 1, 1, "f1", listOf("foo", "f2"))
+        row("baz b1 foo f1", 1, 1, "f1", listOf("b1")),
+        row("baz foo f1 baz foo f2", 2, 2, "f2", listOf()),
+        row("foo f1 baz b1 b2 foo f2", 2, 1, "f2", listOf("b1", "b2"))
     ) { argv, fc, bc, fa, ba ->
         class Baz : TestCommand(name = "baz", count = bc) {
             val arg by argument().multiple()
@@ -408,9 +407,9 @@ class SubcommandTest {
         c.x shouldBe "xx"
 
         val c2 = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
-        shouldThrow<NoSuchSubcommand> {
+        shouldThrow<NoSuchArgument> {
             c2.parse("--x=xx foo 1 z bar 2")
-        }
+        }.formattedMessage shouldBe "got unexpected extra argument (z)"
     }
 
     @Test
@@ -437,7 +436,6 @@ class SubcommandTest {
         }.formattedMessage shouldBe "got unexpected extra argument (foo)"
     }
 
-
     @Test
     @JsName("accessing_options_of_uninvoked_subcommand")
     fun `accessing options of uninvoked subcommand`() {
diff --git a/docs/commands.md b/docs/commands.md
index fe9afcd5..f76023c4 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -446,20 +446,14 @@ constructor.
 
 The parent command will [`run`][run] once, and each subcommand will `run` once each time they're called.
 
-### Parsing multiple subcommands
+!!! warning
 
-Note that enabling `allowMultipleSubcommands` will disable [`allowInterspersedArgs`][interspersed]
-on the command and all its subcommands. If both were allowed to be enabled at the same time, then
-not all command lines could be parsed unambiguously.
+    Enabling `allowMultipleSubcommands` will disable [`allowInterspersedArgs`][interspersed]
+    on the command and all its subcommands. If both were allowed to be enabled at the same time, then
+    not all command lines could be parsed unambiguously.
 
-When parsing in this mode, tokens are consumed greedily by a subcommand until it encounters an
-argument token it doesn't support, at which point the parent command resumes parsing where the
-subcommand left off. This means that if you have a subcommand with an
-[`argument().multiple()`][argument.multiple] parameter, you won't be able to call any other
-subcommands after that one, since it will consume the rest of the command line.
-
-Subcommands of a command with `allowMultipleSubcommands=true` can themselves have subcommands, but
-cannot have `allowMultipleSubcommands=true`.
+    Subcommands of a command with `allowMultipleSubcommands=true` can themselves have subcommands, but
+    cannot have `allowMultipleSubcommands=true`.
 
 
 [argument.multiple]:             api/clikt/com.github.ajalt.clikt.parameters.arguments/multiple.html

From 57682697ed46506af16fafbf9b73001d8128587c Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 2 Apr 2024 12:53:09 -0700
Subject: [PATCH 14/43] Move errors list to individual invocations

---
 .../github/ajalt/clikt/core/CliktCommand.kt   |  1 -
 .../ajalt/clikt/internal/Finalization.kt      | 44 ++++++++++++-------
 .../com/github/ajalt/clikt/internal/Util.kt   | 13 ++++++
 .../parameters/options/OptionWithValues.kt    |  6 +--
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 19 +++++---
 .../github/ajalt/clikt/parsers/Invocation.kt  | 12 +----
 .../ajalt/clikt/parsers/ParserInternals.kt    | 21 +++++----
 7 files changed, 67 insertions(+), 49 deletions(-)
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Util.kt

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 17e1b25c..a0bc3a7b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -90,7 +90,6 @@ fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
 fun BaseCliktCommand<() -> Unit>.parse(argv: List<String>) {
 // TODO   generateCompletion()
     val result = CommandLineParser.parse(this, argv)
-    result.throwErrors()
     for (invocation in result.invocations) {
         CommandLineParser.finalize(invocation)
         invocation.command.runner()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index 188d1622..ecab77da 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -1,6 +1,8 @@
 package com.github.ajalt.clikt.internal
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.Abort
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.groups.ParameterGroup
 import com.github.ajalt.clikt.parameters.options.Option
@@ -12,10 +14,9 @@ internal fun finalizeOptions(
     options: List<Option>,
     invocationsByOption: Map<Option, List<Invocation>>,
 ) {
-    val errors = finalizeParameters(
-        context, options, emptyList(), emptyList(), invocationsByOption, emptyList()
-    )
-    MultiUsageError.buildOrNull(errors)?.let { throw it }
+    iterateFinalization(
+        context, getAllOptions(invocationsByOption, options).map { Opt(it.key, it.value) }
+    ).throwErrors()
 }
 
 private sealed class Param
@@ -43,12 +44,7 @@ internal fun finalizeParameters(
         }
     }
 
-    val allOptions = buildMap<Option, List<Invocation>> {
-        allGroups[null]?.toMap(this)
-        for (opt in options) {
-            if (opt !in this) set(opt, emptyList())
-        }
-    }
+    val allOptions = getAllOptions(allGroups[null] ?: emptyMap(), options)
 
     val allArguments = buildMap<Argument, List<String>> {
         argumentInvocations.associateTo(this) { it.argument to it.values }
@@ -58,11 +54,30 @@ internal fun finalizeParameters(
     }
 
     val allParams: List<Param> = buildList {
-        allArguments.keys.mapTo(this) { Arg(it, allArguments.getValue(it)) }
-        allOptions.keys.mapTo(this) { Opt(it, allOptions.getValue(it)) }
+        allArguments.entries.mapTo(this) { Arg(it.key, it.value) }
+        allOptions.entries.mapTo(this) { Opt(it.key, it.value) }
         allGroups.mapNotNullTo(this) { it.key?.let { k -> Group(k, it.value) } }
     }
 
+    return iterateFinalization(context, allParams)
+}
+
+private fun getAllOptions(
+    invocations: Map<Option, List<Invocation>>,
+    options: List<Option>,
+): Map<Option, List<Invocation>> {
+    return buildMap {
+        putAll(invocations)
+        for (opt in options) {
+            if (opt !in this) set(opt, emptyList())
+        }
+    }
+}
+
+private fun iterateFinalization(
+    context: Context,
+    allParams: List<Param>,
+): MutableList<UsageError> {
     val errors = mutableListOf<UsageError>()
     var currentRound = allParams.toList()
     val nextRound = mutableListOf<Param>()
@@ -90,7 +105,6 @@ internal fun finalizeParameters(
         currentRound = nextRound.toList()
         nextRound.clear()
     }
-
     return errors
 }
 
@@ -136,5 +150,3 @@ private inline fun gatherErrors(
         context.errorEncountered = true
     }
 }
-
-private val Option.group: ParameterGroup? get() = (this as? GroupableOption)?.parameterGroup
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Util.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Util.kt
new file mode 100644
index 00000000..dd678975
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Util.kt
@@ -0,0 +1,13 @@
+package com.github.ajalt.clikt.internal
+
+import com.github.ajalt.clikt.core.GroupableOption
+import com.github.ajalt.clikt.core.MultiUsageError
+import com.github.ajalt.clikt.core.UsageError
+import com.github.ajalt.clikt.parameters.groups.ParameterGroup
+import com.github.ajalt.clikt.parameters.options.Option
+
+internal val Option.group: ParameterGroup? get() = (this as? GroupableOption)?.parameterGroup
+
+internal fun List<UsageError>.throwErrors() {
+    MultiUsageError.buildOrNull(this)?.let { throw it }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
index fc6ef6ec..e2ef71ff 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
@@ -197,11 +197,7 @@ private class OptionWithValuesImpl<AllT, EachT, ValueT>(
                 when (valueSplit) {
                     null -> invocations
                     else -> invocations.map { inv ->
-                        inv.copy(values = inv.values.flatMap {
-                            it.split(
-                                valueSplit
-                            )
-                        })
+                        inv.copy(values = inv.values.flatMap { it.split(valueSplit) })
                     }
                 }
             }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index df1aa92d..bb4ef14a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -1,12 +1,10 @@
 package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.core.MultiUsageError
 import com.github.ajalt.clikt.core.UsageError
-import com.github.ajalt.clikt.internal.finalizeOptions
-import com.github.ajalt.clikt.internal.finalizeParameters
-import com.github.ajalt.clikt.internal.validateOptions
-import com.github.ajalt.clikt.internal.validateParameters
+import com.github.ajalt.clikt.internal.*
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
@@ -38,10 +36,13 @@ object CommandLineParser {
         finalizeOptions(invocation.command.currentContext, eagerOpts, eagerInvs)
         validateOptions(invocation.command.currentContext, eagerInvs).throwErrors()
 
+        // throw any parse errors after the eager options are finalized
+        invocation.throwErrors()
+
         // then finalize and validate everything else
         finalizeParameters(
             invocation.command.currentContext,
-            nonEagerOpts,
+            nonEagerOpts.filter { it.group == null },
             invocation.command.registeredParameterGroups(),
             invocation.command.registeredArguments(),
             nonEagerInvs,
@@ -55,6 +56,10 @@ object CommandLineParser {
     }
 }
 
-private fun List<UsageError>.throwErrors() {
-    MultiUsageError.buildOrNull(this)?.let { throw it }
+private fun CommandInvocation<*>.throwErrors() {
+    when (val first = errors.firstOrNull()) {
+        is UsageError -> errors.takeWhile { it is UsageError }
+            .filterIsInstance<UsageError>().throwErrors()
+        is CliktError -> throw first
+    }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 96df6325..00778fdc 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -24,21 +24,11 @@ data class CommandInvocation<RunnerT>(
     val command: BaseCliktCommand<RunnerT>,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
+    val errors: List<CliktError>,
 )
 
 class CommandLineParseResult<RunnerT>(
     val invocations: List<CommandInvocation<RunnerT>>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
-    val errors: List<CliktError>,
 )
-
-fun CommandLineParseResult<*>.throwErrors() {
-    when (val first = errors.firstOrNull()) {
-        is UsageError -> MultiUsageError.buildOrNull(
-            errors.takeWhile { it is UsageError }.filterIsInstance<UsageError>()
-        )?.let { throw it }
-
-        is CliktError -> throw first
-    }
-}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 6e4fab3a..5f53a2fe 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -12,31 +12,34 @@ internal fun <RunnerT> parseArgv(
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
     var command: BaseCliktCommand<RunnerT>? = rootCommand
-    val errors = mutableListOf<CliktError>()
     var i = 0
     while (command != null) {
         val parent = results.lastOrNull()?.command?.currentContext
         val commandResult = CommandParser(command, parent, expandedArgv, i).parse()
         i = commandResult.i
-        errors += commandResult.errors
         expandedArgv = commandResult.expandedArgv
         if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
 
-        for (e in errors) {
+        for (e in commandResult.errors) {
             if (e is UsageError) e.context = e.context ?: command.currentContext
         }
         results += CommandInvocation(
-            command, commandResult.optInvocations, commandResult.argInvocations
+            command,
+            commandResult.optInvocations,
+            commandResult.argInvocations,
+            commandResult.errors
         )
         command = commandResult.subcommand
     }
-    val lastInvocation = results.lastOrNull()
-    if (lastInvocation != null && i != expandedArgv.size) {
-        errors += NoSuchArgument(expandedArgv.drop(i + 1)).also {
-            it.context = rootCommand.currentContext
+    check(results.isNotEmpty())
+    if (i != expandedArgv.size) {
+        val lastResult = results.last()
+        val error = NoSuchArgument(expandedArgv.drop(i + 1)).also {
+            it.context = lastResult.command.currentContext
         }
+        results[results.lastIndex] = lastResult.copy(errors = lastResult.errors + error)
     }
-    return CommandLineParseResult(results, originalArgv, expandedArgv, errors)
+    return CommandLineParseResult(results, originalArgv, expandedArgv)
 }
 
 private class CommandParser<RunnerT>(

From e1237edabacc6e561af3804dd25317a91230dea4 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 2 Apr 2024 14:39:57 -0700
Subject: [PATCH 15/43] Re-add support for invokeWithoutSubcommand

---
 .../github/ajalt/clikt/core/CliktCommand.kt   |  1 -
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 32 ++++++++++++-------
 .../github/ajalt/clikt/parsers/Invocation.kt  |  3 +-
 .../ajalt/clikt/parsers/ParserInternals.kt    |  1 +
 4 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index a0bc3a7b..e77c636b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -3,7 +3,6 @@ package com.github.ajalt.clikt.core
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parsers.CommandLineParser
-import com.github.ajalt.clikt.parsers.throwErrors
 
 /**
  * The [CliktCommand] is the core of command line interfaces in Clikt.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index bb4ef14a..98175089 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -2,7 +2,7 @@ package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktError
-import com.github.ajalt.clikt.core.MultiUsageError
+import com.github.ajalt.clikt.core.PrintHelpMessage
 import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.internal.*
 import com.github.ajalt.clikt.output.Localization
@@ -25,7 +25,11 @@ object CommandLineParser {
 
     // TODO: docs throws
     fun finalize(invocation: CommandInvocation<*>) {
-        val (eagerOpts, nonEagerOpts) = invocation.command.registeredOptions()
+        val command = invocation.command
+        val context = command.currentContext
+        val subcommand = invocation.invokedSubcommand
+
+        val (eagerOpts, nonEagerOpts) = command.registeredOptions()
             .partition { it.eager }
 
         val (eagerInvs, nonEagerInvs) = invocation.optionInvocations.entries
@@ -33,26 +37,31 @@ object CommandLineParser {
             .toList().map { it.associate { (k, v) -> k to v } }
 
         // finalize and validate eager options first
-        finalizeOptions(invocation.command.currentContext, eagerOpts, eagerInvs)
-        validateOptions(invocation.command.currentContext, eagerInvs).throwErrors()
+        finalizeOptions(context, eagerOpts, eagerInvs)
+        validateOptions(context, eagerInvs).throwErrors()
 
         // throw any parse errors after the eager options are finalized
         invocation.throwErrors()
 
         // then finalize and validate everything else
         finalizeParameters(
-            invocation.command.currentContext,
+            context,
             nonEagerOpts.filter { it.group == null },
-            invocation.command.registeredParameterGroups(),
-            invocation.command.registeredArguments(),
+            command.registeredParameterGroups(),
+            command.registeredArguments(),
             nonEagerInvs,
             invocation.argumentInvocations,
         ).throwErrors()
 
-        validateParameters(
-            invocation.command.currentContext,
-            invocation.optionInvocations
-        ).throwErrors()
+        validateParameters(context, invocation.optionInvocations).throwErrors()
+
+        if (subcommand == null && command._subcommands.isNotEmpty() &&
+            !command.invokeWithoutSubcommand
+        ) {
+            throw PrintHelpMessage(context, error = true)
+        }
+
+        context.invokedSubcommand = subcommand
     }
 }
 
@@ -60,6 +69,7 @@ private fun CommandInvocation<*>.throwErrors() {
     when (val first = errors.firstOrNull()) {
         is UsageError -> errors.takeWhile { it is UsageError }
             .filterIsInstance<UsageError>().throwErrors()
+
         is CliktError -> throw first
     }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 00778fdc..27ebbb47 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -2,8 +2,6 @@ package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktError
-import com.github.ajalt.clikt.core.MultiUsageError
-import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 
@@ -24,6 +22,7 @@ data class CommandInvocation<RunnerT>(
     val command: BaseCliktCommand<RunnerT>,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
+    val invokedSubcommand: BaseCliktCommand<RunnerT>?,
     val errors: List<CliktError>,
 )
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 5f53a2fe..0e4fd551 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -27,6 +27,7 @@ internal fun <RunnerT> parseArgv(
             command,
             commandResult.optInvocations,
             commandResult.argInvocations,
+            commandResult.subcommand,
             commandResult.errors
         )
         command = commandResult.subcommand

From 2eb96ccd1e4f84568d6813e16a1186cc77d42d8a Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 2 Apr 2024 15:10:51 -0700
Subject: [PATCH 16/43] Handle eager options in groups

---
 .../com/github/ajalt/clikt/internal/Finalization.kt  | 11 ++++++-----
 .../clikt/parameters/internal/NullableLateinit.kt    |  6 ++++--
 .../github/ajalt/clikt/parsers/CommandLineParser.kt  |  2 +-
 .../ajalt/clikt/parameters/EagerOptionsTest.kt       | 12 ++++++------
 .../com/github/ajalt/clikt/testing/TestCommand.kt    |  3 +++
 5 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index ecab77da..4f6c5b9b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -5,6 +5,7 @@ import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.groups.ParameterGroup
+import com.github.ajalt.clikt.parameters.internal.LateinitException
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parsers.ArgumentInvocation
 import com.github.ajalt.clikt.parsers.Invocation
@@ -20,9 +21,9 @@ internal fun finalizeOptions(
 }
 
 private sealed class Param
-private class Opt(val option: Option, val invs: List<Invocation>) : Param()
-private class Arg(val argument: Argument, val invs: List<String>) : Param()
-private class Group(val group: ParameterGroup, val invs: Map<Option, List<Invocation>>) : Param()
+private data class Opt(val option: Option, val invs: List<Invocation>) : Param()
+private data class Arg(val argument: Argument, val invs: List<String>) : Param()
+private data class Group(val group: ParameterGroup, val invs: Map<Option, List<Invocation>>) : Param()
 
 internal fun finalizeParameters(
     context: Context,
@@ -90,7 +91,7 @@ private fun iterateFinalization(
                     is Opt -> it.option.finalize(context, it.invs)
                     is Group -> it.group.finalize(context, it.invs)
                 }
-            } catch (e: IllegalStateException) {
+            } catch (e: LateinitException) {
                 nextRound += it
             } catch (e: UsageError) {
                 e.context = e.context ?: context
@@ -113,7 +114,7 @@ internal fun validateOptions(
     optionInvocations: Map<Option, List<Invocation>>,
 ): List<UsageError> {
     val usageErrors = mutableListOf<UsageError>()
-    optionInvocations.keys.filter { it.group == null }.forEach {
+    optionInvocations.keys.forEach {
         gatherErrors(usageErrors, context) { it.postValidate(context) }
     }
     return usageErrors
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/internal/NullableLateinit.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/internal/NullableLateinit.kt
index 501c70db..e5e582ea 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/internal/NullableLateinit.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/internal/NullableLateinit.kt
@@ -15,13 +15,13 @@ internal class NullableLateinit<T>(private val errorMessage: String) : ReadWrite
     private var value: Any? = UNINITIALIZED
 
     override fun getValue(thisRef: Any, property: KProperty<*>): T {
-        if (value === UNINITIALIZED) throw IllegalStateException(errorMessage)
+        if (value === UNINITIALIZED) throw LateinitException(errorMessage)
 
         try {
             @Suppress("UNCHECKED_CAST")
             return value as T
         } catch (e: ClassCastException) {
-            throw IllegalStateException(errorMessage)
+            throw LateinitException(errorMessage)
         }
     }
 
@@ -29,3 +29,5 @@ internal class NullableLateinit<T>(private val errorMessage: String) : ReadWrite
         this.value = value
     }
 }
+
+internal class LateinitException(message: String) : IllegalStateException(message)
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 98175089..a408cb70 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -53,7 +53,7 @@ object CommandLineParser {
             invocation.argumentInvocations,
         ).throwErrors()
 
-        validateParameters(context, invocation.optionInvocations).throwErrors()
+        validateParameters(context, nonEagerInvs).throwErrors()
 
         if (subcommand == null && command._subcommands.isNotEmpty() &&
             !command.invokeWithoutSubcommand
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
index 421ed31e..5a572e52 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EagerOptionsTest.kt
@@ -8,6 +8,7 @@ import com.github.ajalt.clikt.parameters.groups.mutuallyExclusiveOptions
 import com.github.ajalt.clikt.parameters.groups.provideDelegate
 import com.github.ajalt.clikt.parameters.options.*
 import com.github.ajalt.clikt.testing.TestCommand
+import com.github.ajalt.clikt.testing.TestException
 import com.github.ajalt.clikt.testing.formattedMessage
 import com.github.ajalt.clikt.testing.parse
 import io.kotest.assertions.throwables.shouldThrow
@@ -48,20 +49,19 @@ class EagerOptionsTest {
     @JsName("eager_option_parse_order")
     fun `eager option parse order`() {
         class C : TestCommand(called = false) {
-            val o by option().flag().validate { error("fail") }
+            val o by option().flag().validate { throw TestException("fail") }
         }
 
-
         shouldThrow<PrintHelpMessage> { C().parse("-h --o") }
         shouldThrow<PrintHelpMessage> { C().parse("--o -h") }
-        shouldThrow<IllegalStateException> { C().parse("--o") }
+        shouldThrow<TestException> { C().parse("--o") }
     }
 
     @Test
     @JsName("eager_option_in_option_group_plain")
     fun `eager option in option group plain`() {
         class G : OptionGroup(name = "g") {
-            val x by option("-x", eager = true).flag().validate { error("fail") }
+            val x by option("-x", eager = true).flag().validate { throw TestException("fail") }
         }
 
         class C : TestCommand(called = false) {
@@ -70,8 +70,8 @@ class EagerOptionsTest {
         }
 
         shouldThrow<PrintHelpMessage> { C().parse("-hxy") }
-        shouldThrow<IllegalStateException> { C().parse("-xyh") }
-        shouldThrow<IllegalStateException> { C().parse("-yxh") }
+        shouldThrow<TestException> { C().parse("-xyh") }
+        shouldThrow<TestException> { C().parse("-yxh") }
     }
 
     @Test
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index 2d5a634f..674b8836 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -9,6 +9,8 @@ import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
 import kotlin.test.assertEquals
 
+class TestException(message: String) : Exception(message)
+
 open class TestCommand(
     called: Boolean = true,
     count: Int? = null,
@@ -66,3 +68,4 @@ fun <T : TestCommand> T.parse(argv: String): T {
     TestCommand.assertCalled(this)
     return this
 }
+

From 45c0d310a7f561f38810ad2276f32e42ee736925 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 3 Apr 2024 10:31:45 -0700
Subject: [PATCH 17/43] Add CommandLineParser.parseAndRun

---
 .../github/ajalt/clikt/core/CliktCommand.kt   |  7 +-----
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 22 +++++++++++++++++--
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index e77c636b..32a1a279 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -87,10 +87,5 @@ fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
  * You should use [main] instead unless you want to handle output yourself.
  */
 fun BaseCliktCommand<() -> Unit>.parse(argv: List<String>) {
-// TODO   generateCompletion()
-    val result = CommandLineParser.parse(this, argv)
-    for (invocation in result.invocations) {
-        CommandLineParser.finalize(invocation)
-        invocation.command.runner()
-    }
+    CommandLineParser.parseAndRun(this, argv) { it.runner() }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index a408cb70..55e12595 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,11 +16,28 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
+    inline fun <RunnerT> parseAndRun(
+        command: BaseCliktCommand<RunnerT>,
+        argv: List<String>,
+        crossinline run: (BaseCliktCommand<RunnerT>) -> Unit,
+    ) {
+// TODO   generateCompletion()
+        val result = parse(command, argv)
+        for (invocation in result.invocations) {
+            try {
+                finalize(invocation)
+                run(invocation.command)
+            } finally {
+                invocation.command.currentContext.close()
+            }
+        }
+    }
+
     // TODO: docs does not throw
     fun <RunnerT> parse(
-        command: BaseCliktCommand<RunnerT>, originalArgv: List<String>,
+        command: BaseCliktCommand<RunnerT>, argv: List<String>,
     ): CommandLineParseResult<RunnerT> {
-        return parseArgv(command, originalArgv)
+        return parseArgv(command, argv)
     }
 
     // TODO: docs throws
@@ -67,6 +84,7 @@ object CommandLineParser {
 
 private fun CommandInvocation<*>.throwErrors() {
     when (val first = errors.firstOrNull()) {
+        // TODO: check if there is ever an error after a UsageError
         is UsageError -> errors.takeWhile { it is UsageError }
             .filterIsInstance<UsageError>().throwErrors()
 

From d5d0a2f3998aad85b7dee39382f6a325eb873c1e Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 3 Apr 2024 11:14:42 -0700
Subject: [PATCH 18/43] Fix double validation of grouped options

---
 .../ajalt/clikt/internal/Finalization.kt      | 33 +++++++------------
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 19 +++++++----
 .../parameters/groups/OptionGroupsTest.kt     | 14 ++++++++
 3 files changed, 38 insertions(+), 28 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index 4f6c5b9b..53f50da4 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -23,7 +23,8 @@ internal fun finalizeOptions(
 private sealed class Param
 private data class Opt(val option: Option, val invs: List<Invocation>) : Param()
 private data class Arg(val argument: Argument, val invs: List<String>) : Param()
-private data class Group(val group: ParameterGroup, val invs: Map<Option, List<Invocation>>) : Param()
+private data class Group(val group: ParameterGroup, val invs: Map<Option, List<Invocation>>) :
+    Param()
 
 internal fun finalizeParameters(
     context: Context,
@@ -109,31 +110,21 @@ private fun iterateFinalization(
     return errors
 }
 
-internal fun validateOptions(
-    context: Context,
-    optionInvocations: Map<Option, List<Invocation>>,
-): List<UsageError> {
-    val usageErrors = mutableListOf<UsageError>()
-    optionInvocations.keys.forEach {
-        gatherErrors(usageErrors, context) { it.postValidate(context) }
-    }
-    return usageErrors
-}
-
 internal fun validateParameters(
     context: Context,
-    optionInvocations: Map<Option, List<Invocation>>,
+    options: Iterable<Option> = emptyList(),
+    groups: Iterable<ParameterGroup> = emptyList(),
+    arguments: Iterable<Argument> = emptyList(),
 ): List<UsageError> {
     val usageErrors = mutableListOf<UsageError>()
-    usageErrors += validateOptions(context, optionInvocations)
-    context.command.registeredParameterGroups().forEach {
-        gatherErrors(usageErrors, context) { it.postValidate(context) }
+    for (option in options) {
+        gatherErrors(usageErrors, context) { option.postValidate(context) }
+    }
+    for (group in groups) {
+        gatherErrors(usageErrors, context) { group.postValidate(context) }
     }
-    context.command.registeredArguments().forEach {
-        gatherErrors(
-            usageErrors,
-            context
-        ) { it.postValidate(context) }
+    for (argument in arguments) {
+        gatherErrors(usageErrors, context) { argument.postValidate(context) }
     }
     return usageErrors
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 55e12595..d693b5f2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,12 +16,13 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
+    // TODO: docs throws
     inline fun <RunnerT> parseAndRun(
         command: BaseCliktCommand<RunnerT>,
         argv: List<String>,
         crossinline run: (BaseCliktCommand<RunnerT>) -> Unit,
     ) {
-// TODO   generateCompletion()
+        // TODO   generateCompletion()
         val result = parse(command, argv)
         for (invocation in result.invocations) {
             try {
@@ -45,6 +46,8 @@ object CommandLineParser {
         val command = invocation.command
         val context = command.currentContext
         val subcommand = invocation.invokedSubcommand
+        val groups = command.registeredParameterGroups()
+        val arguments = command.registeredArguments()
 
         val (eagerOpts, nonEagerOpts) = command.registeredOptions()
             .partition { it.eager }
@@ -53,24 +56,26 @@ object CommandLineParser {
             .partition { it.key.eager }
             .toList().map { it.associate { (k, v) -> k to v } }
 
-        // finalize and validate eager options first
+        // finalize and validate eager options first; unlike other options, eager options only get
+        // validated if they're invoked
         finalizeOptions(context, eagerOpts, eagerInvs)
-        validateOptions(context, eagerInvs).throwErrors()
+        validateParameters(context, eagerInvs.keys).throwErrors()
 
         // throw any parse errors after the eager options are finalized
         invocation.throwErrors()
 
         // then finalize and validate everything else
+        val nonEagerNonGroupOpts = nonEagerOpts.filter { it.group == null }
         finalizeParameters(
             context,
-            nonEagerOpts.filter { it.group == null },
-            command.registeredParameterGroups(),
-            command.registeredArguments(),
+            nonEagerNonGroupOpts,
+            groups,
+            arguments,
             nonEagerInvs,
             invocation.argumentInvocations,
         ).throwErrors()
 
-        validateParameters(context, nonEagerInvs).throwErrors()
+        validateParameters(context, nonEagerNonGroupOpts, groups, arguments).throwErrors()
 
         if (subcommand == null && command._subcommands.isNotEmpty() &&
             !command.invokeWithoutSubcommand
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
index 96a30f87..93ebc810 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
@@ -368,6 +368,20 @@ class OptionGroupsTest {
         }
     }
 
+    @Test
+    @JsName("grouped_option_is_finalized_exactly_once")
+    fun `grouped option is finalized exactly once`() {
+        class G : OptionGroup() {
+            private var finalized = 0
+            val x by option().convert { ++finalized }
+        }
+
+        class C : TestCommand() {
+            val g by G()
+        }
+        C().parse("--x=1").g.x shouldBe 1
+    }
+
     @Test
     @JsName("plain_option_group_validation")
     fun `plain option group validation`() = forAll(

From 66dd09c45320de426d57b048d07ecb28d7914c14 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Fri, 5 Apr 2024 12:30:19 -0700
Subject: [PATCH 19/43] Report value errors during finalization

---
 CHANGELOG.md                                  |  1 +
 .../clikt/parameters/arguments/Argument.kt    |  6 +++
 .../ajalt/clikt/parameters/options/Option.kt  |  3 +-
 .../parameters/options/OptionWithValues.kt    | 11 +++--
 .../clikt/parameters/options/TransformEach.kt |  7 ++--
 .../ajalt/clikt/parsers/ParserInternals.kt    | 40 +++++++++----------
 .../ajalt/clikt/parameters/ArgumentTest.kt    | 10 +----
 .../clikt/parameters/EnvvarOptionsTest.kt     |  1 -
 .../clikt/parameters/MultiUsageErrorTest.kt   |  4 +-
 .../github/ajalt/clikt/testing/TestSource.kt  |  5 ++-
 10 files changed, 47 insertions(+), 41 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a43ff94..038b948e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 
 ### Changed
 - In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
+- Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
index dc53ba90..84d87c6c 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt
@@ -196,6 +196,12 @@ class ProcessedArgumentImpl<AllT, ValueT> internal constructor(
 
     override fun finalize(context: Context, values: List<String>) {
         val ctx = ArgumentTransformContext(this, context)
+        if (required) {
+            when {
+                values.isEmpty() -> throw MissingArgument(this)
+                nvalues > 0 && values.size != nvalues -> throw IncorrectArgumentValueCount(this)
+            }
+        }
         value = transformAll(ctx, values.map { transformValue(ctx, it) })
     }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
index 3eec350b..ed95529b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
@@ -152,7 +152,8 @@ internal fun Option.getFinalValue(
     envvar: String?,
 ): FinalValue {
     return when {
-        invocations.isNotEmpty() -> FinalValue.Parsed(invocations)
+        // We don't look at envvars or the value source for eager options
+        eager || invocations.isNotEmpty() -> FinalValue.Parsed(invocations)
         context.readEnvvarBeforeValueSource -> {
             readEnvVar(context, envvar) ?: readValueSource(context)
         }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
index e2ef71ff..368fcba6 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
@@ -192,10 +192,15 @@ private class OptionWithValuesImpl<AllT, EachT, ValueT>(
     }
 
     override fun finalize(context: Context, invocations: List<Invocation>) {
-        val inv = when (val v = getFinalValue(context, invocations, envvar)) {
+        val invs = when (val v = getFinalValue(context, invocations, envvar)) {
             is FinalValue.Parsed -> {
                 when (valueSplit) {
-                    null -> invocations
+                    null -> {
+                        invocations.find { it.values.size !in nvalues }?.let {
+                            throw IncorrectOptionValueCount(this, it.name)
+                        }
+                        invocations
+                    }
                     else -> invocations.map { inv ->
                         inv.copy(values = inv.values.flatMap { it.split(valueSplit) })
                     }
@@ -214,7 +219,7 @@ private class OptionWithValuesImpl<AllT, EachT, ValueT>(
             }
         }
 
-        value = transformAll(OptionTransformContext(this, context), inv.map {
+        value = transformAll(OptionTransformContext(this, context), invs.map {
             val tc = OptionCallTransformContext(it.name, this, context)
             transformEach(tc, it.values.map { v -> transformValue(tc, v) })
         })
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/TransformEach.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/TransformEach.kt
index 225433c1..51891442 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/TransformEach.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/TransformEach.kt
@@ -26,10 +26,9 @@ fun <EachT, ValueT> NullableOption<ValueT, ValueT>.transformValues(
         transformEach = transform,
         transformAll = defaultAllProcessor(),
         validator = defaultValidator(),
-        metavarGetter = if (nvalues == 0..0) {
-            { null }
-        } else {
-            metavarGetter
+        metavarGetter = when (nvalues) {
+            0..0 -> { { null } }
+            else -> { metavarGetter }
         },
         nvalues = nvalues
     )
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 0e4fd551..24ebcd9d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -18,11 +18,6 @@ internal fun <RunnerT> parseArgv(
         val commandResult = CommandParser(command, parent, expandedArgv, i).parse()
         i = commandResult.i
         expandedArgv = commandResult.expandedArgv
-        if (commandResult.errors.isNotEmpty()) command.currentContext.errorEncountered = true
-
-        for (e in commandResult.errors) {
-            if (e is UsageError) e.context = e.context ?: command.currentContext
-        }
         results += CommandInvocation(
             command,
             commandResult.optInvocations,
@@ -30,11 +25,19 @@ internal fun <RunnerT> parseArgv(
             commandResult.subcommand,
             commandResult.errors
         )
+        for (e in commandResult.errors) {
+            if (e is UsageError) e.context = e.context ?: command.currentContext
+        }
+        if (commandResult.errors.isNotEmpty()) {
+            command.currentContext.errorEncountered = true
+            break
+        }
         command = commandResult.subcommand
     }
-    check(results.isNotEmpty())
-    if (i != expandedArgv.size) {
-        val lastResult = results.last()
+    // TODO: pretty sure we can remove this
+    val lastResult = results.last()
+    if (lastResult.errors.isEmpty() && i != expandedArgv.size) {
+        // Only report trailing tokens if the last command didn't have any errors,
         val error = NoSuchArgument(expandedArgv.drop(i + 1)).also {
             it.context = lastResult.command.currentContext
         }
@@ -289,14 +292,8 @@ private class CommandParser<RunnerT>(
             values += tok
         }
 
+        // This might not be enough values for the option, but we'll report that during finalization
         val consumed = values.size + if (attachedValue == null) 1 else 0
-        if (values.size !in option.nvalues) {
-            return OptParseResult(
-                consumed,
-                err = IncorrectOptionValueCount(option, name)
-            )
-        }
-
         return OptParseResult(consumed, option, name, values)
     }
 
@@ -316,16 +313,15 @@ private class CommandParser<RunnerT>(
                 else -> argument.nvalues
             }
 
+            val toIndex = (tokenI + consumed).coerceAtMost(argumentTokens.size)
+            val values = argumentTokens.subList(tokenI, toIndex)
+            argInvocations += ArgumentInvocation(argument, values)
+
             if (consumed > remaining) {
-                val e = when (remaining) {
-                    0 -> MissingArgument(argument)
-                    else -> IncorrectArgumentValueCount(argument)
-                }
-                errors += e
+                // Not enough values for remaining args, we'll report it during finalization
                 return
             }
-            val values = argumentTokens.subList(tokenI, tokenI + consumed)
-            argInvocations += ArgumentInvocation(argument, values)
+
             tokenI += consumed
         }
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
index ce64829b..506db9aa 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
@@ -480,10 +480,7 @@ class ArgumentTest {
         class C : TestCommand(called = false) {
             val x by argument()
         }
-        shouldThrow<MultiUsageError> { C().parse("-foo") }.errors.let {
-            it[0].shouldBeInstanceOf<NoSuchOption>()
-            it[1].shouldBeInstanceOf<MissingArgument>()
-        }
+        shouldThrow<NoSuchOption> { C().parse("-foo") }
     }
 
     @Test
@@ -516,10 +513,7 @@ class ArgumentTest {
 
             val x by argument()
         }
-        shouldThrow<MultiUsageError> { C().parse("/foo") }.errors.let {
-            it[0].shouldBeInstanceOf<NoSuchOption>()
-            it[1].shouldBeInstanceOf<MissingArgument>()
-        }
+        shouldThrow<NoSuchOption> { C().parse("/foo") }
     }
 
     @Test
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EnvvarOptionsTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EnvvarOptionsTest.kt
index 09d4baa5..629135b9 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EnvvarOptionsTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/EnvvarOptionsTest.kt
@@ -109,7 +109,6 @@ class EnvvarOptionsTest {
     @Test
     @JsName("split_envvar")
     fun `split envvar`() {
-
         class C : TestCommand() {
             val foo by option(envvar = "FOO")
             val bar by option(envvar = "BAR").split(";")
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
index b2444404..66a41194 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
@@ -11,6 +11,7 @@ import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
 import com.github.ajalt.clikt.parameters.types.int
 import com.github.ajalt.clikt.testing.TestCommand
+import com.github.ajalt.clikt.testing.formattedMessage
 import com.github.ajalt.clikt.testing.parse
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.data.blocking.forAll
@@ -37,6 +38,7 @@ class MultiUsageErrorTest {
         class C : TestCommand(called = false) {
             val x by option().int().required().check { it == 0 }
             val y by option().int().required().check { it == 0 }
+            // TODO: parseArguments and handleExcessArgs used to be part of the finalization step.
             val a by argument().int().check { it == 0 }
         }
 
@@ -44,7 +46,7 @@ class MultiUsageErrorTest {
             C().parse(argv)
         }
         ((e as? MultiUsageError)?.errors ?: listOf(e))
-            .map { er -> er.formatMessage(defaultLocalization, ParameterFormatter.Plain) }
+            .map { it.formattedMessage }
             .shouldBe(ex)
     }
 }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestSource.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestSource.kt
index 681b0e9d..efae4976 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestSource.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestSource.kt
@@ -4,6 +4,7 @@ import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.sources.MapValueSource
 import com.github.ajalt.clikt.sources.ValueSource
+import io.kotest.assertions.withClue
 import io.kotest.matchers.shouldBe
 
 class TestSource(vararg values: Pair<String, String>) : ValueSource {
@@ -16,6 +17,8 @@ class TestSource(vararg values: Pair<String, String>) : ValueSource {
     }
 
     fun assert(read: Boolean) {
-        this.read shouldBe read
+        withClue("ValueSource read") {
+            this.read shouldBe read
+        }
     }
 }

From 065b7081e67163327fa4b6e04b48d3bc64be8cc0 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 6 Apr 2024 10:55:47 -0700
Subject: [PATCH 20/43] Reenable completion generation

---
 .../clikt/completion/CompletionGenerator.kt   |  7 +++--
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 14 +---------
 .../github/ajalt/clikt/core/CliktCommand.kt   |  1 +
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 21 ++++++++++----
 .../github/ajalt/clikt/parsers/Invocation.kt  |  5 ++++
 .../ajalt/clikt/parsers/ParserInternals.kt    | 28 +++++++++++++++++--
 6 files changed, 53 insertions(+), 23 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
index 4c9144f8..04bba838 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt
@@ -1,11 +1,14 @@
 package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.PrintCompletionMessage
 
 internal object CompletionGenerator {
     fun throwCompletionMessage(command: BaseCliktCommand<*>, shell: String): Nothing {
+        throw getCompletionMessage(command, shell)
+    }
+
+    fun getCompletionMessage(command: BaseCliktCommand<*>, shell: String): PrintCompletionMessage {
         val message = when (shell.trim().lowercase()) {
             "fish" -> FishCompletionGenerator.generateFishCompletion(command = command)
             "zsh" -> BashCompletionGenerator.generateBashOrZshCompletion(
@@ -18,6 +21,6 @@ internal object CompletionGenerator {
                 zsh = false
             )
         }
-        throw PrintCompletionMessage(message)
+        return PrintCompletionMessage(message)
     }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 66bc8b40..c52e9333 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -50,7 +50,7 @@ abstract class BaseCliktCommand<RunnerT>(
      * The envvar to use to enable shell autocomplete script generation. Set to null to disable
      * generation.
      */
-    private val autoCompleteEnvvar: String? = "",
+    internal val autoCompleteEnvvar: String? = "",
     /**
      * If true, allow multiple of this command's subcommands to be called sequentially. This will
      * disable `allowInterspersedArgs` on the context of this command and its descendants.
@@ -181,18 +181,6 @@ abstract class BaseCliktCommand<RunnerT>(
         return currentContext.commandNameWithParents().joinToString(" ")
     }
 
-    private fun generateCompletion() {
-        if (autoCompleteEnvvar == null) return
-        val envvar = when {
-            autoCompleteEnvvar.isBlank() -> "_${commandName.replace("-", "_").uppercase()}_COMPLETE"
-            else -> autoCompleteEnvvar
-        }
-
-        val envval = currentContext.readEnvvar(envvar) ?: return
-
-        CompletionGenerator.throwCompletionMessage(this, envval)
-    }
-
     /**
      * This command's context.
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 32a1a279..8d112853 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -2,6 +2,7 @@ package com.github.ajalt.clikt.core
 
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parsers.CommandLineParseResult
 import com.github.ajalt.clikt.parsers.CommandLineParser
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index d693b5f2..3e1500fe 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,18 +16,27 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
-    // TODO: docs throws
-    inline fun <RunnerT> parseAndRun(
+    /**
+     * A shortcut for calling `run(parse(command, argv), runCommand)`
+     */
+    fun <RunnerT> parseAndRun(
         command: BaseCliktCommand<RunnerT>,
         argv: List<String>,
-        crossinline run: (BaseCliktCommand<RunnerT>) -> Unit,
+        runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
+    ) {
+        run(parse(command, argv), runCommand)
+    }
+
+    // TODO: docs throws
+    fun <RunnerT> run(
+        result: CommandLineParseResult<RunnerT>,
+        runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
     ) {
-        // TODO   generateCompletion()
-        val result = parse(command, argv)
+        result.throwError()
         for (invocation in result.invocations) {
             try {
                 finalize(invocation)
-                run(invocation.command)
+                runCommand(invocation.command)
             } finally {
                 invocation.command.currentContext.close()
             }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 27ebbb47..7f671446 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -30,4 +30,9 @@ class CommandLineParseResult<RunnerT>(
     val invocations: List<CommandInvocation<RunnerT>>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
+    val error: CliktError?,
 )
+
+fun CommandLineParseResult<*>.throwError() {
+    error?.let { throw it }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 24ebcd9d..ab076211 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -1,5 +1,6 @@
 package com.github.ajalt.clikt.parsers
 
+import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
@@ -8,7 +9,14 @@ internal fun <RunnerT> parseArgv(
     rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
-    rootCommand.resetContext(null)
+    val rootContext = rootCommand.resetContext(null)
+
+    generateCompletion(rootContext, rootCommand)?.let {
+        return@parseArgv CommandLineParseResult(
+            emptyList(), originalArgv, originalArgv, it
+        )
+    }
+
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
     var command: BaseCliktCommand<RunnerT>? = rootCommand
@@ -43,7 +51,23 @@ internal fun <RunnerT> parseArgv(
         }
         results[results.lastIndex] = lastResult.copy(errors = lastResult.errors + error)
     }
-    return CommandLineParseResult(results, originalArgv, expandedArgv)
+    return CommandLineParseResult(results, originalArgv, expandedArgv, null)
+}
+
+private fun generateCompletion(
+    context: Context,
+    command: BaseCliktCommand<*>,
+): PrintCompletionMessage? {
+    if (command.autoCompleteEnvvar == null) return null
+    val envvar = when {
+        command.autoCompleteEnvvar.isBlank() -> "_${
+            command.commandName.replace("-", "_").uppercase()
+        }_COMPLETE"
+
+        else -> command.autoCompleteEnvvar
+    }
+    val envval = context.readEnvvar(envvar) ?: return null
+    return CompletionGenerator.getCompletionMessage(command, envval)
 }
 
 private class CommandParser<RunnerT>(

From 45db14362807cf3626bb7dfa1184500842299331 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 6 Apr 2024 11:09:23 -0700
Subject: [PATCH 21/43] Deprecate Context.originalArgv

---
 CHANGELOG.md                                     |  3 +++
 .../github/ajalt/clikt/core/BaseCliktCommand.kt  |  4 +---
 .../com/github/ajalt/clikt/core/Context.kt       | 12 ++++++------
 .../com/github/ajalt/clikt/core/ContextTest.kt   | 16 ----------------
 4 files changed, 10 insertions(+), 25 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 038b948e..2a5de543 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,9 @@
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
 
+### Deprecated
+- Deprecated `Context.originalArgv`. It will now always return an empty list. If your commands need an argv, you can pass it to them before you run them.
+
 ## 4.3.0
 ### 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))
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index c52e9333..abf910cb 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -1,6 +1,5 @@
 package com.github.ajalt.clikt.core
 
-import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.arguments.argument
@@ -129,8 +128,7 @@ abstract class BaseCliktCommand<RunnerT>(
      */
     fun resetContext(parent: Context?): Context {
         _context?.close()
-        // TODO either pass argv or remove it from ctx
-        val ctx = Context.build(this, parent, emptyList(), _contextConfig)
+        val ctx = Context.build(this, parent, _contextConfig)
         _context = ctx
 
         if (allowMultipleSubcommands) {
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 cf4b9cd9..6f111c22 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
@@ -107,10 +107,6 @@ class Context private constructor(
      * can also set the object on the context itself after it's been constructed.
      */
     var obj: Any?,
-    /**
-     * The original command line arguments.
-     */
-    val originalArgv: List<String>,
 ) {
     /**
      * If this command has subcommands and one of them was invoked, this is the subcommand that will
@@ -212,6 +208,12 @@ class Context private constructor(
      */
     val expandArgumentFiles: Boolean get() = argumentFileReader != null
 
+    /**
+     * The original command line arguments.
+     */
+    @Deprecated("This property is deprecated and will be removed in the future. It will now always return an empty list. If your commands need an argv, you can pass it to them before they are run.")
+    val originalArgv: List<String> = emptyList()
+
     override fun toString(): String {
         return "Context(command=${command.commandName}, parent=${parent?.command?.commandName})"
     }
@@ -346,7 +348,6 @@ class Context private constructor(
         internal fun build(
             command: BaseCliktCommand<*>,
             parent: Context?,
-            argv: List<String>,
             block: Builder.() -> Unit,
         ): Context {
             with(Builder(command, parent)) {
@@ -375,7 +376,6 @@ class Context private constructor(
                     localization = localization,
                     readEnvvar = envvarReader,
                     obj = obj,
-                    originalArgv = argv
                 )
             }
         }
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 889cfa8a..65cf3589 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
@@ -104,22 +104,6 @@ class ContextTest {
         }
     }
 
-    @Test
-    fun originalArgv() {
-        class C : TestCommand()
-        class S : TestCommand() {
-            val opt by option()
-            val args by argument().multiple()
-            override fun run_() {
-                opt shouldBe "o"
-                args shouldBe listOf("1", "2")
-                currentContext.originalArgv shouldBe listOf("s", "--opt", "o", "1", "2")
-            }
-        }
-
-        C().subcommands(S()).parse("s --opt o 1 2")
-    }
-
     @Test
     @JsName("assign_obj_through_context_builder")
     fun `assign obj through context builder`() {

From 012078a651b9967285277dae636bf4aaf3b84c7f Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 7 Apr 2024 10:15:12 -0700
Subject: [PATCH 22/43] Move completion check to finalize

---
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 24 ++++++++++++++---
 .../ajalt/clikt/parsers/ParserInternals.kt    | 27 +------------------
 2 files changed, 21 insertions(+), 30 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 3e1500fe..17d3b6f5 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -1,9 +1,7 @@
 package com.github.ajalt.clikt.parsers
 
-import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktError
-import com.github.ajalt.clikt.core.PrintHelpMessage
-import com.github.ajalt.clikt.core.UsageError
+import com.github.ajalt.clikt.completion.CompletionGenerator
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.*
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
@@ -58,6 +56,8 @@ object CommandLineParser {
         val groups = command.registeredParameterGroups()
         val arguments = command.registeredArguments()
 
+        throwCompletionMessageIfRequsted(context, command)
+
         val (eagerOpts, nonEagerOpts) = command.registeredOptions()
             .partition { it.eager }
 
@@ -105,3 +105,19 @@ private fun CommandInvocation<*>.throwErrors() {
         is CliktError -> throw first
     }
 }
+
+private fun throwCompletionMessageIfRequsted(
+    context: Context,
+    command: BaseCliktCommand<*>,
+) {
+    if (command.autoCompleteEnvvar == null) return
+    val envvar = when {
+        command.autoCompleteEnvvar.isBlank() -> "_${
+            command.commandName.replace("-", "_").uppercase()
+        }_COMPLETE"
+
+        else -> command.autoCompleteEnvvar
+    }
+    val envval = context.readEnvvar(envvar) ?: return
+    throw CompletionGenerator.getCompletionMessage(command, envval)
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index ab076211..94e101ee 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -1,6 +1,5 @@
 package com.github.ajalt.clikt.parsers
 
-import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
@@ -9,14 +8,6 @@ internal fun <RunnerT> parseArgv(
     rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
-    val rootContext = rootCommand.resetContext(null)
-
-    generateCompletion(rootContext, rootCommand)?.let {
-        return@parseArgv CommandLineParseResult(
-            emptyList(), originalArgv, originalArgv, it
-        )
-    }
-
     val results = mutableListOf<CommandInvocation<RunnerT>>()
     var expandedArgv = originalArgv
     var command: BaseCliktCommand<RunnerT>? = rootCommand
@@ -54,22 +45,6 @@ internal fun <RunnerT> parseArgv(
     return CommandLineParseResult(results, originalArgv, expandedArgv, null)
 }
 
-private fun generateCompletion(
-    context: Context,
-    command: BaseCliktCommand<*>,
-): PrintCompletionMessage? {
-    if (command.autoCompleteEnvvar == null) return null
-    val envvar = when {
-        command.autoCompleteEnvvar.isBlank() -> "_${
-            command.commandName.replace("-", "_").uppercase()
-        }_COMPLETE"
-
-        else -> command.autoCompleteEnvvar
-    }
-    val envval = context.readEnvvar(envvar) ?: return null
-    return CompletionGenerator.getCompletionMessage(command, envval)
-}
-
 private class CommandParser<RunnerT>(
     private val command: BaseCliktCommand<RunnerT>,
     parentContext: Context?,
@@ -77,7 +52,7 @@ private class CommandParser<RunnerT>(
     startingIndex: Int,
 ) {
     private var tokens = argv
-    private val context = command.currentContext
+    private val context = command.resetContext(parentContext)
     private val aliases = command.aliases()
     private val extraSubcommands = parentContext?.selfAndAncestors()
         ?.firstOrNull { it.command.allowMultipleSubcommands }?.command

From 0ca8c89515bb407a4f9acfef8035f534f92affae Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 7 Apr 2024 10:08:53 -0700
Subject: [PATCH 23/43] Implement Context.invokedSubcommands and close

---
 .../ajalt/clikt/parsers/CommandLineParser.kt     |  1 +
 .../ajalt/clikt/parsers/ParserInternals.kt       |  9 ---------
 .../ajalt/clikt/parameters/SubcommandTest.kt     | 16 ++++++++++++++--
 .../github/ajalt/clikt/testing/TestCommand.kt    |  7 +++++--
 4 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 17d3b6f5..dc101427 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -6,6 +6,7 @@ import com.github.ajalt.clikt.internal.*
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
+// TODO: docs, changelog
 object CommandLineParser {
     fun tokenize(
         commandLine: String,
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 94e101ee..876e30b5 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -33,15 +33,6 @@ internal fun <RunnerT> parseArgv(
         }
         command = commandResult.subcommand
     }
-    // TODO: pretty sure we can remove this
-    val lastResult = results.last()
-    if (lastResult.errors.isEmpty() && i != expandedArgv.size) {
-        // Only report trailing tokens if the last command didn't have any errors,
-        val error = NoSuchArgument(expandedArgv.drop(i + 1)).also {
-            it.context = lastResult.command.currentContext
-        }
-        results[results.lastIndex] = lastResult.copy(errors = lastResult.errors + error)
-    }
     return CommandLineParseResult(results, originalArgv, expandedArgv, null)
 }
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index b4e86a53..02a7d47b 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -345,6 +345,9 @@ class SubcommandTest {
         foo.arg shouldBe "f2"
         bar.opt shouldBe null
         bar.arg shouldBe "b2"
+
+        foo.invokedSubcommands shouldBe listOf(bar, bar)
+        bar.invokedSubcommands shouldBe listOf(null, null)
     }
 
     @Test
@@ -357,6 +360,9 @@ class SubcommandTest {
         bar1.arg shouldBe "a12"
         bar2.opt shouldBe "o"
         bar2.arg shouldBe "a22"
+
+        bar1.invokedSubcommands shouldBe listOf(bar2, bar2)
+        bar2.invokedSubcommands shouldBe listOf(null, null)
     }
 
     @Test
@@ -402,9 +408,14 @@ class SubcommandTest {
             }
         }
 
-        val c = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
+        val foo = MultiSubFoo(1)
+        val bar = MultiSubBar(1)
+        val c = C().subcommands(foo, bar)
         c.parse("--x=xx foo 1 bar 2")
         c.x shouldBe "xx"
+        foo.invokedSubcommands shouldBe listOf(null)
+        bar.invokedSubcommands shouldBe listOf(null)
+        c.invokedSubcommands shouldBe listOf(foo)
 
         val c2 = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
         shouldThrow<NoSuchArgument> {
@@ -431,7 +442,8 @@ class SubcommandTest {
     fun `multiple subcommands with excess arguments`() {
         val sub = TestCommand(name = "sub", called = true)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(sub)
-        shouldThrow<UsageError> {
+        c.parse("sub foo")
+        shouldThrow<NoSuchArgument> {
             c.parse("sub foo")
         }.formattedMessage shouldBe "got unexpected extra argument (foo)"
     }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index 674b8836..ad689a37 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -43,9 +43,12 @@ open class TestCommand(
     }
 
     private val count = count ?: if (called) 1 else 0
-    private var actualCount = 0
+    private val invoked = mutableListOf<BaseCliktCommand<*>?>()
+    val invokedSubcommands: List<BaseCliktCommand<*>?> get() = invoked
+    private val actualCount get() = invoked.size
+
     final override fun run() {
-        actualCount++
+        invoked += currentContext.invokedSubcommand
         run_()
     }
 

From b49b8c054aee47e3ed1af54241e16c1c55d52663 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 9 Apr 2024 12:48:58 -0700
Subject: [PATCH 24/43] make parse results recursive

---
 .../ajalt/clikt/core/BaseCliktCommand.kt      |  4 +-
 .../github/ajalt/clikt/core/CliktCommand.kt   |  7 +-
 .../com/github/ajalt/clikt/core/Context.kt    | 23 +++++-
 .../com/github/ajalt/clikt/core/execution.kt  | 16 ----
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 60 ++++++++------
 .../github/ajalt/clikt/parsers/Invocation.kt  |  9 +--
 .../ajalt/clikt/parsers/ParserInternals.kt    | 79 ++++++++++++-------
 .../ajalt/clikt/core/CliktCommandTest.kt      |  5 +-
 .../ajalt/clikt/parameters/SubcommandTest.kt  | 24 +++++-
 9 files changed, 141 insertions(+), 86 deletions(-)
 delete mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index abf910cb..49cb41c1 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -126,7 +126,7 @@ abstract class BaseCliktCommand<RunnerT>(
      *
      * @return The new context.
      */
-    fun resetContext(parent: Context?): Context {
+    fun resetContext(parent: Context? = null): Context {
         _context?.close()
         val ctx = Context.build(this, parent, _contextConfig)
         _context = ctx
@@ -278,7 +278,7 @@ abstract class BaseCliktCommand<RunnerT>(
         _groups += group
     }
 
-
+    // TODO: all of these final functions could be extensions?
     /**
      * Return the help string for this command, optionally with an [error].
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 8d112853..c0c02dae 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -2,7 +2,6 @@ package com.github.ajalt.clikt.core
 
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
-import com.github.ajalt.clikt.parsers.CommandLineParseResult
 import com.github.ajalt.clikt.parsers.CommandLineParser
 
 /**
@@ -60,7 +59,9 @@ abstract class CliktCommand(
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asList())
+fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) {
+    CommandLineParser.main(this, argv) { parse(argv) }
+}
 
 /**
  * Parse the command line and print helpful output if any errors occur.
@@ -71,7 +72,7 @@ fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asLis
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) = main(argv) { parse(argv) }
+fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asList())
 
 /**
  * Parse the command line and throw an exception if parsing fails.
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 6f111c22..dcb06e18 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
@@ -108,13 +108,28 @@ class Context private constructor(
      */
     var obj: Any?,
 ) {
+
+    // TODO: add this to web docs and changelog
     /**
-     * If this command has subcommands and one of them was invoked, this is the subcommand that will
-     * be run next.
+     * All invoked subcommands, in the order they were invoked.
+     *
+     * If `allowMultipleSubcommands=false`, this will have at most one entry. If
+     * `allowMultipleSubcommands=true`, the same command can appear in the list more than once.
      */
-    var invokedSubcommand: BaseCliktCommand<*>? = null
+    var invokedSubcommands: List<BaseCliktCommand<*>> = emptyList()
         internal set
 
+    /**
+     * If this command has subcommands and one of them was invoked, this is the subcommand that will
+     * be run first.
+     *
+     * If `allowMultipleSubcommands=true` on this command, you can use [invokedSubcommands] to get
+     * all invoked subcommands.
+     */
+    val invokedSubcommand: BaseCliktCommand<*>? get() = invokedSubcommands.firstOrNull()
+
+
+
     /**
      * If true, an error was previously encountered while parsing the command line, but parsing is
      * continuing to collect any more errors into a [MultiUsageError].
@@ -428,7 +443,7 @@ inline fun <reified T : Any> BaseCliktCommand<*>.findObject(): ReadOnlyProperty<
  */
 @Suppress("UnusedReceiverParameter")
 inline fun <reified T : Any> BaseCliktCommand<*>.findOrSetObject(
-    crossinline default: () -> T
+    crossinline default: () -> T,
 ): ReadOnlyProperty<BaseCliktCommand<*>, T> {
     return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findOrSetObject(default) }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
deleted file mode 100644
index cee8f8b7..00000000
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/execution.kt
+++ /dev/null
@@ -1,16 +0,0 @@
-package com.github.ajalt.clikt.core
-
-import com.github.ajalt.clikt.mpp.exitProcessMpp
-
-// TODO: docs
-fun <RunnerT> BaseCliktCommand<RunnerT>.main(
-    argv: List<String>,
-    parse: BaseCliktCommand<RunnerT>.(List<String>) -> Unit,
-) {
-    try {
-        parse(argv)
-    } catch (e: CliktError) {
-        echoFormattedHelp(e)
-        exitProcessMpp(e.statusCode)
-    }
-}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index dc101427..2d235cf4 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -3,6 +3,7 @@ package com.github.ajalt.clikt.parsers
 import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.*
+import com.github.ajalt.clikt.mpp.exitProcessMpp
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
@@ -15,30 +16,47 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
+    fun <RunnerT> main(
+        command: BaseCliktCommand<RunnerT>,
+        argv: List<String>,
+        parseAndRun: BaseCliktCommand<RunnerT>.(List<String>) -> Unit,
+    ) {
+        try {
+            command.parseAndRun(argv)
+        } catch (e: CliktError) {
+            command.echoFormattedHelp(e)
+            exitProcessMpp(e.statusCode)
+        }
+    }
+
+
     /**
-     * A shortcut for calling `run(parse(command, argv), runCommand)`
+     * A shortcut for calling `run(parse(command, argv).invocation, runCommand)`
      */
     fun <RunnerT> parseAndRun(
         command: BaseCliktCommand<RunnerT>,
         argv: List<String>,
         runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
-    ) {
-        run(parse(command, argv), runCommand)
+    ): CommandLineParseResult<RunnerT> {
+        val result = parse(command, argv)
+        run(result.invocation, runCommand)
+        return result
     }
 
     // TODO: docs throws
     fun <RunnerT> run(
-        result: CommandLineParseResult<RunnerT>,
+        invocation: CommandInvocation<RunnerT>,
         runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
     ) {
-        result.throwError()
-        for (invocation in result.invocations) {
-            try {
-                finalize(invocation)
-                runCommand(invocation.command)
-            } finally {
-                invocation.command.currentContext.close()
+        try {
+            finalize(invocation)
+            runCommand(invocation.command)
+
+            for (subcommandInvocation in invocation.subcommandInvocations) {
+                run(subcommandInvocation, runCommand)
             }
+        } finally {
+            invocation.command.currentContext.close()
         }
     }
 
@@ -53,11 +71,10 @@ object CommandLineParser {
     fun finalize(invocation: CommandInvocation<*>) {
         val command = invocation.command
         val context = command.currentContext
-        val subcommand = invocation.invokedSubcommand
         val groups = command.registeredParameterGroups()
         val arguments = command.registeredArguments()
 
-        throwCompletionMessageIfRequsted(context, command)
+        throwCompletionMessageIfRequested(context, command)
 
         val (eagerOpts, nonEagerOpts) = command.registeredOptions()
             .partition { it.eager }
@@ -76,24 +93,21 @@ object CommandLineParser {
 
         // then finalize and validate everything else
         val nonEagerNonGroupOpts = nonEagerOpts.filter { it.group == null }
+        val argumentInvocations = invocation.argumentInvocations
         finalizeParameters(
-            context,
-            nonEagerNonGroupOpts,
-            groups,
-            arguments,
-            nonEagerInvs,
-            invocation.argumentInvocations,
+            context, nonEagerNonGroupOpts, groups, arguments, nonEagerInvs, argumentInvocations
         ).throwErrors()
 
         validateParameters(context, nonEagerNonGroupOpts, groups, arguments).throwErrors()
 
-        if (subcommand == null && command._subcommands.isNotEmpty() &&
-            !command.invokeWithoutSubcommand
+        if (invocation.subcommandInvocations.isEmpty()
+            && command._subcommands.isNotEmpty()
+            && !command.invokeWithoutSubcommand
         ) {
             throw PrintHelpMessage(context, error = true)
         }
 
-        context.invokedSubcommand = subcommand
+        context.invokedSubcommands = invocation.subcommandInvocations.map { it.command }
     }
 }
 
@@ -107,7 +121,7 @@ private fun CommandInvocation<*>.throwErrors() {
     }
 }
 
-private fun throwCompletionMessageIfRequsted(
+private fun throwCompletionMessageIfRequested(
     context: Context,
     command: BaseCliktCommand<*>,
 ) {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 7f671446..f50e0e85 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -22,17 +22,12 @@ data class CommandInvocation<RunnerT>(
     val command: BaseCliktCommand<RunnerT>,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
-    val invokedSubcommand: BaseCliktCommand<RunnerT>?,
+    val subcommandInvocations: List<CommandInvocation<RunnerT>>,
     val errors: List<CliktError>,
 )
 
 class CommandLineParseResult<RunnerT>(
-    val invocations: List<CommandInvocation<RunnerT>>,
+    val invocation: CommandInvocation<RunnerT>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
-    val error: CliktError?,
 )
-
-fun CommandLineParseResult<*>.throwError() {
-    error?.let { throw it }
-}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 876e30b5..1df24fe7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -8,34 +8,41 @@ internal fun <RunnerT> parseArgv(
     rootCommand: BaseCliktCommand<RunnerT>,
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
-    val results = mutableListOf<CommandInvocation<RunnerT>>()
-    var expandedArgv = originalArgv
-    var command: BaseCliktCommand<RunnerT>? = rootCommand
-    var i = 0
-    while (command != null) {
-        val parent = results.lastOrNull()?.command?.currentContext
-        val commandResult = CommandParser(command, parent, expandedArgv, i).parse()
-        i = commandResult.i
-        expandedArgv = commandResult.expandedArgv
-        results += CommandInvocation(
-            command,
-            commandResult.optInvocations,
-            commandResult.argInvocations,
-            commandResult.subcommand,
-            commandResult.errors
-        )
-        for (e in commandResult.errors) {
-            if (e is UsageError) e.context = e.context ?: command.currentContext
-        }
-        if (commandResult.errors.isNotEmpty()) {
-            command.currentContext.errorEncountered = true
-            break
-        }
-        command = commandResult.subcommand
+    rootCommand.resetContext()
+    val result = parseCommandArgv(rootCommand, null, originalArgv, 0)
+    return CommandLineParseResult(result.invocation, originalArgv, result.argv)
+}
+
+/** Parse argv for the command, and recursively for its invoked subcommands */
+private fun <RunnerT> parseCommandArgv(
+    command: BaseCliktCommand<RunnerT>,
+    parent: Context?,
+    argv: List<String>,
+    i: Int,
+): CommandArgvParseResult<RunnerT> {
+    val rootResult = CommandParser(command, parent, argv, i).parse()
+    val subcommands = mutableListOf<CommandInvocation<RunnerT>>()
+    var nextCommand: BaseCliktCommand<RunnerT>? = rootResult.nextCommand
+    var nextArgv = rootResult.expandedArgv
+    var nextI = rootResult.i
+    while (nextCommand != null) {
+        val result = parseCommandArgv(nextCommand, command.currentContext, nextArgv, nextI)
+        nextCommand = result.nextCommand
+        nextArgv = result.argv
+        nextI = result.i
+        subcommands += result.invocation
     }
-    return CommandLineParseResult(results, originalArgv, expandedArgv, null)
+
+    return CommandArgvParseResult(rootResult.toInvocation(subcommands), nextCommand, argv, i)
 }
 
+private class CommandArgvParseResult<RunnerT>(
+    val invocation: CommandInvocation<RunnerT>,
+    val nextCommand: BaseCliktCommand<RunnerT>?,
+    val argv: List<String>,
+    val i: Int,
+)
+
 private class CommandParser<RunnerT>(
     private val command: BaseCliktCommand<RunnerT>,
     parentContext: Context?,
@@ -43,7 +50,7 @@ private class CommandParser<RunnerT>(
     startingIndex: Int,
 ) {
     private var tokens = argv
-    private val context = command.resetContext(parentContext)
+    private val context = command.currentContext
     private val aliases = command.aliases()
     private val extraSubcommands = parentContext?.selfAndAncestors()
         ?.firstOrNull { it.command.allowMultipleSubcommands }?.command
@@ -169,7 +176,12 @@ private class CommandParser<RunnerT>(
 
     private fun makeResult(): CommandParseResult<RunnerT> {
         val opts = optInvocations.groupBy({ it.opt }, { it.inv })
-        return CommandParseResult(subcommand, i, errors, tokens, opts, argInvocations)
+        for (e in errors) {
+            if (e is UsageError) e.context = e.context ?: context
+            context.errorEncountered = true
+        }
+        val nextCommand = subcommand.takeIf { errors.isEmpty() }
+        return CommandParseResult(command, nextCommand, i, errors, tokens, opts, argInvocations)
     }
 
     private fun isLongOptionWithEquals(prefix: String, token: String): Boolean {
@@ -342,13 +354,22 @@ private fun loadArgFile(filename: String, context: Context): List<String> {
 }
 
 private data class CommandParseResult<RunnerT>(
-    val subcommand: BaseCliktCommand<RunnerT>?,
+    val command: BaseCliktCommand<RunnerT>,
+    val nextCommand: BaseCliktCommand<RunnerT>?,
     val i: Int,
     val errors: List<CliktError>,
     val expandedArgv: List<String>,
     val optInvocations: Map<Option, List<Invocation>>,
     val argInvocations: List<ArgumentInvocation>,
-)
+) {
+    fun toInvocation(subcommands: List<CommandInvocation<RunnerT>>) = CommandInvocation(
+        command,
+        optInvocations,
+        argInvocations,
+        subcommands,
+        errors,
+    )
+}
 
 private data class OptInvocation(val opt: Option, val name: String, val values: List<String>) {
     val inv get() = Invocation(name, values)
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
index 8141b020..4afc2420 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/core/CliktCommandTest.kt
@@ -68,7 +68,10 @@ class CliktCommandTest {
         }
 
         val child = TestCommand(called = true, name = "foo")
-        TestCommand(called = true, invokeWithoutSubcommand = true).subcommands(child).apply {
+        TestCommand(
+            called = true,
+            invokeWithoutSubcommand = true
+        ).subcommands(child).apply {
             parse("foo")
             currentContext.invokedSubcommand shouldBe child
             child.currentContext.invokedSubcommand shouldBe null
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index 02a7d47b..cd927acb 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -7,11 +7,14 @@ import com.github.ajalt.clikt.parameters.arguments.pair
 import com.github.ajalt.clikt.parameters.options.default
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
+import com.github.ajalt.clikt.parsers.CommandInvocation
+import com.github.ajalt.clikt.parsers.CommandLineParser
 import com.github.ajalt.clikt.testing.TestCommand
 import com.github.ajalt.clikt.testing.formattedMessage
 import com.github.ajalt.clikt.testing.parse
 import com.github.ajalt.clikt.testing.test
 import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.assertions.withClue
 import io.kotest.data.blocking.forAll
 import io.kotest.data.row
 import io.kotest.matchers.shouldBe
@@ -356,15 +359,34 @@ class SubcommandTest {
         val bar1 = MultiSubBar(count = 2)
         val bar2 = MultiSubBar(count = 2)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(bar1.subcommands(bar2))
-        c.parse("bar a11 bar a12 bar a12 bar --opt=o a22")
+        val argv = "bar a11 bar a12 bar a12 bar --opt=o a22"
+        c.parse(argv)
         bar1.arg shouldBe "a12"
         bar2.opt shouldBe "o"
         bar2.arg shouldBe "a22"
 
+        c.invokedSubcommands shouldBe listOf(bar1, bar1)
         bar1.invokedSubcommands shouldBe listOf(bar2, bar2)
         bar2.invokedSubcommands shouldBe listOf(null, null)
+
+        val result = CommandLineParser.parse(c, CommandLineParser.tokenize(argv))
+        val invocation = result.invocation
+        invocation.command shouldBe c
+        invocation subcommandsShouldBe listOf(bar1, bar1)
+        invocation.subcommandInvocations[0] subcommandsShouldBe listOf(bar2)
+        invocation.subcommandInvocations[1] subcommandsShouldBe listOf(bar2)
+    }
+
+    private infix fun CommandInvocation<*>.subcommandsShouldBe(
+        expected: List<BaseCliktCommand<*>>,
+    ) {
+        withClue("${command.commandName} subcommands") {
+            subcommandInvocations.map { it.command.commandName }
+                .shouldBe(expected.map { it.commandName })
+        }
     }
 
+
     @Test
     @JsName("multiple_subcommands_with_varargs")
     fun `multiple subcommands with varargs`() = forAll(

From 76b57cf18da2658e6409091d8307cb270a368cd4 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 10 Apr 2024 10:05:07 -0700
Subject: [PATCH 25/43] Fix final tests

---
 .../ajalt/clikt/parsers/CommandLineParser.kt  |  2 +-
 .../ajalt/clikt/parsers/ParserInternals.kt    | 28 +++---
 .../ajalt/clikt/parameters/SubcommandTest.kt  | 97 ++++++++++++++-----
 .../github/ajalt/clikt/testing/TestCommand.kt |  8 +-
 4 files changed, 95 insertions(+), 40 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 2d235cf4..5bea0f36 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -107,7 +107,7 @@ object CommandLineParser {
             throw PrintHelpMessage(context, error = true)
         }
 
-        context.invokedSubcommands = invocation.subcommandInvocations.map { it.command }
+        context.invokedSubcommands += invocation.subcommandInvocations.map { it.command }
     }
 }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 1df24fe7..b754414e 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -9,31 +9,32 @@ internal fun <RunnerT> parseArgv(
     originalArgv: List<String>,
 ): CommandLineParseResult<RunnerT> {
     rootCommand.resetContext()
-    val result = parseCommandArgv(rootCommand, null, originalArgv, 0)
+    val result = parseCommandArgv(rootCommand, originalArgv, 0)
     return CommandLineParseResult(result.invocation, originalArgv, result.argv)
 }
 
 /** Parse argv for the command, and recursively for its invoked subcommands */
 private fun <RunnerT> parseCommandArgv(
     command: BaseCliktCommand<RunnerT>,
-    parent: Context?,
     argv: List<String>,
     i: Int,
 ): CommandArgvParseResult<RunnerT> {
-    val rootResult = CommandParser(command, parent, argv, i).parse()
+    val rootResult = CommandParser(command, argv, i).parse()
     val subcommands = mutableListOf<CommandInvocation<RunnerT>>()
     var nextCommand: BaseCliktCommand<RunnerT>? = rootResult.nextCommand
     var nextArgv = rootResult.expandedArgv
     var nextI = rootResult.i
-    while (nextCommand != null) {
-        val result = parseCommandArgv(nextCommand, command.currentContext, nextArgv, nextI)
+    while (nextCommand != null && nextCommand.currentContext.parent?.command == command) {
+        val result = parseCommandArgv(nextCommand, nextArgv, nextI)
         nextCommand = result.nextCommand
         nextArgv = result.argv
         nextI = result.i
         subcommands += result.invocation
     }
 
-    return CommandArgvParseResult(rootResult.toInvocation(subcommands), nextCommand, argv, i)
+    return CommandArgvParseResult(
+        rootResult.toInvocation(subcommands), nextCommand, nextArgv, nextI
+    )
 }
 
 private class CommandArgvParseResult<RunnerT>(
@@ -45,17 +46,20 @@ private class CommandArgvParseResult<RunnerT>(
 
 private class CommandParser<RunnerT>(
     private val command: BaseCliktCommand<RunnerT>,
-    parentContext: Context?,
     argv: List<String>,
     startingIndex: Int,
 ) {
     private var tokens = argv
     private val context = command.currentContext
     private val aliases = command.aliases()
-    private val extraSubcommands = parentContext?.selfAndAncestors()
-        ?.firstOrNull { it.command.allowMultipleSubcommands }?.command
-        ?._subcommands?.associate {
-            // We could avoid this cast if Context was generic, but it doesn't seem worth it
+
+    /**
+     * Subcommands of an ancestor with allowMultipleSubcommands, since any of them could be next
+     */
+    private val ancestorMultipleSubcommands = context.ancestors()
+        .firstOrNull { it.command.allowMultipleSubcommands }
+        ?.command?._subcommands?.associate {
+            // TODO We could avoid this cast if Context was generic
             @Suppress("UNCHECKED_CAST")
             it.commandName to it as BaseCliktCommand<RunnerT>
         } ?: emptyMap()
@@ -63,7 +67,7 @@ private class CommandParser<RunnerT>(
 
     // If an ancestor command allows multiple subcommands, include its subcommands so
     // that we can chain into them
-    private val allSubcommands = extraSubcommands + localSubcommands
+    private val allSubcommands = ancestorMultipleSubcommands + localSubcommands
     private val optionsByName = mutableMapOf<String, Option>()
     private val numberOption = command._options.find { it.acceptsNumberValueWithoutName }
     private val prefixes = mutableSetOf<String>()
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index cd927acb..5b6723d1 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -349,8 +349,55 @@ class SubcommandTest {
         bar.opt shouldBe null
         bar.arg shouldBe "b2"
 
-        foo.invokedSubcommands shouldBe listOf(bar, bar)
-        bar.invokedSubcommands shouldBe listOf(null, null)
+        foo.currentContext.invokedSubcommands shouldBe listOf(bar, bar)
+        bar.currentContext.invokedSubcommands shouldBe listOf()
+    }
+
+    @Test
+    @JsName("multiple_subcommands_with_nesting_parse_result")
+    fun `multiple subcommands with nesting parse result`() {
+        val a = TestCommand(name = "a", count = 3, noHelp = true)
+        val b = TestCommand(name = "b", count = 2, noHelp = true)
+        val c = TestCommand(name = "c", count = 1, noHelp = true)
+        val d = TestCommand(name = "d", count = 1, noHelp = true)
+        val r = TestCommand(name = "r", allowMultipleSubcommands = true, noHelp = true)
+            .subcommands(a, b.subcommands(c, d))
+        val argv = "a a b c b d a"
+
+        val result = CommandLineParser.parse(r, CommandLineParser.tokenize(argv))
+        val invocation = result.invocation
+        invocation.command shouldBe r
+        invocation subcommandsShouldBe listOf(a, a, b, b, a)
+        invocation.subcommandInvocations[0] subcommandsShouldBe listOf()
+        invocation.subcommandInvocations[1] subcommandsShouldBe listOf()
+        invocation.subcommandInvocations[2] subcommandsShouldBe listOf(c)
+        invocation.subcommandInvocations[3] subcommandsShouldBe listOf(d)
+        invocation.subcommandInvocations[4] subcommandsShouldBe listOf()
+
+        CommandLineParser.run(invocation) { it.runner() }
+        TestCommand.assertCalled(r)
+        r.currentContext.invokedSubcommands shouldBe listOf(a, a, b, b, a)
+        a.currentContext.invokedSubcommands shouldBe listOf()
+        b.currentContext.invokedSubcommands shouldBe listOf(c, d)
+    }
+
+    @Test
+    @JsName("multiple_subcommands_with_nesting_invalid")
+    fun `multiple subcommands with nesting invalid`() = forAll(
+        row("c"),
+        row("d"),
+        row("a c"),
+        row("a d"),
+        row("b c d"),
+        row("b d c"),
+    ) { argv ->
+        val a = TestCommand(name = "a", count = 3, noHelp = true)
+        val b = TestCommand(name = "b", count = 2, noHelp = true)
+        val c = TestCommand(name = "c", count = 1, noHelp = true)
+        val d = TestCommand(name = "d", count = 1, noHelp = true)
+        val r = TestCommand(name = "r", allowMultipleSubcommands = true, noHelp = true)
+            .subcommands(a, b.subcommands(c, d))
+        shouldThrow<UsageError> { r.parse(argv) }
     }
 
     @Test
@@ -360,14 +407,6 @@ class SubcommandTest {
         val bar2 = MultiSubBar(count = 2)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(bar1.subcommands(bar2))
         val argv = "bar a11 bar a12 bar a12 bar --opt=o a22"
-        c.parse(argv)
-        bar1.arg shouldBe "a12"
-        bar2.opt shouldBe "o"
-        bar2.arg shouldBe "a22"
-
-        c.invokedSubcommands shouldBe listOf(bar1, bar1)
-        bar1.invokedSubcommands shouldBe listOf(bar2, bar2)
-        bar2.invokedSubcommands shouldBe listOf(null, null)
 
         val result = CommandLineParser.parse(c, CommandLineParser.tokenize(argv))
         val invocation = result.invocation
@@ -375,17 +414,18 @@ class SubcommandTest {
         invocation subcommandsShouldBe listOf(bar1, bar1)
         invocation.subcommandInvocations[0] subcommandsShouldBe listOf(bar2)
         invocation.subcommandInvocations[1] subcommandsShouldBe listOf(bar2)
-    }
 
-    private infix fun CommandInvocation<*>.subcommandsShouldBe(
-        expected: List<BaseCliktCommand<*>>,
-    ) {
-        withClue("${command.commandName} subcommands") {
-            subcommandInvocations.map { it.command.commandName }
-                .shouldBe(expected.map { it.commandName })
-        }
-    }
+        CommandLineParser.run(invocation) { it.runner() }
+        TestCommand.assertCalled(c)
+        bar1.arg shouldBe "a12"
+        bar2.opt shouldBe "o"
+        bar2.arg shouldBe "a22"
 
+        c.currentContext.invokedSubcommands shouldBe listOf(bar1, bar1)
+        bar1.currentContext.invokedSubcommands shouldBe listOf(bar2, bar2)
+        bar2.currentContext.invokedSubcommands shouldBe listOf()
+
+    }
 
     @Test
     @JsName("multiple_subcommands_with_varargs")
@@ -435,9 +475,9 @@ class SubcommandTest {
         val c = C().subcommands(foo, bar)
         c.parse("--x=xx foo 1 bar 2")
         c.x shouldBe "xx"
-        foo.invokedSubcommands shouldBe listOf(null)
-        bar.invokedSubcommands shouldBe listOf(null)
-        c.invokedSubcommands shouldBe listOf(foo)
+        foo.currentContext.invokedSubcommands shouldBe listOf()
+        bar.currentContext.invokedSubcommands shouldBe listOf()
+        c.currentContext.invokedSubcommands shouldBe listOf(foo, bar)
 
         val c2 = C().subcommands(MultiSubFoo(1), MultiSubBar(1))
         shouldThrow<NoSuchArgument> {
@@ -464,7 +504,6 @@ class SubcommandTest {
     fun `multiple subcommands with excess arguments`() {
         val sub = TestCommand(name = "sub", called = true)
         val c = TestCommand(allowMultipleSubcommands = true).subcommands(sub)
-        c.parse("sub foo")
         shouldThrow<NoSuchArgument> {
             c.parse("sub foo")
         }.formattedMessage shouldBe "got unexpected extra argument (foo)"
@@ -495,3 +534,15 @@ private class MultiSubBar(count: Int) : TestCommand(name = "bar", count = count)
     val opt by option()
     val arg by argument()
 }
+
+private infix fun CommandInvocation<*>.subcommandsShouldBe(
+    expected: List<BaseCliktCommand<*>>,
+) {
+    fun BaseCliktCommand<*>.str(): String {
+        return "{$commandName (${_subcommands.joinToString { it.commandName }})}"
+    }
+    withClue("${command.commandName} subcommands") {
+        subcommandInvocations.map { it.command.str() }
+            .shouldBe(expected.map { it.str() })
+    }
+}
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index ad689a37..8d78f578 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -24,6 +24,7 @@ open class TestCommand(
     allowMultipleSubcommands: Boolean = false,
     treatUnknownOptionsAsArgs: Boolean = false,
     hidden: Boolean = false,
+    noHelp: Boolean = false,
 ) : CliktCommand(
     help,
     epilog,
@@ -39,16 +40,15 @@ open class TestCommand(
     init {
         context {
             terminal = parent?.terminal ?: Terminal(AnsiLevel.NONE)
+            if (noHelp) helpOptionNames = emptyList()
         }
     }
 
     private val count = count ?: if (called) 1 else 0
-    private val invoked = mutableListOf<BaseCliktCommand<*>?>()
-    val invokedSubcommands: List<BaseCliktCommand<*>?> get() = invoked
-    private val actualCount get() = invoked.size
+    private var actualCount = 0
 
     final override fun run() {
-        invoked += currentContext.invokedSubcommand
+        actualCount++
         run_()
     }
 

From a5d7b337a1fcb9608e04207a37177b64b79a4e65 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 10 Apr 2024 10:26:26 -0700
Subject: [PATCH 26/43] Switch to self types instead of runner

---
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 25 ++++------
 .../github/ajalt/clikt/core/CliktCommand.kt   | 14 +++---
 .../ajalt/clikt/core/NoOpCliktCommand.kt      |  4 +-
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 26 +++++------
 .../github/ajalt/clikt/parsers/Invocation.kt  | 10 ++--
 .../ajalt/clikt/parsers/ParserInternals.kt    | 46 +++++++++----------
 .../ajalt/clikt/parameters/SubcommandTest.kt  |  4 +-
 7 files changed, 58 insertions(+), 71 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 49cb41c1..a754c701 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -15,7 +15,7 @@ import com.github.ajalt.mordant.terminal.Terminal
  */
 @Suppress("PropertyName")
 @ParameterHolderDsl
-abstract class BaseCliktCommand<RunnerT>(
+abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
     /**
      * The help for this command. The first line is used in the usage string, and the entire string
      * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
@@ -67,13 +67,6 @@ abstract class BaseCliktCommand<RunnerT>(
      */
     private val hidden: Boolean = false,
 ) : ParameterHolder {
-    /**
-     * The function to run when this command is invoked.
-     *
-     * For [CliktCommand], this just calls `run`.
-     */
-    abstract val runner: RunnerT
-
     /**
      * The name of this command, used in help output.
      *
@@ -111,7 +104,7 @@ abstract class BaseCliktCommand<RunnerT>(
         return epilog
     }
 
-    internal var _subcommands: List<BaseCliktCommand<RunnerT>> = emptyList()
+    internal var _subcommands: List<T> = emptyList()
     internal val _options: MutableList<Option> = mutableListOf()
     internal val _arguments: MutableList<Argument> = mutableListOf()
     internal val _groups: MutableList<ParameterGroup> = mutableListOf()
@@ -208,7 +201,7 @@ abstract class BaseCliktCommand<RunnerT>(
     /**
      * Get a read-only list of commands registered as [subcommands] of this command.
      */
-    fun registeredSubcommands(): List<BaseCliktCommand<RunnerT>> = _subcommands.toList()
+    fun registeredSubcommands(): List<T> = _subcommands.toList()
 
     /**
      * Get a read-only list of options registered in this command (e.g. via [registerOption] or an
@@ -366,15 +359,15 @@ abstract class BaseCliktCommand<RunnerT>(
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
-    commands: Iterable<BaseCliktCommand<RunnerT>>,
+fun <T : BaseCliktCommand<T>, CommandT : T> CommandT.subcommands(
+    commands: Iterable<T>,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
 }
 
 /** Add the given commands as a subcommand of this command. */
-fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
-    vararg commands: BaseCliktCommand<RunnerT>,
+fun <T : BaseCliktCommand<T>, CommandT : T> CommandT.subcommands(
+    vararg commands: T,
 ): CommandT = apply {
     _subcommands = _subcommands + commands
 }
@@ -385,9 +378,7 @@ fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.subcommands(
  * Context property values are normally inherited from the parent context, but you can override any of them
  * here.
  */
-fun <RunnerT, CommandT : BaseCliktCommand<RunnerT>> CommandT.context(
-    block: Context.Builder.() -> Unit,
-): CommandT = apply {
+fun <T : BaseCliktCommand<T>, U: T> U.context(block: Context.Builder.() -> Unit): U = apply {
     // save the old config to allow multiple context calls
     val c = _contextConfig
     _contextConfig = {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index c0c02dae..d2518f20 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -24,7 +24,7 @@ abstract class CliktCommand(
     allowMultipleSubcommands: Boolean = false,
     treatUnknownOptionsAsArgs: Boolean = false,
     hidden: Boolean = false,
-) : BaseCliktCommand<() -> Unit>(
+) : BaseCliktCommand<CliktCommand>(
     help,
     epilog,
     name,
@@ -36,8 +36,6 @@ abstract class CliktCommand(
     treatUnknownOptionsAsArgs,
     hidden
 ) {
-    final override val runner: () -> Unit get() = ::run
-
     /**
      * Perform actions after parsing is complete and this command is invoked.
      *
@@ -59,7 +57,7 @@ abstract class CliktCommand(
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) {
+fun CliktCommand.main(argv: List<String>) {
     CommandLineParser.main(this, argv) { parse(argv) }
 }
 
@@ -72,14 +70,14 @@ fun BaseCliktCommand<() -> Unit>.main(argv: List<String>) {
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun BaseCliktCommand<() -> Unit>.main(argv: Array<out String>) = main(argv.asList())
+fun CliktCommand.main(argv: Array<out String>) = main(argv.asList())
 
 /**
  * Parse the command line and throw an exception if parsing fails.
  *
  * You should use [main] instead unless you want to handle output yourself.
  */
-fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
+fun CliktCommand.parse(argv: Array<String>) {
     parse(argv.asList())
 }
 
@@ -88,6 +86,6 @@ fun BaseCliktCommand<() -> Unit>.parse(argv: Array<String>) {
  *
  * You should use [main] instead unless you want to handle output yourself.
  */
-fun BaseCliktCommand<() -> Unit>.parse(argv: List<String>) {
-    CommandLineParser.parseAndRun(this, argv) { it.runner() }
+fun CliktCommand.parse(argv: List<String>) {
+    CommandLineParser.parseAndRun(this, argv) { it.run() }
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
index af32aaca..dc3b6382 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
@@ -13,7 +13,7 @@ open class NoOpCliktCommand(
     autoCompleteEnvvar: String? = "",
     allowMultipleSubcommands: Boolean = false,
     hidden: Boolean = false,
-) : BaseCliktCommand<() -> Unit>(
+) : CliktCommand(
     help,
     epilog,
     name,
@@ -24,5 +24,5 @@ open class NoOpCliktCommand(
     allowMultipleSubcommands,
     hidden
 ) {
-    final override val runner: () -> Unit = {}
+    final override fun run() {}
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 5bea0f36..7e8c05c9 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,10 +16,10 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
-    fun <RunnerT> main(
-        command: BaseCliktCommand<RunnerT>,
+    fun <T: BaseCliktCommand<T>> main(
+        command: T,
         argv: List<String>,
-        parseAndRun: BaseCliktCommand<RunnerT>.(List<String>) -> Unit,
+        parseAndRun: T.(argv: List<String>) -> Unit,
     ) {
         try {
             command.parseAndRun(argv)
@@ -33,20 +33,20 @@ object CommandLineParser {
     /**
      * A shortcut for calling `run(parse(command, argv).invocation, runCommand)`
      */
-    fun <RunnerT> parseAndRun(
-        command: BaseCliktCommand<RunnerT>,
+    fun <T: BaseCliktCommand<T>> parseAndRun(
+        command: T,
         argv: List<String>,
-        runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
-    ): CommandLineParseResult<RunnerT> {
+        runCommand: (T) -> Unit,
+    ): CommandLineParseResult<T> {
         val result = parse(command, argv)
         run(result.invocation, runCommand)
         return result
     }
 
     // TODO: docs throws
-    fun <RunnerT> run(
-        invocation: CommandInvocation<RunnerT>,
-        runCommand: (BaseCliktCommand<RunnerT>) -> Unit,
+    fun <T: BaseCliktCommand<T>> run(
+        invocation: CommandInvocation<T>,
+        runCommand: (T) -> Unit,
     ) {
         try {
             finalize(invocation)
@@ -61,9 +61,9 @@ object CommandLineParser {
     }
 
     // TODO: docs does not throw
-    fun <RunnerT> parse(
-        command: BaseCliktCommand<RunnerT>, argv: List<String>,
-    ): CommandLineParseResult<RunnerT> {
+    fun <T: BaseCliktCommand<T>> parse(
+        command: T, argv: List<String>,
+    ): CommandLineParseResult<T> {
         return parseArgv(command, argv)
     }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index f50e0e85..f3faa26c 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -18,16 +18,16 @@ data class Invocation(val name: String, val values: List<String>)
 // TODO: docs
 data class ArgumentInvocation(val argument: Argument, val values: List<String>)
 
-data class CommandInvocation<RunnerT>(
-    val command: BaseCliktCommand<RunnerT>,
+data class CommandInvocation<T: BaseCliktCommand<T>>(
+    val command: T,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
-    val subcommandInvocations: List<CommandInvocation<RunnerT>>,
+    val subcommandInvocations: List<CommandInvocation<T>>,
     val errors: List<CliktError>,
 )
 
-class CommandLineParseResult<RunnerT>(
-    val invocation: CommandInvocation<RunnerT>,
+class CommandLineParseResult<T: BaseCliktCommand<T>>(
+    val invocation: CommandInvocation<T>,
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
 )
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index b754414e..0968d5bb 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -4,24 +4,24 @@ import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
 
-internal fun <RunnerT> parseArgv(
-    rootCommand: BaseCliktCommand<RunnerT>,
+internal fun <T : BaseCliktCommand<T>> parseArgv(
+    rootCommand: T,
     originalArgv: List<String>,
-): CommandLineParseResult<RunnerT> {
+): CommandLineParseResult<T> {
     rootCommand.resetContext()
     val result = parseCommandArgv(rootCommand, originalArgv, 0)
     return CommandLineParseResult(result.invocation, originalArgv, result.argv)
 }
 
 /** Parse argv for the command, and recursively for its invoked subcommands */
-private fun <RunnerT> parseCommandArgv(
-    command: BaseCliktCommand<RunnerT>,
+private fun <T : BaseCliktCommand<T>> parseCommandArgv(
+    command: T,
     argv: List<String>,
     i: Int,
-): CommandArgvParseResult<RunnerT> {
+): CommandArgvParseResult<T> {
     val rootResult = CommandParser(command, argv, i).parse()
-    val subcommands = mutableListOf<CommandInvocation<RunnerT>>()
-    var nextCommand: BaseCliktCommand<RunnerT>? = rootResult.nextCommand
+    val subcommands = mutableListOf<CommandInvocation<T>>()
+    var nextCommand: T? = rootResult.nextCommand
     var nextArgv = rootResult.expandedArgv
     var nextI = rootResult.i
     while (nextCommand != null && nextCommand.currentContext.parent?.command == command) {
@@ -37,15 +37,15 @@ private fun <RunnerT> parseCommandArgv(
     )
 }
 
-private class CommandArgvParseResult<RunnerT>(
-    val invocation: CommandInvocation<RunnerT>,
-    val nextCommand: BaseCliktCommand<RunnerT>?,
+private class CommandArgvParseResult<T : BaseCliktCommand<T>>(
+    val invocation: CommandInvocation<T>,
+    val nextCommand: T?,
     val argv: List<String>,
     val i: Int,
 )
 
-private class CommandParser<RunnerT>(
-    private val command: BaseCliktCommand<RunnerT>,
+private class CommandParser<T : BaseCliktCommand<T>>(
+    private val command: T,
     argv: List<String>,
     startingIndex: Int,
 ) {
@@ -53,15 +53,13 @@ private class CommandParser<RunnerT>(
     private val context = command.currentContext
     private val aliases = command.aliases()
 
-    /**
-     * Subcommands of an ancestor with allowMultipleSubcommands, since any of them could be next
-     */
+    // Subcommands of an ancestor with allowMultipleSubcommands, since any of them could be next
     private val ancestorMultipleSubcommands = context.ancestors()
         .firstOrNull { it.command.allowMultipleSubcommands }
         ?.command?._subcommands?.associate {
             // TODO We could avoid this cast if Context was generic
             @Suppress("UNCHECKED_CAST")
-            it.commandName to it as BaseCliktCommand<RunnerT>
+            it.commandName to it as T
         } ?: emptyMap()
     private val localSubcommands = command._subcommands.associateBy { it.commandName }
 
@@ -73,7 +71,7 @@ private class CommandParser<RunnerT>(
     private val prefixes = mutableSetOf<String>()
     private val longNames = mutableSetOf<String>()
     private val argumentTokens = mutableListOf<String>()
-    private var subcommand: BaseCliktCommand<RunnerT>? = null
+    private var subcommand: T? = null
     private val optInvocations = mutableListOf<OptInvocation>()
     private val argInvocations = mutableListOf<ArgumentInvocation>()
     private val errors = mutableListOf<CliktError>()
@@ -84,7 +82,7 @@ private class CommandParser<RunnerT>(
     private var canParseOptions = true
     private var canExpandAtFiles = context.expandArgumentFiles
 
-    fun parse(): CommandParseResult<RunnerT> {
+    fun parse(): CommandParseResult<T> {
         splitOptionPrefixes()
         if (printHelpOnEmptyArgsIfNecessary()) return makeResult()
         consumeTokens()
@@ -178,7 +176,7 @@ private class CommandParser<RunnerT>(
         prefixes.remove("")
     }
 
-    private fun makeResult(): CommandParseResult<RunnerT> {
+    private fun makeResult(): CommandParseResult<T> {
         val opts = optInvocations.groupBy({ it.opt }, { it.inv })
         for (e in errors) {
             if (e is UsageError) e.context = e.context ?: context
@@ -357,16 +355,16 @@ private fun loadArgFile(filename: String, context: Context): List<String> {
     return shlex(filename, context.argumentFileReader!!(filename), context.localization)
 }
 
-private data class CommandParseResult<RunnerT>(
-    val command: BaseCliktCommand<RunnerT>,
-    val nextCommand: BaseCliktCommand<RunnerT>?,
+private data class CommandParseResult<T : BaseCliktCommand<T>>(
+    val command: T,
+    val nextCommand: T?,
     val i: Int,
     val errors: List<CliktError>,
     val expandedArgv: List<String>,
     val optInvocations: Map<Option, List<Invocation>>,
     val argInvocations: List<ArgumentInvocation>,
 ) {
-    fun toInvocation(subcommands: List<CommandInvocation<RunnerT>>) = CommandInvocation(
+    fun toInvocation(subcommands: List<CommandInvocation<T>>) = CommandInvocation(
         command,
         optInvocations,
         argInvocations,
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
index 5b6723d1..a0ab0854 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt
@@ -374,7 +374,7 @@ class SubcommandTest {
         invocation.subcommandInvocations[3] subcommandsShouldBe listOf(d)
         invocation.subcommandInvocations[4] subcommandsShouldBe listOf()
 
-        CommandLineParser.run(invocation) { it.runner() }
+        CommandLineParser.run(invocation) { it.run() }
         TestCommand.assertCalled(r)
         r.currentContext.invokedSubcommands shouldBe listOf(a, a, b, b, a)
         a.currentContext.invokedSubcommands shouldBe listOf()
@@ -415,7 +415,7 @@ class SubcommandTest {
         invocation.subcommandInvocations[0] subcommandsShouldBe listOf(bar2)
         invocation.subcommandInvocations[1] subcommandsShouldBe listOf(bar2)
 
-        CommandLineParser.run(invocation) { it.runner() }
+        CommandLineParser.run(invocation) { it.run() }
         TestCommand.assertCalled(c)
         bar1.arg shouldBe "a12"
         bar2.opt shouldBe "o"

From 2d58250067c39a415482e82565e1b61c0534006e Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 10 Apr 2024 10:36:13 -0700
Subject: [PATCH 27/43] Add test for expandedArgv

---
 .../github/ajalt/clikt/parsers/AtFileTest.kt  | 34 +++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parsers/AtFileTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parsers/AtFileTest.kt
index 67ab9314..c7862ad7 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parsers/AtFileTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parsers/AtFileTest.kt
@@ -73,10 +73,15 @@ class AtFileTest {
             }
         }
 
-        C().withAtFiles(
+        val c = C().withAtFiles(
             "foo" to "--foo 123 456",
             "bar" to "@foo"
-        ).parse("@foo")
+        )
+        c.parse("@foo")
+
+        val result = CommandLineParser.parse(c, listOf("@foo"))
+        result.originalArgv shouldBe listOf("@foo")
+        result.expandedArgv shouldBe listOf("--foo", "123", "456")
     }
 
     @Test
@@ -165,4 +170,29 @@ class AtFileTest {
 
         C().parse("@file")
     }
+
+    @Test
+    @JsName("parsing_atfile_with_alias")
+    fun `parsing atfile with alias`() {
+        class C : TestCommand() {
+            val foo by option()
+            val arg by argument().multiple()
+
+            override fun aliases() = mapOf(
+                "alias" to listOf("@foo", "789"),
+            )
+
+            override fun run_() {
+                foo shouldBe "123"
+                arg shouldBe listOf("456", "789")
+            }
+        }
+
+        val c = C().withAtFiles("foo" to "--foo 123 456")
+        c.parse("alias")
+
+        val result = CommandLineParser.parse(c, listOf("alias"))
+        result.originalArgv shouldBe listOf("alias")
+        result.expandedArgv shouldBe listOf("--foo", "123", "456", "789")
+    }
 }

From 434e55266759238c99d7caaf641d71beb17bd757 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Wed, 10 Apr 2024 13:40:19 -0700
Subject: [PATCH 28/43] Add SuspendingCliktCommand

---
 clikt/build.gradle.kts                        |  2 +
 .../clikt/command/SuspendingCliktCommand.kt   | 85 +++++++++++++++++++
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 25 +++---
 .../github/ajalt/clikt/parsers/Invocation.kt  | 35 ++++++++
 .../command/SuspendingCliktCommandTest.kt     | 42 +++++++++
 gradle/libs.versions.toml                     |  3 +
 6 files changed, 178 insertions(+), 14 deletions(-)
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
 create mode 100644 clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt

diff --git a/clikt/build.gradle.kts b/clikt/build.gradle.kts
index db1dd789..330ca46e 100644
--- a/clikt/build.gradle.kts
+++ b/clikt/build.gradle.kts
@@ -38,6 +38,8 @@ kotlin {
             dependencies {
                 api(kotlin("test"))
                 api(libs.kotest)
+                api(libs.coroutines.core)
+                api(libs.coroutines.test)
             }
         }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
new file mode 100644
index 00000000..f6b9b1cc
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -0,0 +1,85 @@
+package com.github.ajalt.clikt.command
+
+import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.parsers.CommandLineParser
+
+/**
+ * A version of [CliktCommand] that supports a suspending [run] function.
+ */
+abstract class SuspendingCliktCommand(
+    help: String = "",
+    epilog: String = "",
+    name: String? = null,
+    invokeWithoutSubcommand: Boolean = false,
+    printHelpOnEmptyArgs: Boolean = false,
+    helpTags: Map<String, String> = emptyMap(),
+    autoCompleteEnvvar: String? = "",
+    allowMultipleSubcommands: Boolean = false,
+    treatUnknownOptionsAsArgs: Boolean = false,
+    hidden: Boolean = false,
+) : BaseCliktCommand<SuspendingCliktCommand>(
+    help,
+    epilog,
+    name,
+    invokeWithoutSubcommand,
+    printHelpOnEmptyArgs,
+    helpTags,
+    autoCompleteEnvvar,
+    allowMultipleSubcommands,
+    treatUnknownOptionsAsArgs,
+    hidden
+) {
+    /**
+     * Perform actions after parsing is complete and this command is invoked.
+     *
+     * This is called after command line parsing is complete. If this command is a subcommand, this
+     * will only be called if the subcommand is invoked.
+     *
+     * If one of this command's subcommands is invoked, this is called before the subcommand's
+     * arguments are parsed.
+     */
+    abstract suspend fun run()
+}
+
+
+/**
+ * Parse the command line and print helpful output if any errors occur.
+ *
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
+ */
+suspend fun SuspendingCliktCommand.main(argv: List<String>) {
+    CommandLineParser.main(this, argv) { parse(argv) }
+}
+
+/**
+ * Parse the command line and print helpful output if any errors occur.
+ *
+ * This suspend function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
+ */
+suspend fun SuspendingCliktCommand.main(argv: Array<out String>) = main(argv.asList())
+
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+suspend fun SuspendingCliktCommand.parse(argv: Array<String>) {
+    parse(argv.asList())
+}
+
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+suspend fun SuspendingCliktCommand.parse(argv: List<String>) {
+    CommandLineParser.parseAndRun(this, argv) { it.run() }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 7e8c05c9..8daa80fe 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,7 +16,7 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
-    fun <T: BaseCliktCommand<T>> main(
+    inline fun <T: BaseCliktCommand<T>> main(
         command: T,
         argv: List<String>,
         parseAndRun: T.(argv: List<String>) -> Unit,
@@ -25,7 +25,7 @@ object CommandLineParser {
             command.parseAndRun(argv)
         } catch (e: CliktError) {
             command.echoFormattedHelp(e)
-            exitProcessMpp(e.statusCode)
+           TODO(" exitProcessMpp(e.statusCode)")
         }
     }
 
@@ -33,7 +33,7 @@ object CommandLineParser {
     /**
      * A shortcut for calling `run(parse(command, argv).invocation, runCommand)`
      */
-    fun <T: BaseCliktCommand<T>> parseAndRun(
+    inline fun <T: BaseCliktCommand<T>> parseAndRun(
         command: T,
         argv: List<String>,
         runCommand: (T) -> Unit,
@@ -44,26 +44,23 @@ object CommandLineParser {
     }
 
     // TODO: docs throws
-    fun <T: BaseCliktCommand<T>> run(
-        invocation: CommandInvocation<T>,
+    inline fun <T: BaseCliktCommand<T>> run(
+        rootInvocation: CommandInvocation<T>,
         runCommand: (T) -> Unit,
     ) {
+        val invocations = rootInvocation.flatten()
         try {
-            finalize(invocation)
-            runCommand(invocation.command)
-
-            for (subcommandInvocation in invocation.subcommandInvocations) {
-                run(subcommandInvocation, runCommand)
+            for (invocation in invocations) {
+                finalize(invocation)
+                runCommand(invocation.command)
             }
         } finally {
-            invocation.command.currentContext.close()
+            invocations.close()
         }
     }
 
     // TODO: docs does not throw
-    fun <T: BaseCliktCommand<T>> parse(
-        command: T, argv: List<String>,
-    ): CommandLineParseResult<T> {
+    fun <T: BaseCliktCommand<T>> parse(command: T, argv: List<String>): CommandLineParseResult<T> {
         return parseArgv(command, argv)
     }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index f3faa26c..55684379 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -2,6 +2,7 @@ package com.github.ajalt.clikt.parsers
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktError
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.options.Option
 
@@ -31,3 +32,37 @@ class CommandLineParseResult<T: BaseCliktCommand<T>>(
     val originalArgv: List<String>,
     val expandedArgv: List<String>,
 )
+
+fun <T: BaseCliktCommand<T>> CommandInvocation<T>.flatten(): FlatInvocations<T> {
+    return FlatInvocations(this)
+}
+
+class FlatInvocations<T: BaseCliktCommand<T>> internal constructor(
+    root: CommandInvocation<T>,
+): Sequence<CommandInvocation<T>> {
+    private val closables = mutableListOf<Context>()
+    private val seq = sequence {
+        suspend fun SequenceScope<CommandInvocation<T>>.yieldSubs(inv: CommandInvocation<T>) {
+            closables.add(inv.command.currentContext)
+            yield(inv)
+            for (sub in inv.subcommandInvocations) {
+                yieldSubs(sub)
+            }
+            closables.removeLast().close()
+        }
+        yieldSubs(root)
+    }
+
+    override fun iterator(): Iterator<CommandInvocation<T>> = seq.iterator()
+
+    fun close() {
+        closables.forEach { it.close() }
+    }
+}
+
+fun <T: BaseCliktCommand<T>> CommandLineParseResult<T>.flatten(): Sequence<CommandInvocation<T>> {
+    return sequence {
+        yield(invocation)
+        yieldAll(invocation.subcommandInvocations)
+    }
+}
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt
new file mode 100644
index 00000000..1d6c0f96
--- /dev/null
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt
@@ -0,0 +1,42 @@
+package com.github.ajalt.clikt.command
+
+import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.parameters.arguments.argument
+import com.github.ajalt.clikt.parsers.CommandLineParser
+import io.kotest.matchers.shouldBe
+import kotlinx.coroutines.test.runTest
+import kotlinx.coroutines.yield
+import kotlin.js.JsName
+import kotlin.test.Test
+
+
+class SuspendingCliktCommandTest {
+    @Test
+    @JsName("suspending_run")
+    fun `suspending run`() = runTest {
+        class C : SuspendingCliktCommand() {
+            val arg by argument()
+            var ran = false
+
+            override suspend fun run() {
+                yield()
+                arg shouldBe "foo"
+                ran = true
+            }
+        }
+
+        class Sub : SuspendingCliktCommand() {
+            var ran = false
+
+            override suspend fun run() {
+                ran = true
+            }
+        }
+
+        val sub = Sub()
+        val c: C = C().subcommands(sub)
+        c.parse(CommandLineParser.tokenize("foo sub"))
+        c.ran shouldBe true
+        sub.ran shouldBe true
+    }
+}
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 3ecc56a8..4c326ed7 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -1,10 +1,13 @@
 [versions]
 kotlin = "1.9.23"
+coroutines = "1.8.0"
 
 [libraries]
 mordant = "com.github.ajalt.mordant:mordant:2.5.0"
 
 # used in tests
+coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
+coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
 kotest =  "io.kotest:kotest-assertions-core:5.9.0.1440-SNAPSHOT"
 systemrules = "com.github.stefanbirkner:system-rules:1.19.0"
 jimfs = "com.google.jimfs:jimfs:1.3.0"

From e7230c7d8b4c742e32ccfc2532e2dc1301f5d379 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Thu, 11 Apr 2024 09:55:24 -0700
Subject: [PATCH 29/43] Add ChainedCliktCommand

---
 README.md                                     |  2 +-
 .../clikt/command/ChainedCliktCommand.kt      | 93 +++++++++++++++++++
 .../clikt/command/SuspendingCliktCommand.kt   |  3 +-
 .../ajalt/clikt/parsers/CommandLineParser.kt  |  8 +-
 .../github/ajalt/clikt/parsers/Invocation.kt  |  7 --
 .../clikt/command/ChainedCliktCommandTest.kt  | 38 ++++++++
 6 files changed, 138 insertions(+), 13 deletions(-)
 create mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
 create mode 100644 clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt

diff --git a/README.md b/README.md
index dac32fd9..10862218 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ dependencies {
 
 #### Multiplatform
 
-Clikt supports the following targets: `jvm`, `mingwX64`, `linuxX64`, `linuxArm64`, `macosX64`, `macosArm64'`,
+Clikt supports the following targets: `jvm`, `mingwX64`, `linuxX64`, `linuxArm64`, `macosX64`, `macosArm64`,
 and `js` and `wasmJs` (for both Node.js and Browsers). [See the
 docs](https://ajalt.github.io/clikt/advanced/#multiplatform-support) for more information about
 functionality supported on each target. You'll need to use Gradle 6 or newer.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
new file mode 100644
index 00000000..5ea210ff
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -0,0 +1,93 @@
+package com.github.ajalt.clikt.command
+
+import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.parsers.CommandLineParser
+
+// TODO: md docs, changelog
+/**
+ * A version of [CliktCommand] that returns a value from the [run] function, which is then passed to
+ * subcommands.
+ */
+abstract class ChainedCliktCommand<T>(
+    help: String = "",
+    epilog: String = "",
+    name: String? = null,
+    invokeWithoutSubcommand: Boolean = false,
+    printHelpOnEmptyArgs: Boolean = false,
+    helpTags: Map<String, String> = emptyMap(),
+    autoCompleteEnvvar: String? = "",
+    allowMultipleSubcommands: Boolean = false,
+    treatUnknownOptionsAsArgs: Boolean = false,
+    hidden: Boolean = false,
+) : BaseCliktCommand<ChainedCliktCommand<T>>(
+    help,
+    epilog,
+    name,
+    invokeWithoutSubcommand,
+    printHelpOnEmptyArgs,
+    helpTags,
+    autoCompleteEnvvar,
+    allowMultipleSubcommands,
+    treatUnknownOptionsAsArgs,
+    hidden
+) {
+    /**
+     * Perform actions after parsing is complete and this command is invoked.
+     *
+     * This takes the value returned by the previously invoked command and returns a new value.
+     *
+     * This is called after command line parsing is complete. If this command is a subcommand, this
+     * will only be called if the subcommand is invoked.
+     *
+     * If one of this command's subcommands is invoked, this is called before the subcommand's
+     * arguments are parsed.
+     */
+    abstract fun run(value: T): T
+}
+
+
+/**
+ * Parse the command line and print helpful output if any errors occur.
+ *
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
+ */
+fun <T> ChainedCliktCommand<T>.main(argv: List<String>, initial: T): T {
+    return CommandLineParser.main(this, argv) { parse(argv, initial) }
+}
+
+/**
+ * Parse the command line and print helpful output if any errors occur.
+ *
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
+ * through.
+ *
+ * If you don't want Clikt to exit your process, call [parse] instead.
+ */
+fun <T> ChainedCliktCommand<T>.main(argv: Array<out String>, initial: T) {
+    main(argv.asList(), initial)
+}
+
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+fun <T> ChainedCliktCommand<T>.parse(argv: Array<String>, initial: T): T {
+    return parse(argv.asList(), initial)
+}
+
+/**
+ * Parse the command line and throw an exception if parsing fails.
+ *
+ * You should use [main] instead unless you want to handle output yourself.
+ */
+fun <T> ChainedCliktCommand<T>.parse(argv: List<String>, initial: T): T {
+    var value = initial
+    CommandLineParser.parseAndRun(this, argv) { value = it.run(value) }
+    return value
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
index f6b9b1cc..9d1141c2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -3,6 +3,7 @@ package com.github.ajalt.clikt.command
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.CommandLineParser
 
+// TODO: md docs
 /**
  * A version of [CliktCommand] that supports a suspending [run] function.
  */
@@ -58,7 +59,7 @@ suspend fun SuspendingCliktCommand.main(argv: List<String>) {
 /**
  * Parse the command line and print helpful output if any errors occur.
  *
- * This suspend function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
+ * This function calls [parse] and catches any [CliktError]s that are thrown, exiting the process
  * with the specified [status code][CliktError.statusCode]. Other errors are allowed to pass
  * through.
  *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 8daa80fe..93792089 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -16,13 +16,13 @@ object CommandLineParser {
         return shlex("TODO", commandLine, localization)// TODO
     }
 
-    inline fun <T: BaseCliktCommand<T>> main(
+    inline fun <T: BaseCliktCommand<T>, U> main(
         command: T,
         argv: List<String>,
-        parseAndRun: T.(argv: List<String>) -> Unit,
-    ) {
+        parseAndRun: T.(argv: List<String>) -> U,
+    ) : U {
         try {
-            command.parseAndRun(argv)
+            return command.parseAndRun(argv)
         } catch (e: CliktError) {
             command.echoFormattedHelp(e)
            TODO(" exitProcessMpp(e.statusCode)")
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 55684379..16b1d553 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -59,10 +59,3 @@ class FlatInvocations<T: BaseCliktCommand<T>> internal constructor(
         closables.forEach { it.close() }
     }
 }
-
-fun <T: BaseCliktCommand<T>> CommandLineParseResult<T>.flatten(): Sequence<CommandInvocation<T>> {
-    return sequence {
-        yield(invocation)
-        yieldAll(invocation.subcommandInvocations)
-    }
-}
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
new file mode 100644
index 00000000..322e79c7
--- /dev/null
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
@@ -0,0 +1,38 @@
+package com.github.ajalt.clikt.command
+
+import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.parameters.arguments.argument
+import com.github.ajalt.clikt.parameters.types.int
+import com.github.ajalt.clikt.parsers.CommandLineParser
+import io.kotest.matchers.shouldBe
+import kotlinx.coroutines.test.runTest
+import kotlinx.coroutines.yield
+import kotlin.js.JsName
+import kotlin.test.Test
+
+
+class ChainedCliktCommandTest {
+    @Test
+    @JsName("chained_run")
+    fun `chained run`() = runTest {
+        class C : ChainedCliktCommand<List<Int>>(
+            allowMultipleSubcommands = true
+        ) {
+            override fun run(value: List<Int>): List<Int> {
+                return value + 1
+            }
+        }
+
+        class Sub : ChainedCliktCommand<List<Int>>() {
+            val arg by argument().int()
+            override fun run(value: List<Int>): List<Int> {
+                return value + arg
+            }
+        }
+
+        val sub = Sub()
+        val c: C = C().subcommands(sub)
+        val result = c.parse(listOf("sub", "2",  "sub", "3"), emptyList())
+        result shouldBe listOf(1, 2, 3)
+    }
+}

From 0f397df09fc5f6c528406809f2bef2cafe5b50de Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Thu, 11 Apr 2024 11:11:13 -0700
Subject: [PATCH 30/43] Add CliktUtil.exitProcess

---
 CHANGELOG.md                                  |  1 +
 .../clikt/command/ChainedCliktCommand.kt      |  9 ++++++++-
 .../com/github/ajalt/clikt/core/CliktUtil.kt  | 14 ++++++++++++++
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 19 +++++++++----------
 .../clikt/parameters/MultiUsageErrorTest.kt   |  1 -
 5 files changed, 32 insertions(+), 12 deletions(-)
 create mode 100755 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktUtil.kt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2a5de543..c55c3b07 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 ### Added
 - Added `NoSuchArgument` exception that is thrown when too many arguments were given on the command line. Previously, a less specific `UsageError` was thrown instead.
+- Added `CliktUtil.exitProcess`, which is a cross-platform way to exit the process with a status code.
 ## 4.4.0
 ### Added
 - Publish `linuxArm64` and `wasmJs` targets.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
index 5ea210ff..b4cf79ab 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -56,7 +56,14 @@ abstract class ChainedCliktCommand<T>(
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
 fun <T> ChainedCliktCommand<T>.main(argv: List<String>, initial: T): T {
-    return CommandLineParser.main(this, argv) { parse(argv, initial) }
+    try {
+        return parse(argv, initial)
+    } catch (e: CliktError) {
+        echoFormattedHelp(e)
+        CliktUtil.exitProcess(e.statusCode)
+        // Throw an exception if we can't exit, since we don't have a return value
+        throw ProgramResult(e.statusCode)
+    }
 }
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktUtil.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktUtil.kt
new file mode 100755
index 00000000..b6f853ce
--- /dev/null
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktUtil.kt
@@ -0,0 +1,14 @@
+package com.github.ajalt.clikt.core
+
+import com.github.ajalt.clikt.mpp.exitProcessMpp
+
+object CliktUtil {
+    /**
+     * Exit the current process with the given status code.
+     *
+     * On browsers, where it's not possible to exit the process, this is a no-op.
+     */
+    fun exitProcess(status: Int) {
+        exitProcessMpp(status)
+    }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 93792089..41ea1b3d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -3,7 +3,6 @@ package com.github.ajalt.clikt.parsers
 import com.github.ajalt.clikt.completion.CompletionGenerator
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.*
-import com.github.ajalt.clikt.mpp.exitProcessMpp
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
@@ -13,19 +12,19 @@ object CommandLineParser {
         commandLine: String,
         localization: Localization = defaultLocalization,
     ): List<String> {
-        return shlex("TODO", commandLine, localization)// TODO
+        return shlex("TODO", commandLine, localization)// TODO shlex
     }
 
-    inline fun <T: BaseCliktCommand<T>, U> main(
+    inline fun <T : BaseCliktCommand<T>> main(
         command: T,
         argv: List<String>,
-        parseAndRun: T.(argv: List<String>) -> U,
-    ) : U {
+        parseAndRun: T.(argv: List<String>) -> Unit,
+    ) {
         try {
-            return command.parseAndRun(argv)
+            command.parseAndRun(argv)
         } catch (e: CliktError) {
             command.echoFormattedHelp(e)
-           TODO(" exitProcessMpp(e.statusCode)")
+            CliktUtil.exitProcess(e.statusCode)
         }
     }
 
@@ -33,7 +32,7 @@ object CommandLineParser {
     /**
      * A shortcut for calling `run(parse(command, argv).invocation, runCommand)`
      */
-    inline fun <T: BaseCliktCommand<T>> parseAndRun(
+    inline fun <T : BaseCliktCommand<T>> parseAndRun(
         command: T,
         argv: List<String>,
         runCommand: (T) -> Unit,
@@ -44,7 +43,7 @@ object CommandLineParser {
     }
 
     // TODO: docs throws
-    inline fun <T: BaseCliktCommand<T>> run(
+    inline fun <T : BaseCliktCommand<T>> run(
         rootInvocation: CommandInvocation<T>,
         runCommand: (T) -> Unit,
     ) {
@@ -60,7 +59,7 @@ object CommandLineParser {
     }
 
     // TODO: docs does not throw
-    fun <T: BaseCliktCommand<T>> parse(command: T, argv: List<String>): CommandLineParseResult<T> {
+    fun <T : BaseCliktCommand<T>> parse(command: T, argv: List<String>): CommandLineParseResult<T> {
         return parseArgv(command, argv)
     }
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
index 66a41194..aebe2692 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
@@ -38,7 +38,6 @@ class MultiUsageErrorTest {
         class C : TestCommand(called = false) {
             val x by option().int().required().check { it == 0 }
             val y by option().int().required().check { it == 0 }
-            // TODO: parseArguments and handleExcessArgs used to be part of the finalization step.
             val a by argument().int().check { it == 0 }
         }
 

From 28989a4a8bc5d43094099394b066d12a15d2038b Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Thu, 11 Apr 2024 11:23:17 -0700
Subject: [PATCH 31/43] Simplify throwErrors

---
 .../com/github/ajalt/clikt/parsers/CommandLineParser.kt     | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 41ea1b3d..e2a71477 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -108,11 +108,9 @@ object CommandLineParser {
 }
 
 private fun CommandInvocation<*>.throwErrors() {
+    // The errors are always UsageErrors, expect for the case of printHelpOnEmptyArgs
     when (val first = errors.firstOrNull()) {
-        // TODO: check if there is ever an error after a UsageError
-        is UsageError -> errors.takeWhile { it is UsageError }
-            .filterIsInstance<UsageError>().throwErrors()
-
+        is UsageError -> errors.filterIsInstance<UsageError>().throwErrors()
         is CliktError -> throw first
     }
 }

From 68db911bf685119468ca423d0ce4d89f91ce71c2 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Fri, 12 Apr 2024 11:15:12 -0700
Subject: [PATCH 32/43] Remove most CliktCommand constructor parameters

---
 CHANGELOG.md                                  |  13 +++
 .../clikt/command/ChainedCliktCommand.kt      |  26 +----
 .../clikt/command/SuspendingCliktCommand.kt   |  26 +----
 .../clikt/completion/CompletionBuiltins.kt    |  15 ++-
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 104 ++++++++----------
 .../github/ajalt/clikt/core/CliktCommand.kt   |  26 +----
 .../ajalt/clikt/core/NoOpCliktCommand.kt      |  24 +---
 .../ajalt/clikt/parsers/CommandLineParser.kt  |   6 +-
 .../clikt/command/ChainedCliktCommandTest.kt  |   9 +-
 .../github/ajalt/clikt/testing/TestCommand.kt |  40 +++----
 docs/autocomplete.md                          |  10 +-
 docs/commands.md                              |  23 ++--
 docs/options.md                               |  35 +++---
 .../ajalt/clikt/samples/aliases/main.kt       |  21 ++--
 .../github/ajalt/clikt/samples/copy/main.kt   |   7 +-
 .../github/ajalt/clikt/samples/json/main.kt   |  16 ++-
 .../ajalt/clikt/samples/plugins/commit.kt     |  18 +--
 .../ajalt/clikt/samples/plugins/delete.kt     |  12 +-
 .../github/ajalt/clikt/samples/repo/main.kt   |  94 ++++++++--------
 .../ajalt/clikt/samples/validation/main.kt    |   5 +-
 20 files changed, 245 insertions(+), 285 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c55c3b07..bd348151 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,19 @@
 ### Changed
 - In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
 - Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.
+- **Breaking Change:** Removed the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
+  
+  | removed parameter           | replacement property            |
+  |-----------------------------|---------------------------------|
+  | `help`                      | `fun commandHelp`               |
+  | `epilog`                    | `fun commandHelpEpilog`         |
+  | `invokeWithoutSubcommand`   | `val invokeWithoutSubcommand`   |
+  | `printHelpOnEmptyArgs`      | `val printHelpOnEmptyArgs`      |
+  | `helpTags`                  | `val helpTags`                  |
+  | `autoCompleteEnvvar`        | `val autoCompleteEnvvar`        |
+  | `allowMultipleSubcommands`  | `val allowMultipleSubcommands`  |
+  | `treatUnknownOptionsAsArgs` | `val treatUnknownOptionsAsArgs` |
+  | `hidden`                    | `val hidden`                    |
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
index b4cf79ab..ec1a2c6b 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -9,28 +9,12 @@ import com.github.ajalt.clikt.parsers.CommandLineParser
  * subcommands.
  */
 abstract class ChainedCliktCommand<T>(
-    help: String = "",
-    epilog: String = "",
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
     name: String? = null,
-    invokeWithoutSubcommand: Boolean = false,
-    printHelpOnEmptyArgs: Boolean = false,
-    helpTags: Map<String, String> = emptyMap(),
-    autoCompleteEnvvar: String? = "",
-    allowMultipleSubcommands: Boolean = false,
-    treatUnknownOptionsAsArgs: Boolean = false,
-    hidden: Boolean = false,
-) : BaseCliktCommand<ChainedCliktCommand<T>>(
-    help,
-    epilog,
-    name,
-    invokeWithoutSubcommand,
-    printHelpOnEmptyArgs,
-    helpTags,
-    autoCompleteEnvvar,
-    allowMultipleSubcommands,
-    treatUnknownOptionsAsArgs,
-    hidden
-) {
+) : BaseCliktCommand<ChainedCliktCommand<T>>(name) {
     /**
      * Perform actions after parsing is complete and this command is invoked.
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
index 9d1141c2..f6bb7573 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -8,28 +8,12 @@ import com.github.ajalt.clikt.parsers.CommandLineParser
  * A version of [CliktCommand] that supports a suspending [run] function.
  */
 abstract class SuspendingCliktCommand(
-    help: String = "",
-    epilog: String = "",
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
     name: String? = null,
-    invokeWithoutSubcommand: Boolean = false,
-    printHelpOnEmptyArgs: Boolean = false,
-    helpTags: Map<String, String> = emptyMap(),
-    autoCompleteEnvvar: String? = "",
-    allowMultipleSubcommands: Boolean = false,
-    treatUnknownOptionsAsArgs: Boolean = false,
-    hidden: Boolean = false,
-) : BaseCliktCommand<SuspendingCliktCommand>(
-    help,
-    epilog,
-    name,
-    invokeWithoutSubcommand,
-    printHelpOnEmptyArgs,
-    helpTags,
-    autoCompleteEnvvar,
-    allowMultipleSubcommands,
-    treatUnknownOptionsAsArgs,
-    hidden
-) {
+) : BaseCliktCommand<SuspendingCliktCommand>(name) {
     /**
      * Perform actions after parsing is complete and this command is invoked.
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
index fe2d8479..d9119ee7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
@@ -2,6 +2,7 @@ package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.validate
@@ -17,8 +18,10 @@ fun <T : BaseCliktCommand<*>> T.completionOption(
     help: String = "",
     hidden: Boolean = false,
 ): T = apply {
-    registerOption(option(*names, help = help, hidden = hidden, eager = true,
-        metavar = choices.joinToString("|", prefix = "(", postfix = ")")).validate {
+    registerOption(option(
+        *names, help = help, hidden = hidden, eager = true,
+        metavar = choices.joinToString("|", prefix = "(", postfix = ")")
+    ).validate {
         CompletionGenerator.throwCompletionMessage(context.command, it)
     })
 }
@@ -27,10 +30,12 @@ fun <T : BaseCliktCommand<*>> T.completionOption(
  * A subcommand that will print a completion script for the given shell when invoked.
  */
 class CompletionCommand(
-    help: String = "Generate a tab-complete script for the given shell",
-    epilog: String = "",
+    private val help: String = "Generate a tab-complete script for the given shell",
+    private val epilog: String = "",
     name: String = "generate-completion",
-) : CliktCommand(help, epilog, name) {
+) : CliktCommand(name) {
+    override fun commandHelp(context: Context): String = help
+    override fun commandHelpEpilog(context: Context): String = epilog
     private val shell by argument("shell").choice(*choices)
     override fun run() {
         val cmd = currentContext.parent?.command ?: this
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index a754c701..0b8915fa 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -17,97 +17,89 @@ import com.github.ajalt.mordant.terminal.Terminal
 @ParameterHolderDsl
 abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
     /**
-     * The help for this command. The first line is used in the usage string, and the entire string
-     * is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
      */
-    private val help: String = "",
+    name: String? = null,
+) : ParameterHolder {
+    // TODO: rename commandName commandHelp commandHelpEpilog?
     /**
-     * Text to display at the end of the full help output. It is automatically re-wrapped to the
-     * terminal width.
+     * The name of this command, used in help output.
+     *
+     * By default, this is the lowercase name of the class, with "Command" removed if it's present
      */
-    private val epilog: String = "",
+    val commandName: String = name?.takeIf { it.isNotBlank() } ?: inferCommandName()
+
     /**
-     * The name of the program to use in the help output. If not given, it is inferred from the
-     * class name.
+     * The help text for this command.
+     *
+     * ### Example:
+     *
+     * ```
+     * class Command: CliktCommand() {
+     *     override fun commandHelp(context: Context): String {
+     *         return context.theme.info("This is a command")
+     *     }
+     * }
+     * ```
      */
-    name: String? = null,
+    open fun commandHelp(context: Context): String = ""
+
+    /**
+     * Help text to display at the end of the help output, after any parameters.
+     *
+     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
+     * method.
+     */
+    open fun commandHelpEpilog(context: Context): String = ""
+
     /**
      * Used when this command has subcommands, and this command is called without a subcommand. If
      * true, [run] will be called. By default, a [PrintHelpMessage] is thrown instead.
      */
-    val invokeWithoutSubcommand: Boolean = false,
+    open val invokeWithoutSubcommand: Boolean = false
+
     /**
      * If this command is called with no values on the command line, print a help message (by
-     * throwing [PrintHelpMessage]) if this is true, otherwise run normally.
+     * throwing [PrintHelpMessage]) if this is `true`, otherwise run normally.
      */
-    val printHelpOnEmptyArgs: Boolean = false,
+    open val printHelpOnEmptyArgs: Boolean = false
+
     /**
      * Extra information about this command to pass to the help formatter.
      */
-    val helpTags: Map<String, String> = emptyMap(),
+    open val helpTags: Map<String, String> = emptyMap()
+
     /**
      * The envvar to use to enable shell autocomplete script generation. Set to null to disable
      * generation.
      */
-    internal val autoCompleteEnvvar: String? = "",
+    open val autoCompleteEnvvar: String? = ""
+
     /**
      * If true, allow multiple of this command's subcommands to be called sequentially. This will
      * disable `allowInterspersedArgs` on the context of this command and its descendants.
      */
-    internal val allowMultipleSubcommands: Boolean = false,
+    open val allowMultipleSubcommands: Boolean = false
+
     /**
      * If true, any options on the command line whose names aren't valid will be parsed as an
      * argument rather than reporting an error. You'll need to define an `argument().multiple()` to
      * collect these options, or an error will still be reported. Unknown short option flags grouped
      * with other flags on the command line will always be reported as errors.
      */
-    internal val treatUnknownOptionsAsArgs: Boolean = false,
-    /**
-     * If true, don't display this command in help output when used as a subcommand.
-     */
-    private val hidden: Boolean = false,
-) : ParameterHolder {
-    /**
-     * The name of this command, used in help output.
-     *
-     * You can set this by passing `name` to the [CliktCommand] constructor.
-     */
-    val commandName: String = name ?: inferCommandName()
-
-    /**
-     * The help text for this command.
-     *
-     * You can set this by passing `help` to the [CliktCommand] constructor, or by overriding this
-     * method if you need to build the string lazily or access the terminal or context.
-     *
-     * ### Example:
-     *
-     * ```
-     * class Command: CliktCommand() {
-     *     override fun commandHelp(context: Context): String {
-     *         return context.theme.info("This is a command")
-     *     }
-     * }
-     * ```
-     */
-    open fun commandHelp(context: Context): String {
-        return help
-    }
+    open val treatUnknownOptionsAsArgs: Boolean = false
 
     /**
-     * Help text to display at the end of the help output, after any parameters.
-     *
-     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
-     * method.
+     * If true, don't display this command in help output when used as a subcommand.
      */
-    open fun commandHelpEpilog(context: Context): String {
-        return epilog
-    }
+    open val hidden: Boolean = false
 
+    // TODO: make these all private?
     internal var _subcommands: List<T> = emptyList()
     internal val _options: MutableList<Option> = mutableListOf()
     internal val _arguments: MutableList<Argument> = mutableListOf()
-    internal val _groups: MutableList<ParameterGroup> = mutableListOf()
+    private val _groups: MutableList<ParameterGroup> = mutableListOf()
     internal var _contextConfig: Context.Builder.() -> Unit = {}
     private var _context: Context? = null
     private val _messages = mutableListOf<String>()
@@ -378,7 +370,7 @@ fun <T : BaseCliktCommand<T>, CommandT : T> CommandT.subcommands(
  * Context property values are normally inherited from the parent context, but you can override any of them
  * here.
  */
-fun <T : BaseCliktCommand<T>, U: T> U.context(block: Context.Builder.() -> Unit): U = apply {
+fun <T : BaseCliktCommand<T>, U : T> U.context(block: Context.Builder.() -> Unit): U = apply {
     // save the old config to allow multiple context calls
     val c = _contextConfig
     _contextConfig = {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index d2518f20..89a63ee9 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -14,28 +14,12 @@ import com.github.ajalt.clikt.parsers.CommandLineParser
  * Once the command line has been parsed and all the parameters are populated, [run] is called.
  */
 abstract class CliktCommand(
-    help: String = "",
-    epilog: String = "",
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
     name: String? = null,
-    invokeWithoutSubcommand: Boolean = false,
-    printHelpOnEmptyArgs: Boolean = false,
-    helpTags: Map<String, String> = emptyMap(),
-    autoCompleteEnvvar: String? = "",
-    allowMultipleSubcommands: Boolean = false,
-    treatUnknownOptionsAsArgs: Boolean = false,
-    hidden: Boolean = false,
-) : BaseCliktCommand<CliktCommand>(
-    help,
-    epilog,
-    name,
-    invokeWithoutSubcommand,
-    printHelpOnEmptyArgs,
-    helpTags,
-    autoCompleteEnvvar,
-    allowMultipleSubcommands,
-    treatUnknownOptionsAsArgs,
-    hidden
-) {
+) : BaseCliktCommand<CliktCommand>(name) {
     /**
      * Perform actions after parsing is complete and this command is invoked.
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
index dc3b6382..26bb6510 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/NoOpCliktCommand.kt
@@ -4,25 +4,11 @@ package com.github.ajalt.clikt.core
  * A [CliktCommand] that has a default implementation of [CliktCommand.run] that is a no-op.
  */
 open class NoOpCliktCommand(
-    help: String = "",
-    epilog: String = "",
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
     name: String? = null,
-    invokeWithoutSubcommand: Boolean = false,
-    printHelpOnEmptyArgs: Boolean = false,
-    helpTags: Map<String, String> = emptyMap(),
-    autoCompleteEnvvar: String? = "",
-    allowMultipleSubcommands: Boolean = false,
-    hidden: Boolean = false,
-) : CliktCommand(
-    help,
-    epilog,
-    name,
-    invokeWithoutSubcommand,
-    printHelpOnEmptyArgs,
-    helpTags,
-    autoCompleteEnvvar,
-    allowMultipleSubcommands,
-    hidden
-) {
+) : CliktCommand(name) {
     final override fun run() {}
 }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index e2a71477..930b7f84 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -119,13 +119,13 @@ private fun throwCompletionMessageIfRequested(
     context: Context,
     command: BaseCliktCommand<*>,
 ) {
-    if (command.autoCompleteEnvvar == null) return
+    val commandEnvvar = command.autoCompleteEnvvar ?: return
     val envvar = when {
-        command.autoCompleteEnvvar.isBlank() -> "_${
+        commandEnvvar.isBlank() -> "_${
             command.commandName.replace("-", "_").uppercase()
         }_COMPLETE"
 
-        else -> command.autoCompleteEnvvar
+        else -> commandEnvvar
     }
     val envval = context.readEnvvar(envvar) ?: return
     throw CompletionGenerator.getCompletionMessage(command, envval)
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
index 322e79c7..1f997404 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
@@ -3,10 +3,8 @@ package com.github.ajalt.clikt.command
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.types.int
-import com.github.ajalt.clikt.parsers.CommandLineParser
 import io.kotest.matchers.shouldBe
 import kotlinx.coroutines.test.runTest
-import kotlinx.coroutines.yield
 import kotlin.js.JsName
 import kotlin.test.Test
 
@@ -15,9 +13,8 @@ class ChainedCliktCommandTest {
     @Test
     @JsName("chained_run")
     fun `chained run`() = runTest {
-        class C : ChainedCliktCommand<List<Int>>(
-            allowMultipleSubcommands = true
-        ) {
+        class C : ChainedCliktCommand<List<Int>>() {
+            override val allowMultipleSubcommands: Boolean = true
             override fun run(value: List<Int>): List<Int> {
                 return value + 1
             }
@@ -32,7 +29,7 @@ class ChainedCliktCommandTest {
 
         val sub = Sub()
         val c: C = C().subcommands(sub)
-        val result = c.parse(listOf("sub", "2",  "sub", "3"), emptyList())
+        val result = c.parse(listOf("sub", "2", "sub", "3"), emptyList())
         result shouldBe listOf(1, 2, 3)
     }
 }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index 8d78f578..48d526dc 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.testing
 
-import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.context
-import com.github.ajalt.clikt.core.parse
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.shlex
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
@@ -14,29 +11,18 @@ class TestException(message: String) : Exception(message)
 open class TestCommand(
     called: Boolean = true,
     count: Int? = null,
-    help: String = "",
-    epilog: String = "",
+    private val help: String = "",
+    private val epilog: String = "",
     name: String? = null,
-    invokeWithoutSubcommand: Boolean = false,
-    printHelpOnEmptyArgs: Boolean = false,
-    helpTags: Map<String, String> = emptyMap(),
-    autoCompleteEnvvar: String? = "",
-    allowMultipleSubcommands: Boolean = false,
-    treatUnknownOptionsAsArgs: Boolean = false,
-    hidden: Boolean = false,
+    override val invokeWithoutSubcommand: Boolean = false,
+    override val printHelpOnEmptyArgs: Boolean = false,
+    override val helpTags: Map<String, String> = emptyMap(),
+    override val autoCompleteEnvvar: String? = "",
+    override val allowMultipleSubcommands: Boolean = false,
+    override val treatUnknownOptionsAsArgs: Boolean = false,
+    override val hidden: Boolean = false,
     noHelp: Boolean = false,
-) : CliktCommand(
-    help,
-    epilog,
-    name,
-    invokeWithoutSubcommand,
-    printHelpOnEmptyArgs,
-    helpTags,
-    autoCompleteEnvvar,
-    allowMultipleSubcommands,
-    treatUnknownOptionsAsArgs,
-    hidden
-) {
+) : CliktCommand(name) {
     init {
         context {
             terminal = parent?.terminal ?: Terminal(AnsiLevel.NONE)
@@ -44,6 +30,10 @@ open class TestCommand(
         }
     }
 
+    override fun commandHelp(context: Context): String = help
+
+    override fun commandHelpEpilog(context: Context): String = epilog
+
     private val count = count ?: if (called) 1 else 0
     private var actualCount = 0
 
diff --git a/docs/autocomplete.md b/docs/autocomplete.md
index e09aca70..3e4fcf73 100644
--- a/docs/autocomplete.md
+++ b/docs/autocomplete.md
@@ -23,11 +23,11 @@ the script once each time your CLI changes, and load it each time your start you
 
 You can generate the completion script by invoking your program with a special environment variable.
 
-You can set the variable name manually with the `autoCompleteEnvvar` parameter in the
-[`CliktCommand` constructor][CliktCommand]. By default, it's your command's name capitalized,
-with `-` replaced with `_`, and prefixed with another `_`.
-So if your command name is `my-command`, the variable would be `_MY_COMMAND_COMPLETE=bash`,
- `_MY_COMMAND_COMPLETE=zsh`, or `_MY_COMMAND_COMPLETE=fish`, depending on your current shell.
+You can set the variable name manually with by overriding the `autoCompleteEnvvar` property in
+your command. By default, it's your command's name capitalized, with `-` replaced with `_`, and
+prefixed with another `_`. So if your command name is `my-command`, the variable would be
+`_MY_COMMAND_COMPLETE=bash`, `_MY_COMMAND_COMPLETE=zsh`, or `_MY_COMMAND_COMPLETE=fish`, depending
+on your current shell.
 
 For example to activate bash autocomplete for this command:
 
diff --git a/docs/commands.md b/docs/commands.md
index f76023c4..e58513fc 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -245,7 +245,8 @@ is about to be invoked, if there is one.
 
 === "Example"
     ```kotlin
-    class Tool : CliktCommand(invokeWithoutSubcommand = true) {
+    class Tool : CliktCommand() {
+        override val invokeWithoutSubcommand = true
         override fun run() {
             val subcommand = currentContext.invokedSubcommand
             if (subcommand == null) {
@@ -255,14 +256,12 @@ is about to be invoked, if there is one.
             }
         }
     }
-
+    
     class Execute : CliktCommand() {
         override fun run() {
             echo("running subcommand")
         }
     }
-
-    fun main(args: Array<String>) = Tool().subcommands(Execute()).main(args)
     ```
 
 === "Usage 1"
@@ -319,13 +318,14 @@ For example, you can change the name of help option. These definitions are equiv
 Normally, if a command is called with no values on the command line, a usage error is printed if
 there are required parameters, or [`run`][run] is called if there aren't any.
 
-You can change this behavior by passing `printHelpOnEmptyArgs = true` to your command's
-constructor. This will cause a help message to be printed when no values are provided on the command
+You can change this behavior by passing overriding `printHelpOnEmptyArgs = true` in your command.
+This will cause a help message to be printed when no values are provided on the command
 line, regardless of the parameters in your command.
 
 === "Example"
     ```kotlin
-    class Cli : CliktCommand(printHelpOnEmptyArgs = true) {
+    class Cli : CliktCommand() {
+        override val printHelpOnEmptyArgs = true
         val arg by argument()
         override fun run() { echo("Command ran") }
     }
@@ -408,12 +408,12 @@ Some command line interfaces allow you to call more than one subcommand at a tim
 might do something like `gradle clean build publish` to run the `clean` task, then the `build` task,
 then the `publish` task, which are all subcommands of `gradle`.
 
-To do this with Clikt, pass `allowMultipleSubcommands = true` to your [`CliktCommand`][CliktCommand]
-constructor.
+To do this with Clikt, override `allowMultipleSubcommands = true` in your command.
 
 === "Example"
     ```kotlin
-    class Compiler: CliktCommand(allowMultipleSubcommands = true) {
+    class Compiler: CliktCommand() {
+        override val allowMultipleSubcommands = true
         override fun run() {
             echo("Running compiler")
         }
@@ -444,7 +444,8 @@ constructor.
     Building main.kt
     ```
 
-The parent command will [`run`][run] once, and each subcommand will `run` once each time they're called.
+The parent command will [`run`][run] once, and each subcommand will `run` once each time they're
+called.
 
 !!! warning
 
diff --git a/docs/options.md b/docs/options.md
index faf9426b..aa712047 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -949,16 +949,17 @@ You can customize or omit the warning message and help tags, or change the warni
 
 ## Unknown Options
 
-You may want to collect unknown options for manual processing. You can do this by passing
-`treatUnknownOptionsAsArgs = true` to your [`CliktCommand` constructor][CliktCommand.init]. This
-will cause Clikt to treat unknown options as positional arguments rather than reporting an error
-when one is encountered. You'll need to define an [`argument().multiple()`][argument.multiple]
-property to collect the options, otherwise an error will still be reported.
+You may want to collect unknown options for manual processing. You can do this by overriding
+`treatUnknownOptionsAsArgs = true` in your command. This will cause Clikt to treat unknown options
+as positional arguments rather than reporting an error when one is encountered. You'll need to
+define an [`argument().multiple()`][argument.multiple] property to collect the options, otherwise an
+error will still be reported.
 
 === "Example"
     ```kotlin
-    class Wrapper : CliktCommand(treatUnknownOptionsAsArgs = true) {
-        init { context { allowInterspersedArgs = false } }
+    class Wrapper : CliktCommand() {
+        init { context { allowInterspersedArgs = false }}
+        override val treatUnknownOptionsAsArgs = true
 
         val command by option().required()
         val arguments by argument().multiple()
@@ -983,12 +984,13 @@ property to collect the options, otherwise an error will still be reported.
 
 !!! warning
 
-    Multiple short options in a single token (e.g. using `-abc` to specify `-a`, `-b`, and `-c` in a single token) will
-    still report an error if it contains a mixture of known and unknown options. To avoid this, don't declare single-letter
-    names for options in commands that use `treatUnknownOptionsAsArgs`.
+    Multiple short options in a single token (e.g. using `-abc` to specify `-a`, `-b`, and `-c` in a
+    single token) will still report an error if it contains a mixture of known and unknown options. To
+    avoid this, don't declare single-letter names for options in commands that use
+    `treatUnknownOptionsAsArgs`.
 
-You'll often want to set [`allowInterspersedArgs = false`][allowInterspersedArgs] on your Context when
-using `treatUnknownOptionsAsArgs`. You may also find that subcommands are a better fit than
+You'll often want to set [`allowInterspersedArgs = false`][allowInterspersedArgs] on your Context
+when using `treatUnknownOptionsAsArgs`. You may also find that subcommands are a better fit than
 `treatUnknownOptionsAsArgs` for your use case.
 
 ## Values From Environment Variables
@@ -1033,11 +1035,10 @@ To set the envvar name manually, pass the name to
     ```
 
 You can enable automatic envvar name inference by setting the `autoEnvvarPrefix` on a command's
-[`context`][context]. This will cause all options without
-an explicit envvar name to be given an uppercase underscore-separated envvar name. Since the prefix
-is set on the [`context`][context], it is propagated to
-subcommands. If you have a subcommand called `foo` with an option `--bar`, and your prefix is
-`MY_TOOL`, the option's envvar name will be `MY_TOOL_FOO_BAR`.
+[`context`][context]. This will cause all options without an explicit envvar name to be given an
+uppercase underscore-separated envvar name. Since the prefix is set on the [`context`][context], it
+is propagated to subcommands. If you have a subcommand called `foo` with an option `--bar`, and your
+prefix is `MY_TOOL`, the option's envvar name will be `MY_TOOL_FOO_BAR`.
 
 === "Example"
     ```kotlin
diff --git a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
index c2ef8c93..2182800f 100644
--- a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
+++ b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.samples.aliases
 
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.NoOpCliktCommand
-import com.github.ajalt.clikt.core.main
-import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.multiple
 import com.github.ajalt.clikt.parameters.options.option
 import java.io.File
@@ -13,8 +10,8 @@ import java.io.File
  * @param configFile A config file containing aliases, one per line, in the form `token = alias`. Aliases can
  *   have multiple tokens (e.g. `cm = commit -m`).
  */
-class AliasedCli(private val configFile: File) : NoOpCliktCommand(
-    help = "An example that supports aliased subcommands") {
+class AliasedCli(private val configFile: File) : NoOpCliktCommand() {
+    override fun commandHelp(context: Context) = "An example that supports aliased subcommands"
     override fun aliases(): Map<String, List<String>> {
         return configFile.readLines().map { it.split("=", limit = 2) }
             .associate { it[0].trim() to it[1].trim().split(Regex("\\s+")) }
@@ -22,19 +19,23 @@ class AliasedCli(private val configFile: File) : NoOpCliktCommand(
 }
 
 
-class Push : CliktCommand(help = "push changes") {
+class Push : CliktCommand() {
+    override fun commandHelp(context: Context) = "push changes"
     override fun run() = echo("push")
 }
 
-class Pull : CliktCommand(help = "pull changes") {
+class Pull : CliktCommand() {
+    override fun commandHelp(context: Context) = "pull changes"
     override fun run() = echo("pull")
 }
 
-class Clone : CliktCommand(help = "clone a repository") {
+class Clone : CliktCommand() {
+    override fun commandHelp(context: Context) = "clone a repository"
     override fun run() = echo("clone")
 }
 
-class Commit : CliktCommand(help = "clone a repository") {
+class Commit : CliktCommand() {
+    override fun commandHelp(context: Context) = "clone a repository"
     val message by option("-m", "--message").multiple()
     override fun run() = echo("commit message=${message.joinToString("\n")}")
 }
diff --git a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
index 13a235cf..b45a6320 100644
--- a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
+++ b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.copy
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.terminal
 import com.github.ajalt.clikt.parameters.arguments.argument
@@ -10,7 +11,11 @@ import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.types.file
 import com.github.ajalt.mordant.terminal.YesNoPrompt
 
-class Copy : CliktCommand(help = "Copy SOURCE to DEST, or multiple SOURCE(s) to directory DEST.") {
+class Copy : CliktCommand() {
+    override fun commandHelp(context: Context): String {
+        return "Copy SOURCE to DEST, or multiple SOURCE(s) to directory DEST."
+    }
+
     val interactive by option("-i", "--interactive", help = "prompt before overwrite").flag()
     val recursive by option("-r", "--recursive", help = "copy directories recursively").flag()
     val source by argument().file(mustExist = true).multiple()
diff --git a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
index f70ccc95..42caa9ce 100644
--- a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
+++ b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.samples.json
 
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.context
-import com.github.ajalt.clikt.core.main
-import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.multiple
 import com.github.ajalt.clikt.parameters.options.option
@@ -17,7 +14,10 @@ class Subcommand : CliktCommand() {
     }
 }
 
-class Cli : CliktCommand(help = "An example using json files for configuration values") {
+class Cli : CliktCommand() {
+    override fun commandHelp(context: Context) =
+        "An example using json files for configuration values"
+
     init {
         context {
             valueSources(
@@ -27,7 +27,11 @@ class Cli : CliktCommand(help = "An example using json files for configuration v
         }
     }
 
-    private val option by option("-o", "--option", help = "this option takes multiple values").multiple()
+    private val option by option(
+        "-o",
+        "--option",
+        help = "this option takes multiple values"
+    ).multiple()
     private val flag by option("-f", "--flag", help = "this option is a flag").flag()
 
     override fun run() {
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
index e022fbca..0afaf971 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
@@ -1,10 +1,12 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.requireObject
 import com.github.ajalt.clikt.output.TermUi
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
+import com.github.ajalt.clikt.parameters.options.help
 import com.github.ajalt.clikt.parameters.options.multiple
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.types.file
@@ -14,8 +16,8 @@ import org.kodein.di.generic.inSet
 import org.kodein.di.generic.provider
 import java.io.File
 
-class Commit : CliktCommand(
-    help = """
+class Commit : CliktCommand() {
+    override fun commandHelp(context: Context) = """
         Commits outstanding changes.
 
         Commit changes to the given files into the repository.  You will need to
@@ -23,12 +25,14 @@ class Commit : CliktCommand(
 
         If a list of files is omitted, all changes reported by "repo status"
         will be committed.
-        """.trimIndent()) {
+        """.trimIndent()
+
     val repo: Repo by requireObject()
-    val message: List<String> by option("--message", "-m",
-        help = "The commit message. If provided multiple times " +
-                "each argument gets converted into a new line.")
-        .multiple()
+    val message: List<String> by option("--message", "-m").multiple()
+        .help(
+            "The commit message. If provided multiple times " +
+                    "each argument gets converted into a new line."
+        )
     val files: List<File> by argument()
         .file()
         .multiple()
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
index e93d5f3b..5caf4fc5 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
@@ -1,18 +1,20 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.requireObject
 import org.kodein.di.Kodein
 import org.kodein.di.generic.bind
 import org.kodein.di.generic.inSet
 import org.kodein.di.generic.provider
 
-class Delete : CliktCommand(
-    help = """
-        Deletes a repository.
+class Delete : CliktCommand() {
+    override fun commandHelp(context: Context) = """
+    Deletes a repository.
+
+    This will throw away the current repository.
+    """.trimIndent()
 
-        This will throw away the current repository.
-        """.trimIndent()) {
     val repo: Repo by requireObject()
 
     override fun run() {
diff --git a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
index 2ea4e3b7..abb654b0 100644
--- a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
+++ b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
@@ -1,9 +1,6 @@
 package com.github.ajalt.clikt.samples.repo
 
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.main
-import com.github.ajalt.clikt.core.requireObject
-import com.github.ajalt.clikt.core.subcommands
+import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.output.TermUi
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
@@ -12,16 +9,21 @@ import com.github.ajalt.clikt.parameters.options.*
 import com.github.ajalt.clikt.parameters.types.file
 import java.io.File
 
-data class RepoConfig(var home: String, val config: MutableMap<String, String>, var verbose: Boolean)
+data class RepoConfig(
+    var home: String,
+    val config: MutableMap<String, String>,
+    var verbose: Boolean,
+)
 
-class Repo : CliktCommand(
-    help = """
-        Repo is a command line tool that showcases how to build complex
-        command line interfaces with Clikt.
+class Repo : CliktCommand() {
+    override fun commandHelp(context: Context): String = """
+    Repo is a command line tool that showcases how to build complex
+    command line interfaces with Clikt.
+
+    This tool is supposed to look like a distributed version control
+    system to show how something like this can be structured.
+    """.trimIndent()
 
-        This tool is supposed to look like a distributed version control
-        system to show how something like this can be structured.
-        """.trimIndent()) {
     init {
         versionOption("1.0")
     }
@@ -44,14 +46,15 @@ class Repo : CliktCommand(
 }
 
 
-class Clone : CliktCommand(
-    help = """
-        Clones a repository.
+class Clone : CliktCommand() {
+    override fun commandHelp(context: Context): String = """
+    Clones a repository.
+
+    This will clone the repository at SRC into the folder DEST. If DEST
+    is not provided this will automatically use the last path component
+    of SRC and create that folder.
+    """.trimIndent()
 
-        This will clone the repository at SRC into the folder DEST. If DEST
-        is not provided this will automatically use the last path component
-        of SRC and create that folder.
-        """.trimIndent()) {
     val repo: RepoConfig by requireObject()
     val src: File by argument().file()
     val dest: File? by argument().file().optional()
@@ -72,12 +75,13 @@ class Clone : CliktCommand(
     }
 }
 
-class Delete : CliktCommand(
-    help = """
-        Deletes a repository.
+class Delete : CliktCommand() {
+    override fun commandHelp(context: Context): String = """
+    Deletes a repository.
+
+    This will throw away the current repository.
+    """.trimIndent()
 
-        This will throw away the current repository.
-        """.trimIndent()) {
     val repo: RepoConfig by requireObject()
 
     override fun run() {
@@ -86,13 +90,13 @@ class Delete : CliktCommand(
     }
 }
 
-class SetUser : CliktCommand(
-    name = "setuser",
-    help = """
-        Sets the user credentials.
+class SetUser : CliktCommand(name = "setuser") {
+    override fun commandHelp(context: Context): String = """
+    Sets the user credentials.
+
+    This will override the current user config.
+    """.trimIndent()
 
-        This will override the current user config.
-        """.trimIndent()) {
     val repo: RepoConfig by requireObject()
     val username: String by option(help = "The developer's shown username.")
         .prompt()
@@ -110,24 +114,24 @@ class SetUser : CliktCommand(
 }
 
 
-class Commit : CliktCommand(
-    help = """
-        Commits outstanding changes.
+class Commit : CliktCommand() {
+    override fun commandHelp(context: Context) = """
+    Commits outstanding changes.
 
-        Commit changes to the given files into the repository.  You will need to
-        "repo push" to push up your changes to other repositories.
+    Commit changes to the given files into the repository.  You will need to
+    "repo push" to push up your changes to other repositories.
+
+    If a list of files is omitted, all changes reported by "repo status"
+    will be committed.
+    """.trimIndent()
 
-        If a list of files is omitted, all changes reported by "repo status"
-        will be committed.
-        """.trimIndent()) {
     val repo: RepoConfig by requireObject()
-    val message: List<String> by option("--message", "-m",
-        help = "The commit message. If provided multiple times " +
-                "each argument gets converted into a new line.")
-        .multiple()
-    val files: List<File> by argument()
-        .file()
-        .multiple()
+    val message: List<String> by option("--message", "-m").multiple()
+        .help(
+            "The commit message. If provided multiple times " +
+                    "each argument gets converted into a new line."
+        )
+    val files: List<File> by argument().file().multiple()
 
     override fun run() {
         val msg: String = if (message.isNotEmpty()) {
diff --git a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
index f2f6a2ec..f5a82673 100644
--- a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
+++ b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.validation
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.convert
@@ -10,7 +11,9 @@ import java.net.URL
 
 data class Quad(val a: Int, val b: Int, val c: Int, val d: Int)
 
-class Cli : CliktCommand(help = "Validation examples") {
+class Cli : CliktCommand() {
+    override fun commandHelp(context: Context) = "Validation examples"
+
     val count by option(help = "A positive even number").int()
         .check("Should be a positive, even integer") { it > 0 && it % 2 == 0 }
 

From cda4a340fa3b8b82f54297e3203fc32729eabff1 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Fri, 12 Apr 2024 11:42:05 -0700
Subject: [PATCH 33/43] Rename commandHelp -> help

---
 CHANGELOG.md                                  |  5 +-
 .../clikt/completion/CompletionBuiltins.kt    |  4 +-
 .../completion/FishCompletionGenerator.kt     |  3 +-
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 24 +++++----
 .../clikt/output/MordantHelpFormatterTest.kt  |  6 +--
 .../github/ajalt/clikt/testing/TestCommand.kt |  6 +--
 docs/commands.md                              |  8 +--
 docs/documenting.md                           | 52 +++++++++----------
 docs/options.md                               |  2 +-
 .../ajalt/clikt/samples/aliases/main.kt       | 10 ++--
 .../github/ajalt/clikt/samples/copy/main.kt   |  2 +-
 .../github/ajalt/clikt/samples/json/main.kt   |  2 +-
 .../ajalt/clikt/samples/plugins/commit.kt     |  2 +-
 .../ajalt/clikt/samples/plugins/delete.kt     |  2 +-
 .../github/ajalt/clikt/samples/repo/main.kt   | 10 ++--
 .../ajalt/clikt/samples/validation/main.kt    |  7 ++-
 16 files changed, 74 insertions(+), 71 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd348151..0fd4adc5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@
 - In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
 - Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.
 - **Breaking Change:** Removed the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
-  
+
   | removed parameter           | replacement property            |
   |-----------------------------|---------------------------------|
   | `help`                      | `fun commandHelp`               |
@@ -23,7 +23,8 @@
   | `autoCompleteEnvvar`        | `val autoCompleteEnvvar`        |
   | `allowMultipleSubcommands`  | `val allowMultipleSubcommands`  |
   | `treatUnknownOptionsAsArgs` | `val treatUnknownOptionsAsArgs` |
-  | `hidden`                    | `val hidden`                    |
+  | `hidden`                    | `val hiddenFromHelp`            |
+- The following methods on `CliktCommand` have been renamed: `commandHelp` -> `help`, `commandHelpEpilog` -> `epilog`. The old names are deprecated.
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
index d9119ee7..e2bbd04d 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt
@@ -34,8 +34,8 @@ class CompletionCommand(
     private val epilog: String = "",
     name: String = "generate-completion",
 ) : CliktCommand(name) {
-    override fun commandHelp(context: Context): String = help
-    override fun commandHelpEpilog(context: Context): String = epilog
+    override fun help(context: Context): String = help
+    override fun helpEpilog(context: Context): String = epilog
     private val shell by argument("shell").choice(*choices)
     override fun run() {
         val cmd = currentContext.parent?.command ?: this
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
index 48509ed7..dc7b0b9f 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt
@@ -2,7 +2,6 @@ package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.completion.CompletionCandidates.Custom.ShellType
 import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.options.Option
 
 internal object FishCompletionGenerator {
@@ -57,7 +56,7 @@ internal object FishCompletionGenerator {
 
             append("-a $commandName ")
 
-            val help = command.commandHelp(command.currentContext).replace("'", "\\'")
+            val help = command.help(command.currentContext).replace("'", "\\'")
             if (help.isNotBlank()) {
                 append("-d '${help}'")
             }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 0b8915fa..3fd171c8 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -22,7 +22,6 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
      */
     name: String? = null,
 ) : ParameterHolder {
-    // TODO: rename commandName commandHelp commandHelpEpilog?
     /**
      * The name of this command, used in help output.
      *
@@ -43,15 +42,18 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
      * }
      * ```
      */
-    open fun commandHelp(context: Context): String = ""
+    open fun help(context: Context): String = ""
+
+    @Deprecated("Method renamed to `help`", ReplaceWith("help(context)"))
+    open fun commandHelp(context: Context): String = help(context)
 
     /**
      * Help text to display at the end of the help output, after any parameters.
-     *
-     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
-     * method.
      */
-    open fun commandHelpEpilog(context: Context): String = ""
+    open fun helpEpilog(context: Context): String = ""
+
+    @Deprecated("Method renamed to `helpEpilog`", ReplaceWith("helpEpilog(context)"))
+    open fun commandHelpEpilog(context: Context): String = helpEpilog(context)
 
     /**
      * Used when this command has subcommands, and this command is called without a subcommand. If
@@ -93,7 +95,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
     /**
      * If true, don't display this command in help output when used as a subcommand.
      */
-    open val hidden: Boolean = false
+    open val hiddenFromHelp: Boolean = false
 
     // TODO: make these all private?
     internal var _subcommands: List<T> = emptyList()
@@ -154,7 +156,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
                     c.commandName,
                     c.shortHelp(currentContext),
                     c.helpTags
-                ).takeUnless { c.hidden }
+                ).takeUnless { c.hiddenFromHelp }
             }
         ).flatten()
     }
@@ -185,7 +187,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
 
     /** The help displayed in the commands list when this command is used as a subcommand. */
     protected fun shortHelp(context: Context): String =
-        Regex("""\s*(?:```)?\s*(.+)""").find(commandHelp(context))?.groups?.get(1)?.value ?: ""
+        Regex("""\s*(?:```)?\s*(.+)""").find(help(context))?.groups?.get(1)?.value ?: ""
 
     /** The names of all direct children of this command */
     fun registeredSubcommandNames(): List<String> = _subcommands.map { it.commandName }
@@ -279,8 +281,8 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
         val programName = cmd.getCommandNameWithParents()
         return ctx.helpFormatter(ctx).formatHelp(
             error as? UsageError,
-            cmd.commandHelp(ctx),
-            cmd.commandHelpEpilog(ctx),
+            cmd.help(ctx),
+            cmd.helpEpilog(ctx),
             cmd.allHelpParams(),
             programName
         )
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
index 1bc28c08..bd072065 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt
@@ -444,7 +444,7 @@ class MordantHelpFormatterTest {
             TestCommand(name = "foo", help = "some thing to live by"),
             TestCommand(name = "bar", help = "another argument"),
             TestCommand(name = "baz"),
-            TestCommand(name = "qux", hidden = true),
+            TestCommand(name = "qux", hiddenFromHelp = true),
         )
         doTest(
             """
@@ -778,10 +778,10 @@ class MordantHelpFormatterTest {
         }
 
         class C: TestCommand(name="prog") {
-            override fun commandHelp(context: Context): String =
+            override fun help(context: Context): String =
                 context.theme.danger("command help")
 
-            override fun commandHelpEpilog(context: Context): String =
+            override fun helpEpilog(context: Context): String =
                 context.theme.danger("command epilog")
 
             val o by option("--aa", "-a")
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
index 48d526dc..62ecea16 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt
@@ -20,7 +20,7 @@ open class TestCommand(
     override val autoCompleteEnvvar: String? = "",
     override val allowMultipleSubcommands: Boolean = false,
     override val treatUnknownOptionsAsArgs: Boolean = false,
-    override val hidden: Boolean = false,
+    override val hiddenFromHelp: Boolean = false,
     noHelp: Boolean = false,
 ) : CliktCommand(name) {
     init {
@@ -30,9 +30,9 @@ open class TestCommand(
         }
     }
 
-    override fun commandHelp(context: Context): String = help
+    override fun help(context: Context): String = help
 
-    override fun commandHelpEpilog(context: Context): String = epilog
+    override fun helpEpilog(context: Context): String = epilog
 
     private val count = count ?: if (called) 1 else 0
     private var actualCount = 0
diff --git a/docs/commands.md b/docs/commands.md
index e58513fc..172d1260 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -101,12 +101,14 @@ command names.
 
 === "Example"
     ```kotlin
-    class Tool : CliktCommand(help = "A tool that runs") {
+    class Tool : CliktCommand() {
+        override fun help(context: Context) = "A tool that runs"
         val verbose by option().flag("--no-verbose")
         override fun run() = Unit
     }
 
-    class Execute : CliktCommand(help = "Execute the command") {
+    class Execute : CliktCommand() {
+        override fun help(context: Context) = "Execute the command"
         val name by option()
         override fun run() = Unit
     }
@@ -252,7 +254,7 @@ is about to be invoked, if there is one.
             if (subcommand == null) {
                 echo("invoked without a subcommand")
             } else {
-                echo("about to run ${subcommand.commandName}")
+                echo("about to run ${subcommand.name}")
             }
         }
     }
diff --git a/docs/documenting.md b/docs/documenting.md
index 6c75ac91..ee68d3c4 100644
--- a/docs/documenting.md
+++ b/docs/documenting.md
@@ -7,43 +7,40 @@ and set it on the [command's context][customizing-contexts].
 
 ## Help Texts
 
-[Commands][Commands] and parameters accept a `help` argument. Commands also accept an `epilog`
-argument, which is printed after the parameters and commands on the help page. All text is
-automatically trimmed of leading indentation and re-wrapped to the terminal width.
-
-As an alternative to passing your help strings as function arguments, you can also use the `help()`
-extensions for your options, and override `commandHelp` and `commandHelpEpilog` on your commands.
-These methods can access the terminal theme on the context to add color to your help text.
+You can add help text to commands and parameters. For parameters, you can pass a `help` string or 
+use the `help()` extension. For commands, you can override the `help` and `helpEpilog` methods.
 
 === "Example"
     ```kotlin
-    class Hello : CliktCommand(help = """
+    class Hello : CliktCommand() {
+        override fun help(context: Context) = """
         This script prints <name> <count> times.
-
+    
         <count> must be a positive number, and defaults to 1.
-        """
-    ) {
-        val count by option("-c", "--count", metavar="count", help = "number of greetings").int().default(1)
-        val name by argument()
-        override fun run() = repeat(count) { echo("Hello $name!") }
+        """.trimIndent()
+        val count by option("-c", "--count", metavar="count", help="number of greetings")
+            .int().default(1)
+        val name by argument(help="The name to greet")
+        override fun run() = repeat(count) { echo("Hello $commandName!") }
     }
     ```
 
 === "Alternate style"
     ```kotlin
     class Hello : CliktCommand() {
-        override fun commandHelp(context: Context): String {
+        override fun help(context: Context): String {
             val style = context.theme.info
             return """
-                This script prints ${style("<name>")} ${style("<count>")} times.
+            This script prints ${style("<name>")} ${style("<count>")} times.
     
-                ${style("<count>")} must be a positive number, and defaults to 1.
+            ${style("<count>")} must be a positive number, and defaults to 1.
             """.trimIndent()
         }
     
         val count by option("-c", "--count", metavar="count").int().default(1)
             .help { theme.success("number of greetings") }
         val name by argument()
+            .help("The name to greet")
         override fun run() = repeat(count) { echo("Hello $name!") }
     }
     ```
@@ -158,13 +155,17 @@ They have a short help string which is the first line of their help.
     ```kotlin
     class Tool : NoOpCliktCommand()
 
-    class Execute : NoOpCliktCommand(help = """
-        Execute the command.
+    class Execute : NoOpCliktCommand() {
+        override fun help(context: Context) = """
+            Execute the command.
 
-        The command will be executed.
-        """)
+            The command will be executed.
+            """.trimIndent()
+    }
 
-    class Abort : NoOpCliktCommand(help="Kill any running commands.")
+    class Abort : NoOpCliktCommand() {
+        override fun help(context: Context) = "Kill any running commands."
+    }
     ```
 
 === "Usage"
@@ -463,10 +464,9 @@ You can localize error messages by implementing [`Localization`][Localization] a
         // ... override the rest of the strings here
     }
 
-    class I18NTool : NoOpCliktCommand(help = "𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒") {
-        init {
-            context { localization = CursiveLocalization() }
-        }
+    class I18NTool : NoOpCliktCommand() {
+        override fun help(context: Context) = "𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒"
+        init { context { localization = CursiveLocalization() } }
     }
     ```
 
diff --git a/docs/options.md b/docs/options.md
index aa712047..0507ea30 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -868,7 +868,7 @@ You can define your own version option like this:
 class Cli : NoOpCliktCommand() {
     init {
         eagerOption("--version") {
-            throw PrintMessage("$commandName version 1.0")
+            throw PrintMessage("$name version 1.0")
         }
     }
 }
diff --git a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
index 2182800f..7a010dcd 100644
--- a/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
+++ b/samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt
@@ -11,7 +11,7 @@ import java.io.File
  *   have multiple tokens (e.g. `cm = commit -m`).
  */
 class AliasedCli(private val configFile: File) : NoOpCliktCommand() {
-    override fun commandHelp(context: Context) = "An example that supports aliased subcommands"
+    override fun help(context: Context) = "An example that supports aliased subcommands"
     override fun aliases(): Map<String, List<String>> {
         return configFile.readLines().map { it.split("=", limit = 2) }
             .associate { it[0].trim() to it[1].trim().split(Regex("\\s+")) }
@@ -20,22 +20,22 @@ class AliasedCli(private val configFile: File) : NoOpCliktCommand() {
 
 
 class Push : CliktCommand() {
-    override fun commandHelp(context: Context) = "push changes"
+    override fun help(context: Context) = "push changes"
     override fun run() = echo("push")
 }
 
 class Pull : CliktCommand() {
-    override fun commandHelp(context: Context) = "pull changes"
+    override fun help(context: Context) = "pull changes"
     override fun run() = echo("pull")
 }
 
 class Clone : CliktCommand() {
-    override fun commandHelp(context: Context) = "clone a repository"
+    override fun help(context: Context) = "clone a repository"
     override fun run() = echo("clone")
 }
 
 class Commit : CliktCommand() {
-    override fun commandHelp(context: Context) = "clone a repository"
+    override fun help(context: Context) = "clone a repository"
     val message by option("-m", "--message").multiple()
     override fun run() = echo("commit message=${message.joinToString("\n")}")
 }
diff --git a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
index b45a6320..6023ceb7 100644
--- a/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
+++ b/samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt
@@ -12,7 +12,7 @@ import com.github.ajalt.clikt.parameters.types.file
 import com.github.ajalt.mordant.terminal.YesNoPrompt
 
 class Copy : CliktCommand() {
-    override fun commandHelp(context: Context): String {
+    override fun help(context: Context): String {
         return "Copy SOURCE to DEST, or multiple SOURCE(s) to directory DEST."
     }
 
diff --git a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
index 42caa9ce..5f7d238c 100644
--- a/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
+++ b/samples/json/src/main/kotlin/com/github/ajalt/clikt/samples/json/main.kt
@@ -15,7 +15,7 @@ class Subcommand : CliktCommand() {
 }
 
 class Cli : CliktCommand() {
-    override fun commandHelp(context: Context) =
+    override fun help(context: Context) =
         "An example using json files for configuration values"
 
     init {
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
index 0afaf971..e49d59f1 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/commit.kt
@@ -17,7 +17,7 @@ import org.kodein.di.generic.provider
 import java.io.File
 
 class Commit : CliktCommand() {
-    override fun commandHelp(context: Context) = """
+    override fun help(context: Context) = """
         Commits outstanding changes.
 
         Commit changes to the given files into the repository.  You will need to
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
index 5caf4fc5..21d752c9 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/delete.kt
@@ -9,7 +9,7 @@ import org.kodein.di.generic.inSet
 import org.kodein.di.generic.provider
 
 class Delete : CliktCommand() {
-    override fun commandHelp(context: Context) = """
+    override fun help(context: Context) = """
     Deletes a repository.
 
     This will throw away the current repository.
diff --git a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
index abb654b0..2d9d33dc 100644
--- a/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
+++ b/samples/repo/src/main/kotlin/com/github/ajalt/clikt/samples/repo/main.kt
@@ -16,7 +16,7 @@ data class RepoConfig(
 )
 
 class Repo : CliktCommand() {
-    override fun commandHelp(context: Context): String = """
+    override fun help(context: Context): String = """
     Repo is a command line tool that showcases how to build complex
     command line interfaces with Clikt.
 
@@ -47,7 +47,7 @@ class Repo : CliktCommand() {
 
 
 class Clone : CliktCommand() {
-    override fun commandHelp(context: Context): String = """
+    override fun help(context: Context): String = """
     Clones a repository.
 
     This will clone the repository at SRC into the folder DEST. If DEST
@@ -76,7 +76,7 @@ class Clone : CliktCommand() {
 }
 
 class Delete : CliktCommand() {
-    override fun commandHelp(context: Context): String = """
+    override fun help(context: Context): String = """
     Deletes a repository.
 
     This will throw away the current repository.
@@ -91,7 +91,7 @@ class Delete : CliktCommand() {
 }
 
 class SetUser : CliktCommand(name = "setuser") {
-    override fun commandHelp(context: Context): String = """
+    override fun help(context: Context): String = """
     Sets the user credentials.
 
     This will override the current user config.
@@ -115,7 +115,7 @@ class SetUser : CliktCommand(name = "setuser") {
 
 
 class Commit : CliktCommand() {
-    override fun commandHelp(context: Context) = """
+    override fun help(context: Context) = """
     Commits outstanding changes.
 
     Commit changes to the given files into the repository.  You will need to
diff --git a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
index f5a82673..b2b70b55 100644
--- a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
+++ b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
@@ -1,8 +1,7 @@
 package com.github.ajalt.clikt.samples.validation
 
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.core.main
+import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.convert
 import com.github.ajalt.clikt.parameters.options.*
@@ -12,7 +11,7 @@ import java.net.URL
 data class Quad(val a: Int, val b: Int, val c: Int, val d: Int)
 
 class Cli : CliktCommand() {
-    override fun commandHelp(context: Context) = "Validation examples"
+    override fun help(context: Context) = "Validation examples"
 
     val count by option(help = "A positive even number").int()
         .check("Should be a positive, even integer") { it > 0 && it % 2 == 0 }

From 8dafb16b20a5ab7990c93c2109bc62f97b93d738 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 13 Apr 2024 09:17:05 -0700
Subject: [PATCH 34/43] Add docs for tokenize

---
 .../github/ajalt/clikt/core/BaseCliktCommand.kt   |  2 --
 .../ajalt/clikt/parsers/CommandLineParser.kt      | 15 ++++++++++++++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 3fd171c8..54586110 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -97,7 +97,6 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
      */
     open val hiddenFromHelp: Boolean = false
 
-    // TODO: make these all private?
     internal var _subcommands: List<T> = emptyList()
     internal val _options: MutableList<Option> = mutableListOf()
     internal val _arguments: MutableList<Argument> = mutableListOf()
@@ -265,7 +264,6 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
         _groups += group
     }
 
-    // TODO: all of these final functions could be extensions?
     /**
      * Return the help string for this command, optionally with an [error].
      *
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 930b7f84..3e654ab9 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -8,11 +8,24 @@ import com.github.ajalt.clikt.output.defaultLocalization
 
 // TODO: docs, changelog
 object CommandLineParser {
+    /**
+     * Split a command line into a list of argv tokens.
+     *
+     * ### Example
+     * ```
+     * tokenize("--text 'hello world'") == listOf("--text", "hello world")
+     * ```
+     *
+     * @param commandLine The command line to split
+     * @param filename The name of the file being parsed. This is used in error messages.
+     * @param localization The localization to use for error messages
+     */
     fun tokenize(
         commandLine: String,
+        filename: String = "",
         localization: Localization = defaultLocalization,
     ): List<String> {
-        return shlex("TODO", commandLine, localization)// TODO shlex
+        return shlex(filename, commandLine, localization)
     }
 
     inline fun <T : BaseCliktCommand<T>> main(

From 1c919ff6040bf4eb0981691dc75109cb13bb3076 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sat, 13 Apr 2024 11:37:09 -0700
Subject: [PATCH 35/43] Add docs for new command types

---
 CHANGELOG.md                                  |  7 ++
 .../clikt/command/ChainedCliktCommand.kt      |  7 +-
 .../clikt/command/SuspendingCliktCommand.kt   |  1 -
 .../com/github/ajalt/clikt/core/Context.kt    |  3 -
 .../ajalt/clikt/parsers/CommandLineParser.kt  | 32 ++++++-
 .../github/ajalt/clikt/parsers/Invocation.kt  | 95 ++++++++++++++++---
 .../ajalt/clikt/parsers/ParserInternals.kt    |  1 -
 .../ajalt/clikt/testing/CliktTesting.kt       |  1 +
 docs/commands.md                              | 68 +++++++++++--
 docs/exceptions.md                            |  8 +-
 docs/options.md                               |  9 +-
 docs/quickstart.md                            | 24 ++++-
 docs/testing.md                               |  4 +-
 docs/utilities.md                             |  1 -
 .../ajalt/clikt/samples/helpformat/main.kt    |  5 +-
 15 files changed, 221 insertions(+), 45 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0fd4adc5..c92a58f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,12 @@
 ### Added
 - Added `NoSuchArgument` exception that is thrown when too many arguments were given on the command line. Previously, a less specific `UsageError` was thrown instead.
 - Added `CliktUtil.exitProcess`, which is a cross-platform way to exit the process with a status code.
+- Added `CommandLineParser.tokenize` that splits a string into argv tokens.
+- Added `CommandLineParser` that provides functions for parsing and finalizing commands manually for more control.
+- Added `Context.invokedSubcommands` that contains all subcommands of the current command that are going to be invoked when `allowMultipleSubcommands` is `true`.
+- Added `SuspendingCliktCommand` that has a `suspend fun run` method, allowing you to use coroutines in your commands.
+- Added `ChainedCliktCommand` that allows you to return a value from your `run` method and pass it to the next command in the chain.
+
 ## 4.4.0
 ### Added
 - Publish `linuxArm64` and `wasmJs` targets.
@@ -25,6 +31,7 @@
   | `treatUnknownOptionsAsArgs` | `val treatUnknownOptionsAsArgs` |
   | `hidden`                    | `val hiddenFromHelp`            |
 - The following methods on `CliktCommand` have been renamed: `commandHelp` -> `help`, `commandHelpEpilog` -> `epilog`. The old names are deprecated.
+- **Breaking Change:** `CliktCommand.main` and `CliktCommand.parse` are now extension functions rather than methods.
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
index ec1a2c6b..e230aa75 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -3,10 +3,11 @@ package com.github.ajalt.clikt.command
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.CommandLineParser
 
-// TODO: md docs, changelog
 /**
  * A version of [CliktCommand] that returns a value from the [run] function, which is then passed to
  * subcommands.
+ *
+ * This command works best if you set [allowMultipleSubcommands] to `true`.
  */
 abstract class ChainedCliktCommand<T>(
     /**
@@ -59,8 +60,8 @@ fun <T> ChainedCliktCommand<T>.main(argv: List<String>, initial: T): T {
  *
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
-fun <T> ChainedCliktCommand<T>.main(argv: Array<out String>, initial: T) {
-    main(argv.asList(), initial)
+fun <T> ChainedCliktCommand<T>.main(argv: Array<out String>, initial: T): T {
+    return main(argv.asList(), initial)
 }
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
index f6bb7573..d2c31117 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -3,7 +3,6 @@ package com.github.ajalt.clikt.command
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.CommandLineParser
 
-// TODO: md docs
 /**
  * A version of [CliktCommand] that supports a suspending [run] function.
  */
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 dcb06e18..fc39c246 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
@@ -109,7 +109,6 @@ class Context private constructor(
     var obj: Any?,
 ) {
 
-    // TODO: add this to web docs and changelog
     /**
      * All invoked subcommands, in the order they were invoked.
      *
@@ -128,8 +127,6 @@ class Context private constructor(
      */
     val invokedSubcommand: BaseCliktCommand<*>? get() = invokedSubcommands.firstOrNull()
 
-
-
     /**
      * If true, an error was previously encountered while parsing the command line, but parsing is
      * continuing to collect any more errors into a [MultiUsageError].
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index 3e654ab9..a4b9632f 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -6,7 +6,9 @@ import com.github.ajalt.clikt.internal.*
 import com.github.ajalt.clikt.output.Localization
 import com.github.ajalt.clikt.output.defaultLocalization
 
-// TODO: docs, changelog
+/**
+ * Methods for parsing command lines and running commands manually.
+ */
 object CommandLineParser {
     /**
      * Split a command line into a list of argv tokens.
@@ -28,6 +30,10 @@ object CommandLineParser {
         return shlex(filename, commandLine, localization)
     }
 
+    /**
+     * Call [parseAndRun] with the given [command] and [argv]. If an error is thrown, exit the
+     * process with the error's [status code][CliktError.statusCode].
+     */
     inline fun <T : BaseCliktCommand<T>> main(
         command: T,
         argv: List<String>,
@@ -55,7 +61,12 @@ object CommandLineParser {
         return result
     }
 
-    // TODO: docs throws
+    /**
+     * [Finalize][finalize] and [run][runCommand] all invoked commands.
+     *
+     * @throws CliktError if an error occurred while parsing or of any occur while finalizing or
+     * running the commands.
+     */
     inline fun <T : BaseCliktCommand<T>> run(
         rootInvocation: CommandInvocation<T>,
         runCommand: (T) -> Unit,
@@ -71,12 +82,25 @@ object CommandLineParser {
         }
     }
 
-    // TODO: docs does not throw
+    /**
+     * Parse a command line and return the result.
+     *
+     * This function does not throw exceptions. If parsing errors occur, they will be in the returned
+     * result.
+     *
+     * This function does not [run] the command or [finalize] the invocations.
+     */
     fun <T : BaseCliktCommand<T>> parse(command: T, argv: List<String>): CommandLineParseResult<T> {
         return parseArgv(command, argv)
     }
 
-    // TODO: docs throws
+    /**
+     * Finalize a command invocation, converting and setting the values for all options and other
+     * parameters. This function does not [run] the command.
+     *
+     * @throws CliktError If the [invocation] had any errors or if any parameters fail to finalize,
+     * such as if a required option is missing or a value could not be converted.
+     */
     fun finalize(invocation: CommandInvocation<*>) {
         val command = invocation.command
         val context = command.currentContext
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index 16b1d553..ba286c31 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -8,38 +8,104 @@ import com.github.ajalt.clikt.parameters.options.Option
 
 /**
  * The output of parsing a single option and its values.
- *
- * @param name The name that was used to invoke the option. May be empty if the value was not retrieved
- *   from the command line (e.g. values from environment variables).
- * @param values The values provided to the option. All invocations passed to [Option.finalize]
- *   will have a size in the range of [Option.nvalues].
  */
-data class Invocation(val name: String, val values: List<String>)
+data class Invocation(
+    /**
+     * The name that was used to invoke the option. May be empty if the value was not retrieved
+     * from the command line (e.g. values from environment variables).
+     */
+    val name: String,
+    /**
+     * The values provided to the option. This will always have a size in the range of
+     * [Option.nvalues] for the option that was invoked.
+     */
+    val values: List<String>,
+)
 
-// TODO: docs
-data class ArgumentInvocation(val argument: Argument, val values: List<String>)
+/**
+ * The output of parsing a single argument and its values.
+ */
+data class ArgumentInvocation(
+    /**
+     * The argument that was invoked.
+     */
+    val argument: Argument,
+    /**
+     * The values provided to the argument. This will always have a size in the range of
+     * [Argument.nvalues] for the argument that was invoked.
+     */
+    val values: List<String>,
+)
 
-data class CommandInvocation<T: BaseCliktCommand<T>>(
+/**
+ * The output of parsing a single command and its options and arguments.
+ */
+data class CommandInvocation<T : BaseCliktCommand<T>>(
     val command: T,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
+    /**
+     * The subcommands of this command that were invoked.
+     *
+     * This list will have at most one entry unless [allowMultipleSubcommands][BaseCliktCommand.allowMultipleSubcommands] is
+     * true.
+     */
     val subcommandInvocations: List<CommandInvocation<T>>,
+    /**
+     * The errors that occurred while parsing this command.
+     */
     val errors: List<CliktError>,
 )
 
-class CommandLineParseResult<T: BaseCliktCommand<T>>(
+/**
+ * The result of parsing a command line.
+ */
+class CommandLineParseResult<T : BaseCliktCommand<T>>(
+    /**
+     * The root command that was parsed.
+     */
     val invocation: CommandInvocation<T>,
+    /**
+     * The original command line tokens that were passed to `parse`.
+     */
     val originalArgv: List<String>,
+    /**
+     * The full argv after expanding any [argument file tokens][Context.argumentFileReader] or
+     * [aliases][BaseCliktCommand.aliases].
+     */
     val expandedArgv: List<String>,
 )
 
-fun <T: BaseCliktCommand<T>> CommandInvocation<T>.flatten(): FlatInvocations<T> {
+/**
+ * Flatten a command invocation into a sequence of invocations.
+ *
+ * This will yield the root command invocation, followed by all subcommand invocations in the order
+ * they were invoked on the command line.
+ *
+ * You can use this to avoid recursion when processing invocations.
+ *
+ * ### Example
+ *
+ * ```
+ * val invocations = rootInvocation.flatten()
+ * try {
+ *   for (inv in invocations) {
+ *     finalize(inv)
+ *     run(inv.command)
+ *   }
+ * } finally {
+ *   invocations.close()
+ * }
+ * ```
+ */
+fun <T : BaseCliktCommand<T>> CommandInvocation<T>.flatten(): FlatInvocations<T> {
     return FlatInvocations(this)
 }
 
-class FlatInvocations<T: BaseCliktCommand<T>> internal constructor(
+// TODO: this should be an AutoClosable once that interface is stable
+class FlatInvocations<T : BaseCliktCommand<T>> internal constructor(
     root: CommandInvocation<T>,
-): Sequence<CommandInvocation<T>> {
+) : Sequence<CommandInvocation<T>> {
     private val closables = mutableListOf<Context>()
     private val seq = sequence {
         suspend fun SequenceScope<CommandInvocation<T>>.yieldSubs(inv: CommandInvocation<T>) {
@@ -55,6 +121,9 @@ class FlatInvocations<T: BaseCliktCommand<T>> internal constructor(
 
     override fun iterator(): Iterator<CommandInvocation<T>> = seq.iterator()
 
+    /**
+     * [Close][Context.close] all open contexts of invoked commands.
+     */
     fun close() {
         closables.forEach { it.close() }
     }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index 0968d5bb..cb687df7 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -57,7 +57,6 @@ private class CommandParser<T : BaseCliktCommand<T>>(
     private val ancestorMultipleSubcommands = context.ancestors()
         .firstOrNull { it.command.allowMultipleSubcommands }
         ?.command?._subcommands?.associate {
-            // TODO We could avoid this cast if Context was generic
             @Suppress("UNCHECKED_CAST")
             it.commandName to it as T
         } ?: emptyMap()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
index d0098f2a..a66cacc5 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
@@ -126,6 +126,7 @@ fun CliktCommand.test(
  * @param height The height of the terminal
  */
 fun CliktCommand.test(
+    // TODO make test() work with base command
     argv: Array<String>,
     stdin: String = "",
     envvars: Map<String, String> = emptyMap(),
diff --git a/docs/commands.md b/docs/commands.md
index 172d1260..a41a296d 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -239,11 +239,10 @@ the property, you should use [`currentContext.findOrSetObject`][Context.findOrSe
 
 ## Running Parent Command Without Children
 
-Normally, if a command has children, [`run`][run] is not called unless a child
-command is invoked on the command line. Instead, `--help` is called on the parent. If you want to
-change this behavior to always call `run()` on the parent, you can do so by setting
-`invokeWithoutSubcommand` to `true`. The `Context` will then have information on the subcommand that
-is about to be invoked, if there is one.
+Normally, if a command has children, [`run`][run] is not called unless a child command is invoked on
+the command line. Instead, `--help` is called on the parent. If you want to change this behavior to
+always call `run()` on the parent, you can do so by setting `invokeWithoutSubcommand` to `true`. The
+`Context` will then have information on the subcommand that is about to be invoked, if there is one.
 
 === "Example"
     ```kotlin
@@ -458,9 +457,66 @@ called.
     Subcommands of a command with `allowMultipleSubcommands=true` can themselves have subcommands, but
     cannot have `allowMultipleSubcommands=true`.
 
+## Command pipelines
+
+If you have [multiple subcommands](#chaining-and-repeating-subcommands) you might want to pass the
+output of one subcommand to the next. For example, the [ImageMagick](https://imagemagick.org) tool
+lets you apply a series of transformations to an image by invoking multiple subcommands.
+
+To do this with Clikt, you could pass your output through the
+[`Context.obj`](#nested-handling-and-contexts), but another option is to use a
+[ChainedCliktCommand], which allows you to return values from your `run` function that will be
+passed to the next subcommand.
+
+In this example, we'll write simple text editing pipeline that takes an initial string, and then
+applies a series of transformations to it, printing the final result:
+
+=== "Example"
+    ```kotlin
+    class EditText : ChainedCliktCommand<String>() {
+        override val allowMultipleSubcommands: Boolean = true
+        val text by argument()
+        override fun run(value: String): String = text
+    }
+
+    class RepeatText : ChainedCliktCommand<String>("repeat") {
+        val count by option().int().default(1)
+        override fun run(value: String): String {
+            return value.repeat(count)
+        }
+    }
+
+    class UppercaseText : ChainedCliktCommand<String>("uppercase") {
+        override fun run(value: String): String {
+            return value.uppercase()
+        }
+    }
+
+    class ReplaceText : ChainedCliktCommand<String>("replace") {
+        val oldValue by argument()
+        val newValue by argument()
+        override fun run(value: String): String {
+            return value.replace(oldValue, newValue)
+        }
+    }
+
+    fun main(args: Array<String>) {
+        val command = EditText()
+            .subcommands(RepeatText(), UppercaseText(), ReplaceText())
+        val result = command.main(args, "")
+        command.echo(result)
+    }
+    ```
+
+=== "Usage"
+    ```text
+    $ ./edit-text 'hello ' uppercase repeat --count=3 replace H Y
+    YELLO YELLO YELLO
+    ```
 
 [argument.multiple]:             api/clikt/com.github.ajalt.clikt.parameters.arguments/multiple.html
 [builder.obj]:                   api/clikt/com.github.ajalt.clikt.core/-context/-builder/obj.html
+[ChainedCliktCommand]:           api/clikt/com.github.ajalt.clikt.command/-chained-clikt-command/index.html
 [CliktCommand]:                  api/clikt/com.github.ajalt.clikt.core/-clikt-command/index.html
 [Context.findOrSetObject]:       api/clikt/com.github.ajalt.clikt.core/find-or-set-object.html
 [Context.obj]:                   api/clikt/com.github.ajalt.clikt.core/-context/obj.html
@@ -471,7 +527,7 @@ called.
 [findObject]:                    api/clikt/com.github.ajalt.clikt.core/find-object.html
 [findOrSetObject]:               api/clikt/com.github.ajalt.clikt.core/find-or-set-object.html
 [interspersed]:                  api/clikt/com.github.ajalt.clikt.core/-context/allow-interspersed-args.html
-[issueMessage]:                  api/clikt/com.github.ajalt.clikt.core/-clikt-command/issue-message.html
+[issueMessage]:                  api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/issue-message.html
 [printing-to-stdout-and-stderr]: quickstart.md#printing-to-stdout-and-stderr
 [requireObject]:                 api/clikt/com.github.ajalt.clikt.core/require-object.html
 [run]:                           api/clikt/com.github.ajalt.clikt.core/-clikt-command/run.html
diff --git a/docs/exceptions.md b/docs/exceptions.md
index deaac297..42475741 100644
--- a/docs/exceptions.md
+++ b/docs/exceptions.md
@@ -71,20 +71,20 @@ The following subclasses exist:
 [BadParameterValue]:               api/clikt/com.github.ajalt.clikt.core/-bad-parameter-value/index.html
 [CliktError]:                      api/clikt/com.github.ajalt.clikt.core/-clikt-error/index.html
 [convert]:                         api/clikt/com.github.ajalt.clikt.parameters.options/convert.html
-[echoFormattedHelp]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/echo-formatted-help.html
+[echoFormattedHelp]:               api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/echo-formatted-help.html
 [FileNotFound]:                    api/clikt/com.github.ajalt.clikt.core/-file-not-found/index.html
-[getFormattedHelp]:                api/clikt/com.github.ajalt.clikt.core/-clikt-command/get-formatted-help.html
+[getFormattedHelp]:                api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/get-formatted-help.html
 [IncorrectArgumentValueCount]:     api/clikt/com.github.ajalt.clikt.core/-incorrect-argument-value-count/index.html
 [IncorrectOptionValueCount]:       api/clikt/com.github.ajalt.clikt.core/-incorrect-option-value-count/index.html
 [InvalidFileFormat]:               api/clikt/com.github.ajalt.clikt.core/-invalid-file-format/index.html
-[main]:                            api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
+[main]:                            api/clikt/com.github.ajalt.clikt.core/main.html
 [MissingArgument]:                 api/clikt/com.github.ajalt.clikt.core/-missing-argument/index.html
 [MissingOption]:                   api/clikt/com.github.ajalt.clikt.core/-missing-option/index.html
 [MultiUsageError]:                 api/clikt/com.github.ajalt.clikt.core/-multi-usage-error/index.html
 [MutuallyExclusiveGroupException]: api/clikt/com.github.ajalt.clikt.core/-mutually-exclusive-group-exception/index.html
 [NoSuchOption]:                    api/clikt/com.github.ajalt.clikt.core/-no-such-option/index.html
 [NoSuchSubcommand]:                api/clikt/com.github.ajalt.clikt.core/-no-such-subcommand/index.html
-[parse]:                           api/clikt/com.github.ajalt.clikt.core/-clikt-command/parse.html
+[parse]:                           api/clikt/com.github.ajalt.clikt.core/parse.html
 [PrintCompletionMessage]:          api/clikt/com.github.ajalt.clikt.core/-print-completion-message/index.html
 [PrintHelpMessage]:                api/clikt/com.github.ajalt.clikt.core/-print-help-message/index.html
 [PrintMessage]:                    api/clikt/com.github.ajalt.clikt.core/-print-message/index.html
diff --git a/docs/options.md b/docs/options.md
index 0507ea30..eb1eebe9 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -264,7 +264,8 @@ You can create options that take zero or one values with [`optionalValue`][optio
 ### Options With a Variable Number of Values
 
 If you want your option to take a variable number of values, but want to split the value on whitespace 
-[rather than a delimiter][#splitting-an-option-value-on-a-delimiter], you can use [`varargValues`][varargValues].
+[rather than a delimiter](#splitting-an-option-value-on-a-delimiter), you can use
+[`varargValues`][varargValues].
 
 === "Example"
 
@@ -674,7 +675,7 @@ options][choice-options].
         val password by option().prompt(hideInput = true)
     }
 
-    class Tool : CliktCommand(help = "An example of a custom help formatter that uses ansi colors") {
+    class Tool : CliktCommand() {
         val load by option().groupChoice(
                 "disk" to FromDisk(),
                 "network" to FromNetwork()
@@ -1227,8 +1228,8 @@ val opt: Pair<Int, Int> by option("-o", "--opt")
 [choice-options]:              #choice-options
 [choice]:                      api/clikt/com.github.ajalt.clikt.parameters.types/choice.html
 [CliktCommand.init]:           api/clikt/com.github.ajalt.clikt.core/-clikt-command/-clikt-command.html
-[CliktCommand.main]:           api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
-[CliktCommand.registerOption]: api/clikt/com.github.ajalt.clikt.core/-clikt-command/register-option.html
+[CliktCommand.main]:           api/clikt/com.github.ajalt.clikt.core/main.html
+[CliktCommand.registerOption]: api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/register-option.html
 [co-occurring-option-groups]:  #co-occurring-option-groups
 [Context.valueSource]:         api/clikt/com.github.ajalt.clikt.core/-context/-builder/value-source.html
 [Context.valueSources]:        api/clikt/com.github.ajalt.clikt.core/-context/-builder/value-sources.html
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 974f28de..b45bcb6e 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -48,6 +48,25 @@ also pass `err=true` to `echo` to print to stderr instead of stdout.
 Additionally, if you use Clikt's [testing utilities][test], output sent 
 to `echo` will be captured for testing, but output sent to `println` will not.
 
+## Coroutine commands with suspend functions
+
+If you want to use coroutines in your command, you can use a [SuspendingCliktCommand]:
+
+```kotlin
+class Hello : SuspendingCliktCommand() {
+    val count by option(help="Number of greetings").int().default(1)
+    val name by argument()
+
+    override suspend fun run() {
+        for (i in 1..count) {
+            echo("Hello $name!")
+            delay(1000)
+        }
+    }
+}
+
+suspend fun main(args: Array<String>) = Hello().main(args)
+```
 ## Nesting Commands
 
 Instances of any command can be attached to other commands, allowing
@@ -166,10 +185,11 @@ distribution scripts in your build folder, which you can then execute normally.
 [argument]:           api/clikt/com.github.ajalt.clikt.parameters.arguments/argument.html
 [clikt-samples]:      https://github.com/ajalt/clikt/tree/master/samples
 [CliktCommand]:       api/clikt/com.github.ajalt.clikt.core/-clikt-command/index.html
-[echo]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/echo.html
-[main]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
+[echo]:               api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/echo.html
+[main]:               api/clikt/com.github.ajalt.clikt.core/main.html
 [option]:             api/clikt/com.github.ajalt.clikt.parameters.options/option.html
 [println]:            https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.io/println.html
 [README]:             https://github.com/ajalt/clikt
 [runsample]:          https://github.com/ajalt/clikt/blob/master/runsample
+[SuspendingCliktCommand]: api/clikt/com.github.ajalt.clikt.command/-suspending-clikt-command/index.html
 [test]:               testing.md
diff --git a/docs/testing.md b/docs/testing.md
index f1f4e1ed..8e98bb4c 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -102,9 +102,9 @@ to return test values for them.
 
 To capture output, [override the command's console][replacing-stdin].
 
-[main]:                api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
+[main]:                api/clikt/com.github.ajalt.clikt.core/main.html
 [override-envvar]:     options.md#overriding-system-environment-variables
-[parse]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/parse.html
+[parse]:               api/clikt/com.github.ajalt.clikt.core/parse.html
 [prompt]:              options.md#prompting-for-input
 [replacing-stdin]:     advanced.md#replacing-stdin-and-stdout
 [test-result]:         api/clikt/com.github.ajalt.clikt.testing/-clikt-command-test-result/index.html
diff --git a/docs/utilities.md b/docs/utilities.md
index b4b98557..d22b829b 100644
--- a/docs/utilities.md
+++ b/docs/utilities.md
@@ -62,7 +62,6 @@ if (YesNoPrompt("Continue?", terminal).ask() == true) {
 [confirm]:             api/clikt/com.github.ajalt.clikt.core/-clikt-command/confirm.html
 [editFile]:            api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-file.html
 [editText]:            api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-text.html
-[prompt]:              api/clikt/com.github.ajalt.clikt.core/-clikt-command/prompt.html
 [prompting-for-input]: options.md#prompting-for-input
 [UsageError]:          api/clikt/com.github.ajalt.clikt.core/-usage-error/index.html
 [YesNoPrompt]:         https://ajalt.github.io/mordant/api/mordant/com.github.ajalt.mordant.terminal/-yes-no-prompt/index.html
diff --git a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
index 1b747707..da9cdeb5 100644
--- a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
+++ b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
@@ -55,7 +55,10 @@ class PanelHelpFormatter(context: Context) : MordantHelpFormatter(context) {
     }
 }
 
-class Echo(t: Terminal) : CliktCommand(help = "Echo the STRING(s) to standard output") {
+class Echo(t: Terminal) : CliktCommand() {
+    override fun help(context: Context): String {
+        return "Echo the STRING(s) to standard output"
+    }
     init {
         context {
             terminal = t

From c4ed82f00772f2e1ce26953253116dc0b8ee4d7f Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 11:12:56 -0700
Subject: [PATCH 36/43] Add .test() extenstion for new command types

---
 .../clikt/command/ChainedCliktCommand.kt      | 93 +++++++++++++++++++
 .../clikt/command/SuspendingCliktCommand.kt   | 87 +++++++++++++++++
 .../ajalt/clikt/core/BaseCliktCommand.kt      | 22 +++--
 .../ajalt/clikt/testing/CliktTesting.kt       | 47 ++++++++--
 .../clikt/command/ChainedCliktCommandTest.kt  | 32 +++++++
 .../command/SuspendingCliktCommandTest.kt     | 15 ++-
 6 files changed, 280 insertions(+), 16 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
index e230aa75..67902d94 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -2,6 +2,9 @@ package com.github.ajalt.clikt.command
 
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.CommandLineParser
+import com.github.ajalt.clikt.testing.CliktCommandTestResult
+import com.github.ajalt.clikt.testing.test
+import com.github.ajalt.mordant.rendering.AnsiLevel
 
 /**
  * A version of [CliktCommand] that returns a value from the [run] function, which is then passed to
@@ -83,3 +86,93 @@ fun <T> ChainedCliktCommand<T>.parse(argv: List<String>, initial: T): T {
     CommandLineParser.parseAndRun(this, argv) { value = it.run(value) }
     return value
 }
+
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed
+ * with [print] or [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+fun <T> ChainedCliktCommand<T>.test(
+    argv: String,
+    initial: T,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    val argvArray = CommandLineParser.tokenize(argv)
+    return test(argvArray, initial, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+}
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed
+ * with [print] or [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+fun <T> ChainedCliktCommand<T>.test(
+    argv: Array<String>,
+    initial: T,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    return test(
+        argv.asList(), initial, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height
+    )
+}
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed
+ * with [print] or [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+fun <T> ChainedCliktCommand<T>.test(
+    argv: List<String>,
+    initial: T,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    return test(argv, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height) {
+        parse(it, initial)
+    }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
index d2c31117..c43a6948 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -2,6 +2,9 @@ package com.github.ajalt.clikt.command
 
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parsers.CommandLineParser
+import com.github.ajalt.clikt.testing.CliktCommandTestResult
+import com.github.ajalt.clikt.testing.test
+import com.github.ajalt.mordant.rendering.AnsiLevel
 
 /**
  * A version of [CliktCommand] that supports a suspending [run] function.
@@ -67,3 +70,87 @@ suspend fun SuspendingCliktCommand.parse(argv: Array<String>) {
 suspend fun SuspendingCliktCommand.parse(argv: List<String>) {
     CommandLineParser.parseAndRun(this, argv) { it.run() }
 }
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed with [print] or
+ * [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+suspend fun SuspendingCliktCommand.test(
+    argv: String,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    val argvArray = CommandLineParser.tokenize(argv)
+    return test(argvArray, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+}
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed with [print] or
+ * [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+suspend fun SuspendingCliktCommand.test(
+    argv: Array<String>,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    return test(argv.asList(), stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+}
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed with [print] or
+ * [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ */
+suspend fun SuspendingCliktCommand.test(
+    argv: List<String>,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    return test(argv, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height) {
+        parse(it)
+    }
+}
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
index 54586110..b23ab071 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt
@@ -331,6 +331,21 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
         }
     }
 
+    /**
+     * Configure this command's [Context].
+     *
+     * Context property values are normally inherited from the parent context, but you can override any of them
+     * here.
+     */
+    fun configureContext(block: Context.Builder.() -> Unit) {
+        // save the old config to allow multiple context calls
+        val c = _contextConfig
+        _contextConfig = {
+            c()
+            block()
+        }
+    }
+
     override fun toString() = buildString {
         append("<${this@BaseCliktCommand.classSimpleName()} name=$commandName")
 
@@ -371,12 +386,7 @@ fun <T : BaseCliktCommand<T>, CommandT : T> CommandT.subcommands(
  * here.
  */
 fun <T : BaseCliktCommand<T>, U : T> U.context(block: Context.Builder.() -> Unit): U = apply {
-    // save the old config to allow multiple context calls
-    val c = _contextConfig
-    _contextConfig = {
-        c()
-        block()
-    }
+    configureContext(block)
 }
 
 private fun Any.classSimpleName(): String = this::class.simpleName.orEmpty().split("$").last()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
index a66cacc5..c1b807c6 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
@@ -1,12 +1,11 @@
 package com.github.ajalt.clikt.testing
 
+import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.CliktError
-import com.github.ajalt.clikt.core.context
 import com.github.ajalt.clikt.core.parse
 import com.github.ajalt.clikt.mpp.readEnvvar
 import com.github.ajalt.clikt.parsers.CommandLineParser
-import com.github.ajalt.clikt.parsers.shlex
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
 import com.github.ajalt.mordant.terminal.TerminalRecorder
@@ -99,7 +98,7 @@ fun CliktCommand.test(
  * @param height The height of the terminal
  */
 fun CliktCommand.test(
-    argv: List<String>,
+    argv: Array<String>,
     stdin: String = "",
     envvars: Map<String, String> = emptyMap(),
     includeSystemEnvvars: Boolean = false,
@@ -107,7 +106,7 @@ fun CliktCommand.test(
     width: Int = 79,
     height: Int = 24,
 ): CliktCommandTestResult {
-    return test(argv.toTypedArray(), stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
+    return test(argv.asList(), stdin, envvars, includeSystemEnvvars, ansiLevel, width, height)
 }
 
 /**
@@ -126,23 +125,53 @@ fun CliktCommand.test(
  * @param height The height of the terminal
  */
 fun CliktCommand.test(
-    // TODO make test() work with base command
-    argv: Array<String>,
+    argv: List<String>,
+    stdin: String = "",
+    envvars: Map<String, String> = emptyMap(),
+    includeSystemEnvvars: Boolean = false,
+    ansiLevel: AnsiLevel = AnsiLevel.NONE,
+    width: Int = 79,
+    height: Int = 24,
+): CliktCommandTestResult {
+    return test(argv, stdin, envvars, includeSystemEnvvars, ansiLevel, width, height) {
+        parse(it)
+    }
+}
+
+/**
+ * Test this command, returning a result that captures the output and result status code.
+ *
+ * Note that only output printed with [echo][CliktCommand.echo] will be captured. Anything printed with [print] or
+ * [println] is not.
+ *
+ * @param argv The command line to send to the command
+ * @param stdin Content of stdin that will be read by prompt options. Multiple inputs should be separated by `\n`.
+ * @param envvars A map of environment variable name to value for envvars that can be read by the command
+ * @param includeSystemEnvvars Set to true to include the environment variables from the system in addition to those
+ *   defined in [envvars]
+ * @param ansiLevel Defaults to no colored output; set to [AnsiLevel.TRUECOLOR] to include ANSI codes in the output.
+ * @param width The width of the terminal, used to wrap text
+ * @param height The height of the terminal
+ * @param parse The function to call to parse the command line and run the command
+ */
+inline fun <T : BaseCliktCommand<T>> BaseCliktCommand<T>.test(
+    argv: List<String>,
     stdin: String = "",
     envvars: Map<String, String> = emptyMap(),
     includeSystemEnvvars: Boolean = false,
     ansiLevel: AnsiLevel = AnsiLevel.NONE,
     width: Int = 79,
     height: Int = 24,
+    parse: (argv: List<String>) -> Unit,
 ): CliktCommandTestResult {
     var exitCode = 0
     val recorder = TerminalRecorder(ansiLevel, width, height)
     recorder.inputLines = stdin.split("\n").toMutableList()
-    context {
-        envvarReader = { envvars[it] ?: (if (includeSystemEnvvars) readEnvvar(it) else null) }
+    configureContext {
+        val originalReader = envvarReader
+        envvarReader = { envvars[it] ?: (if (includeSystemEnvvars) originalReader(it) else null) }
         terminal = Terminal(terminal.theme, terminal.tabWidth, recorder)
     }
-
     try {
         parse(argv)
     } catch (e: CliktError) {
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
index 1f997404..72baf9b9 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
@@ -1,5 +1,7 @@
 package com.github.ajalt.clikt.command
 
+import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.requireObject
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.types.int
@@ -32,4 +34,34 @@ class ChainedCliktCommandTest {
         val result = c.parse(listOf("sub", "2", "sub", "3"), emptyList())
         result shouldBe listOf(1, 2, 3)
     }
+
+
+    @Test
+    @JsName("chained_command_context")
+    fun `chained command context`() {
+        class C : ChainedCliktCommand<Int>() {
+            val arg by argument().int()
+            val ctx by requireObject<Int>()
+            override fun run(value: Int): Int {
+                return value + arg + ctx
+            }
+        }
+
+        C().context { obj = 10 }.parse(listOf("1"), 100) shouldBe 111
+    }
+
+
+    @Test
+    @JsName("chained_command_test")
+    fun `chained command test`()  {
+        class C : ChainedCliktCommand<Int>() {
+            val arg by argument().int()
+            override fun run(value: Int): Int {
+                echo(value + arg)
+                return 0
+            }
+        }
+
+        C().test("10", 1).output shouldBe "11\n"
+    }
 }
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt
index 1d6c0f96..f2401aeb 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommandTest.kt
@@ -20,7 +20,6 @@ class SuspendingCliktCommandTest {
 
             override suspend fun run() {
                 yield()
-                arg shouldBe "foo"
                 ran = true
             }
         }
@@ -36,7 +35,21 @@ class SuspendingCliktCommandTest {
         val sub = Sub()
         val c: C = C().subcommands(sub)
         c.parse(CommandLineParser.tokenize("foo sub"))
+        c.arg shouldBe "foo"
         c.ran shouldBe true
         sub.ran shouldBe true
     }
+
+    @Test
+    @JsName("suspending_command_test")
+    fun `suspending command test`() = runTest {
+        class C : SuspendingCliktCommand() {
+            val arg by argument()
+            override suspend fun run() {
+                echo(arg)
+            }
+        }
+
+        C().test("baz").output shouldBe "baz\n"
+    }
 }

From cf4edb8f7aec31273e730fbc3b42011ffd27fe80 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 12:41:57 -0700
Subject: [PATCH 37/43] Add docs for custom command types

---
 .../clikt/command/ChainedCliktCommand.kt      |   9 +-
 .../clikt/command/SuspendingCliktCommand.kt   |   2 +-
 .../github/ajalt/clikt/core/CliktCommand.kt   |   2 +-
 .../ajalt/clikt/parsers/CommandLineParser.kt  |  31 ++-
 .../github/ajalt/clikt/parsers/Invocation.kt  |  16 +-
 .../clikt/command/ChainedCliktCommandTest.kt  |   2 +-
 docs/advanced.md                              | 196 ++++++++++++++++--
 mkdocs.yml                                    |   4 +
 8 files changed, 216 insertions(+), 46 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
index 67902d94..816051a2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt
@@ -44,14 +44,7 @@ abstract class ChainedCliktCommand<T>(
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
 fun <T> ChainedCliktCommand<T>.main(argv: List<String>, initial: T): T {
-    try {
-        return parse(argv, initial)
-    } catch (e: CliktError) {
-        echoFormattedHelp(e)
-        CliktUtil.exitProcess(e.statusCode)
-        // Throw an exception if we can't exit, since we don't have a return value
-        throw ProgramResult(e.statusCode)
-    }
+    return CommandLineParser.mainReturningValue(this) { parse(argv, initial) }
 }
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
index c43a6948..8c5de46a 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt
@@ -39,7 +39,7 @@ abstract class SuspendingCliktCommand(
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
 suspend fun SuspendingCliktCommand.main(argv: List<String>) {
-    CommandLineParser.main(this, argv) { parse(argv) }
+    CommandLineParser.main(this) { parse(argv) }
 }
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
index 89a63ee9..8f15d996 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt
@@ -42,7 +42,7 @@ abstract class CliktCommand(
  * If you don't want Clikt to exit your process, call [parse] instead.
  */
 fun CliktCommand.main(argv: List<String>) {
-    CommandLineParser.main(this, argv) { parse(argv) }
+    CommandLineParser.main(this) { parse(argv) }
 }
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
index a4b9632f..524544ce 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/CommandLineParser.kt
@@ -31,19 +31,35 @@ object CommandLineParser {
     }
 
     /**
-     * Call [parseAndRun] with the given [command] and [argv]. If an error is thrown, exit the
+     * Call [parseAndRun] on the given [command]. If an error is thrown, exit the
      * process with the error's [status code][CliktError.statusCode].
      */
-    inline fun <T : BaseCliktCommand<T>> main(
-        command: T,
-        argv: List<String>,
-        parseAndRun: T.(argv: List<String>) -> Unit,
-    ) {
+    inline fun <T : BaseCliktCommand<T>> main(command: T, parseAndRun: T.() -> Unit) {
+        try {
+            command.parseAndRun()
+        } catch (e: CliktError) {
+            command.echoFormattedHelp(e)
+            CliktUtil.exitProcess(e.statusCode)
+        }
+    }
+
+    /**
+     * Call [parseAndRun] on the given [command]. If an error is thrown, exit the
+     * process with the error's [status code][CliktError.statusCode].
+     *
+     * @return The value returned by [parseAndRun]
+     * @throws ProgramResult If run on Kotlin/JS on browsers and an error occurs, since it's not
+     * possible to exit the process in that case.
+     */
+    inline fun <T : BaseCliktCommand<T>, R> mainReturningValue(
+        command: T, parseAndRun: T.() -> R,
+    ): R {
         try {
-            command.parseAndRun(argv)
+            return command.parseAndRun()
         } catch (e: CliktError) {
             command.echoFormattedHelp(e)
             CliktUtil.exitProcess(e.statusCode)
+            throw ProgramResult(e.statusCode)
         }
     }
 
@@ -74,7 +90,6 @@ object CommandLineParser {
         val invocations = rootInvocation.flatten()
         try {
             for (invocation in invocations) {
-                finalize(invocation)
                 runCommand(invocation.command)
             }
         } finally {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index ba286c31..e562aec2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -25,7 +25,7 @@ data class Invocation(
 /**
  * The output of parsing a single argument and its values.
  */
-data class ArgumentInvocation(
+class ArgumentInvocation(
     /**
      * The argument that was invoked.
      */
@@ -40,7 +40,7 @@ data class ArgumentInvocation(
 /**
  * The output of parsing a single command and its options and arguments.
  */
-data class CommandInvocation<T : BaseCliktCommand<T>>(
+class CommandInvocation<T : BaseCliktCommand<T>>(
     val command: T,
     val optionInvocations: Map<Option, List<Invocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
@@ -90,21 +90,23 @@ class CommandLineParseResult<T : BaseCliktCommand<T>>(
  * val invocations = rootInvocation.flatten()
  * try {
  *   for (inv in invocations) {
- *     finalize(inv)
  *     run(inv.command)
  *   }
  * } finally {
  *   invocations.close()
  * }
  * ```
+ *
+ * @param finalize If true (the default), finalize all commands as they are emitted in the sequence. If false, you
+ * must call [CommandLineParser.finalize] on each invocation yourself before running the command.
  */
-fun <T : BaseCliktCommand<T>> CommandInvocation<T>.flatten(): FlatInvocations<T> {
-    return FlatInvocations(this)
+fun <T : BaseCliktCommand<T>> CommandInvocation<T>.flatten(finalize: Boolean = true): FlatInvocations<T> {
+    return FlatInvocations(this, finalize)
 }
 
 // TODO: this should be an AutoClosable once that interface is stable
 class FlatInvocations<T : BaseCliktCommand<T>> internal constructor(
-    root: CommandInvocation<T>,
+    root: CommandInvocation<T>, private val finalize: Boolean,
 ) : Sequence<CommandInvocation<T>> {
     private val closables = mutableListOf<Context>()
     private val seq = sequence {
@@ -117,7 +119,7 @@ class FlatInvocations<T : BaseCliktCommand<T>> internal constructor(
             closables.removeLast().close()
         }
         yieldSubs(root)
-    }
+    }.onEach { if (finalize) CommandLineParser.finalize(it) }
 
     override fun iterator(): Iterator<CommandInvocation<T>> = seq.iterator()
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
index 72baf9b9..5eb1f674 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommandTest.kt
@@ -53,7 +53,7 @@ class ChainedCliktCommandTest {
 
     @Test
     @JsName("chained_command_test")
-    fun `chained command test`()  {
+    fun `chained command test`() {
         class C : ChainedCliktCommand<Int>() {
             val arg by argument().int()
             override fun run(value: Int): Int {
diff --git a/docs/advanced.md b/docs/advanced.md
index 78130f66..f918b7df 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -400,6 +400,154 @@ advantages:
 - `ProgramResult` is easier to test. Exiting the process makes unit tests difficult to run.
 - `ProgramResult` works on all platforms. `exitProcess` is only available on the JVM.
 
+## Custom run function signature
+
+Clikt provides a few command base classes that have different run function signatures.
+[CliktCommand] has `fun run()`, while [SuspendingCliktCommand] has `suspend fun run()`. If you want
+a run function with a different signature, you can define your own base class the inherits from
+[BaseCliktCommand] and use the [CommandLineParser] methods to parse and run the command.
+
+For example, if you want a command that uses a [Flow] to emit multiple value for each run, you could
+implement it like this:
+
+=== "Example"
+    ```kotlin
+    abstract class FlowCliktCommand : BaseCliktCommand<FlowCliktCommand>() {
+        abstract fun run(): Flow<String>
+    }
+
+    class MyFlowCommand : FlowCliktCommand() {
+        val opt by option().required()
+        val arg by argument().int()
+
+        override fun run(): Flow<String> = flow {
+            emit(opt)
+            emit(arg.toString())
+        }
+    }
+
+    class MyFlowSubcommand : FlowCliktCommand() {
+        val arg by argument().multiple()
+
+        override fun run(): Flow<String> = flow {
+            arg.forEach { emit(it) }
+        }
+    }
+
+    fun FlowCliktCommand.parse(argv: Array<String>): Flow<String> {
+        val flows = mutableListOf<Flow<String>>()
+        CommandLineParser.parseAndRun(this, argv.asList()) { flows += it.run() }
+        return flow { flows.forEach { emitAll(it) } }
+    }
+
+    fun FlowCliktCommand.main(argv: Array<String>): Flow<String> {
+        return CommandLineParser.mainReturningValue(this) { parse(argv) }
+    }
+
+    suspend fun main(args: Array<String>) {
+        val command = MyFlowCommand().subcommands(MyFlowSubcommand())
+        val resultFlow: Flow<String> = command.main(args)
+        resultFlow.collect {
+            command.echo(it)
+        }
+    }
+    ```
+
+=== "Usage"
+    ```text
+    $ ./command --opt=foo 11 my-flow-subcommand bar baz
+    foo
+    11
+    bar
+    baz
+    ```
+
+There are a number of steps here, so let's break it down:
+
+1. Define a base class `FlowCliktCommand` that inherits from [BaseCliktCommand] and has an abstract
+   `run` function that returns a `Flow`.
+2. Define your commands that inherit from `FlowCliktCommand` and implement your `run` function.
+3. Define an extension function `parse` that uses [CommandLineParser.parseAndRun] to parse the
+   command and run the `run` function.
+4. Define an extension function `main` that uses [CommandLineParser.main] to run the `parse`
+   function and handle any exceptions it might throw.
+5. In your `main` function, call `main` on your command, and collect the results of the `Flow`.
+
+If you want to customize the behavior even further, see the [next section](#custom-run-behavior).
+
+## Custom run behavior
+
+If you want to customize how or when subcommands are run, you can do so by defining a custom base
+class like in the [previous section](#custom-run-function-signature), but instead of using
+`CommandLineParser.parseAndRun`, you can call your command's `run` functions manually.
+
+For example, if you want commands to return status codes, and you want to stop running commands as
+soon as one of them returns a non-zero status code, you could implement it like this:
+
+=== "Example"
+    ```kotlin
+    abstract class StatusCliktCommand : BaseCliktCommand<StatusCliktCommand>() {
+        abstract fun run(): Int
+    }
+    
+    class ParentCommand : StatusCliktCommand() {
+        override val allowMultipleSubcommands: Boolean = true
+        override fun run(): Int {
+            echo("Parent")
+            return 0
+        }
+    }
+    
+    class SuccessCommand : StatusCliktCommand() {
+        override fun run(): Int {
+            echo("Success")
+            return 0
+        }
+    }
+    
+    class FailureCommand : StatusCliktCommand() {
+        override fun run(): Int {
+            echo("Failure")
+            return 1001
+        }
+    }
+    
+    fun StatusCliktCommand.parse(argv: Array<String>): Int {
+        val parseResult = CommandLineParser.parse(this, argv.asList())
+        for (invocation in parseResult.invocation.flatten()) {
+            val status = invocation.command.run()
+            if (status != 0) {
+                return status
+            }
+        }
+        return 0
+    }
+    
+    fun StatusCliktCommand.main(argv: Array<String>) {
+        val status = CommandLineParser.mainReturningValue(this) { parse(argv) }
+        CliktUtil.exitProcess(status)
+    }
+    
+    fun main(argv: Array<String>) {
+        ParentCommand().subcommands(SuccessCommand(), FailureCommand()).main(argv)
+    }
+    ```
+
+=== "Usage"
+    ```text
+    $ ./command success failure success
+    Parent
+    Success
+    Failure
+
+    $ echo $?
+    1001
+    ```
+
+The steps here are similar to the [previous section](#custom-run-function-signature), but instead of
+using [CommandLineParser.parseAndRun], we use [CommandLineParser.parse], then call `run` on each
+command invocation manually, and stop when one of them returns a non-zero status code.
+
 ## Multiplatform Support
 
 Clikt supports the following platforms in addition to JVM:
@@ -428,23 +576,31 @@ 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-
-[editFile]:            api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-file.html
-[editText]:            api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-text.html
-[expandArgumentFiles]: api/clikt/com.github.ajalt.clikt.core/-context/expand-argument-files.html
-[file]:                api/clikt/com.github.ajalt.clikt.parameters.types/file.html
-[grouping-options]:    documenting.md#grouping-options-in-help
-[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
-[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
-[tokenTransformer]:    api/clikt/com.github.ajalt.clikt.core/-context/token-transformer.html
+[BaseCliktCommand]:              api/clikt/com.github.ajalt.clikt.core/-base-clikt-command/index.html
+[CliktCommand]:                  api/clikt/com.github.ajalt.clikt.core/-clikt-command/index.html
+[CommandLineParser]:             api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/index.html
+[CommandLineParser.main]:        api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/main.html
+[CommandLineParser.parse]:       api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/parse.html
+[CommandLineParser.parseAndRun]: api/clikt/com.github.ajalt.clikt.parsers/-command-line-parser/parse-and-run.html
+[Flow]:                          https://kotlinlang.org/docs/flow.html
+[ProgramResult]:                 api/clikt/com.github.ajalt.clikt.core/-program-result/index.html
+[SuspendingCliktCommand]:        api/clikt/com.github.ajalt.clikt.command/-suspending-clikt-command/index.html
+[TermUI]:                        api/clikt/com.github.ajalt.clikt.output/-term-ui/index.html
+[aliases]:                       api/clikt/com.github.ajalt.clikt.core/-base-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-
+[editFile]:                      api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-file.html
+[editText]:                      api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-text.html
+[expandArgumentFiles]:           api/clikt/com.github.ajalt.clikt.core/-context/expand-argument-files.html
+[file]:                          api/clikt/com.github.ajalt.clikt.parameters.types/file.html
+[grouping-options]:              documenting.md#grouping-options-in-help
+[main]:                          api/clikt/com.github.ajalt.clikt.core/main.html
+[parse]:                         api/clikt/com.github.ajalt.clikt.core/parse.html
+[path]:                          api/clikt/com.github.ajalt.clikt.parameters.types/path.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
+[tokenTransformer]:              api/clikt/com.github.ajalt.clikt.core/-context/token-transformer.html
diff --git a/mkdocs.yml b/mkdocs.yml
index 26ad3854..118e7670 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -127,6 +127,10 @@ nav:
       - 'Token Normalization': advanced/#token-normalization
       - 'Replacing stdin and stdout': advanced/#replacing-stdin-and-stdout
       - 'Argument Files ("@-files")': advanced/#command-line-argument-files-files
+      - 'Managing Shared Resources': advanced/#managing-shared-resources
+      - 'Custom exit status codes': advanced/#custom-exit-status-codes
+      - 'Custom run function signature': advanced/#custom-run-function-signature
+      - 'Custom run behavior': advanced/#custom-run-behavior
       - 'Multiplatform Support': advanced/#multiplatform-support
   - 'Testing':
       - 'Testing Your Commands': testing/

From 1417057ad5de8fe43c112a8ba863e5ad4c0f2ca2 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:02:38 -0700
Subject: [PATCH 38/43] Add migration guide

---
 CHANGELOG.md      |  4 +--
 docs/migration.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c92a58f2..09f7d0dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,8 +21,8 @@
 
   | removed parameter           | replacement property            |
   |-----------------------------|---------------------------------|
-  | `help`                      | `fun commandHelp`               |
-  | `epilog`                    | `fun commandHelpEpilog`         |
+  | `help`                      | `fun help`                      |
+  | `epilog`                    | `fun helpEpilog`                |
   | `invokeWithoutSubcommand`   | `val invokeWithoutSubcommand`   |
   | `printHelpOnEmptyArgs`      | `val printHelpOnEmptyArgs`      |
   | `helpTags`                  | `val helpTags`                  |
diff --git a/docs/migration.md b/docs/migration.md
index f1c50cfd..585cc439 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -1,5 +1,67 @@
 # Upgrading to Newer Releases
 
+## Upgrading to 5.0
+
+## `main` is now an extension
+
+The `CliktCommand.main` and `CliktCommand.parse` methods are now a extension functions, so you'll
+need to import them.
+
+```diff
++ import com.github.ajalt.clikt.core.main
+fun main(args: Array<String>) = MyCommand().main(args)
+```
+
+## `CliktCommand` constructor no longer takes most parameters
+
+All parameters of the `CliktCommand` except for `name` have been moved to open properties.
+
+=== "In 5.0"
+    ```kotlin
+    class MyCommand : CliktCommand(name="mycommand") {
+        override fun help(context: Context) = "command help"
+        override fun helpEpilog(context: Context) = "command epilog"
+        override val invokeWithoutSubcommand = true
+        override val printHelpOnEmptyArgs = true
+        override val helpTags = mapOf("tag" to "value")
+        override val autoCompleteEnvvar = "MYCOMMAND_COMPLETE"
+        override val allowMultipleSubcommands = true
+        override val treatUnknownOptionsAsArgs = true
+        override val hiddenFromHelp = true
+    }
+    ```
+
+=== "In 4.0"
+    ```kotlin
+    class MyCommand : CliktCommand(
+        name = "mycommand",
+        help = "command help",
+        helpEpilog = "command epilog",
+        invokeWithoutSubcommand = true,
+        printHelpOnEmptyArgs = true,
+        helpTags = mapOf("tag" to "value"),
+        autoCompleteEnvvar = "MYCOMMAND_COMPLETE",
+        allowMultipleSubcommands = true,
+        treatUnknownOptionsAsArgs = true,
+        hiddenFromHelp = true,
+    ) {
+    }
+    ```
+
+The full list of moved parameters:
+
+| removed parameter           | new replacement property        |
+|-----------------------------|---------------------------------|
+| `help`                      | `fun help`                      |
+| `epilog`                    | `fun helpEpilog`                |
+| `invokeWithoutSubcommand`   | `val invokeWithoutSubcommand`   |
+| `printHelpOnEmptyArgs`      | `val printHelpOnEmptyArgs`      |
+| `helpTags`                  | `val helpTags`                  |
+| `autoCompleteEnvvar`        | `val autoCompleteEnvvar`        |
+| `allowMultipleSubcommands`  | `val allowMultipleSubcommands`  |
+| `treatUnknownOptionsAsArgs` | `val treatUnknownOptionsAsArgs` |
+| `hidden`                    | `val hiddenFromHelp`            |
+
 ## Upgrading to 4.0
 
 ### Help formatting

From e9d9cf143077b66701b9c8b3afba7a54f83a9867 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:02:45 -0700
Subject: [PATCH 39/43] Optimize imports

---
 .../com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt | 5 ++++-
 .../ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt | 1 -
 .../github/ajalt/clikt/parameters/groups/ParameterGroup.kt  | 5 ++++-
 .../github/ajalt/clikt/parameters/options/EagerOption.kt    | 5 ++++-
 .../kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt   | 1 -
 .../kotlin/com/github/ajalt/clikt/core/ContextTest.kt       | 3 ---
 .../com/github/ajalt/clikt/parameters/ArgumentTest.kt       | 1 -
 .../github/ajalt/clikt/parameters/MultiUsageErrorTest.kt    | 2 --
 .../ajalt/clikt/parameters/groups/OptionGroupsTest.kt       | 6 ++++--
 .../com/github/ajalt/clikt/samples/helpformat/main.kt       | 2 +-
 .../com/github/ajalt/clikt/samples/validation/main.kt       | 5 +++--
 11 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
index 83d83723..db9db784 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
@@ -1,6 +1,9 @@
 package com.github.ajalt.clikt.parameters.groups
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.BadParameterValue
+import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.core.MissingOption
 import com.github.ajalt.clikt.parameters.internal.NullableLateinit
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.OptionDelegate
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
index 379eb43f..c9eb5294 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
@@ -1,7 +1,6 @@
 package com.github.ajalt.clikt.parameters.groups
 
 import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.internal.NullableLateinit
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
index 31232e0a..465fd157 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
@@ -1,6 +1,9 @@
 package com.github.ajalt.clikt.parameters.groups
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.core.GroupableOption
+import com.github.ajalt.clikt.core.ParameterHolder
 import com.github.ajalt.clikt.internal.finalizeOptions
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.options.Option
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
index 51ad3f18..61521bb0 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/EagerOption.kt
@@ -1,6 +1,9 @@
 package com.github.ajalt.clikt.parameters.options
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.Abort
+import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.PrintMessage
+import com.github.ajalt.clikt.core.ProgramResult
 
 
 /**
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
index c1b807c6..a36078e2 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/testing/CliktTesting.kt
@@ -4,7 +4,6 @@ import com.github.ajalt.clikt.core.BaseCliktCommand
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.core.parse
-import com.github.ajalt.clikt.mpp.readEnvvar
 import com.github.ajalt.clikt.parsers.CommandLineParser
 import com.github.ajalt.mordant.rendering.AnsiLevel
 import com.github.ajalt.mordant.terminal.Terminal
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 65cf3589..69f71623 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
@@ -1,8 +1,5 @@
 package com.github.ajalt.clikt.core
 
-import com.github.ajalt.clikt.parameters.arguments.argument
-import com.github.ajalt.clikt.parameters.arguments.multiple
-import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.testing.TestCommand
 import com.github.ajalt.clikt.testing.parse
 import io.kotest.assertions.throwables.shouldThrow
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
index 506db9aa..aa7f8332 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/ArgumentTest.kt
@@ -15,7 +15,6 @@ import io.kotest.data.row
 import io.kotest.matchers.should
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.contain
-import io.kotest.matchers.types.shouldBeInstanceOf
 import kotlin.js.JsName
 import kotlin.test.Test
 
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
index aebe2692..6c6a3141 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/MultiUsageErrorTest.kt
@@ -2,8 +2,6 @@ package com.github.ajalt.clikt.parameters
 
 import com.github.ajalt.clikt.core.MultiUsageError
 import com.github.ajalt.clikt.core.UsageError
-import com.github.ajalt.clikt.output.ParameterFormatter
-import com.github.ajalt.clikt.output.defaultLocalization
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.check
 import com.github.ajalt.clikt.parameters.options.check
diff --git a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
index 93ebc810..276120b8 100644
--- a/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
+++ b/clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
@@ -2,13 +2,15 @@
 
 package com.github.ajalt.clikt.parameters.groups
 
-import com.github.ajalt.clikt.core.*
+import com.github.ajalt.clikt.core.BadParameterValue
+import com.github.ajalt.clikt.core.MissingOption
+import com.github.ajalt.clikt.core.MutuallyExclusiveGroupException
+import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.options.*
 import com.github.ajalt.clikt.parameters.types.int
 import com.github.ajalt.clikt.testing.TestCommand
 import com.github.ajalt.clikt.testing.formattedMessage
 import com.github.ajalt.clikt.testing.parse
-import com.github.ajalt.clikt.testing.test
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.data.blocking.forAll
 import io.kotest.data.row
diff --git a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
index da9cdeb5..4e3ec274 100644
--- a/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
+++ b/samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt
@@ -10,7 +10,6 @@ import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
-import com.github.ajalt.clikt.parameters.options.prompt
 import com.github.ajalt.mordant.rendering.TextAlign
 import com.github.ajalt.mordant.rendering.TextColors
 import com.github.ajalt.mordant.rendering.Theme
@@ -59,6 +58,7 @@ class Echo(t: Terminal) : CliktCommand() {
     override fun help(context: Context): String {
         return "Echo the STRING(s) to standard output"
     }
+
     init {
         context {
             terminal = t
diff --git a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
index b2b70b55..7d5a9c8c 100644
--- a/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
+++ b/samples/validation/src/main/kotlin/com/github/ajalt/clikt/samples/validation/main.kt
@@ -1,7 +1,8 @@
 package com.github.ajalt.clikt.samples.validation
 
-import com.github.ajalt.clikt.core.*
-import com.github.ajalt.clikt.output.Localization
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.convert
 import com.github.ajalt.clikt.parameters.options.*

From 0b0d7d9c9d6e23d4ea557689527b4c9d2f987fe4 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:06:22 -0700
Subject: [PATCH 40/43] Remove deprecated annotations

---
 CHANGELOG.md                                         |  5 ++++-
 .../ajalt/clikt/completion/CompletionCandidates.kt   |  6 ------
 .../kotlin/com/github/ajalt/clikt/core/Context.kt    | 12 +++++-------
 .../ajalt/clikt/parameters/options/FlagOption.kt     |  1 -
 .../clikt/sources/ExperimentalValueSourceApi.kt      |  7 -------
 5 files changed, 9 insertions(+), 22 deletions(-)
 delete mode 100644 clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ExperimentalValueSourceApi.kt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09f7d0dc..5807811d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@
 ### Changed
 - In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
 - Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.
-- **Breaking Change:** Removed the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
+- **Breaking Change:** Moved the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
 
   | removed parameter           | replacement property            |
   |-----------------------------|---------------------------------|
@@ -39,6 +39,9 @@
 ### Deprecated
 - Deprecated `Context.originalArgv`. It will now always return an empty list. If your commands need an argv, you can pass it to them before you run them.
 
+### Removed
+- Removed previously deprecated experimental annotations.
+
 ## 4.3.0
 ### 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))
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt
index b5271fa2..c1d7052e 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt
@@ -1,11 +1,5 @@
 package com.github.ajalt.clikt.completion
 
-@RequiresOptIn
-@Retention(AnnotationRetention.BINARY)
-@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
-@Deprecated(message = "This opt-in requirement is not used anymore. Remove its usages from your code.")
-annotation class ExperimentalCompletionCandidates
-
 /**
  * Configurations for generating shell autocomplete suggestions
  */
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 fc39c246..c87a7c81 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
@@ -207,13 +207,6 @@ class Context private constructor(
         if (err != null) throw err
     }
 
-    // TODO(5.0): these don't need to be member functions
-    @PublishedApi
-    internal fun ancestors() = generateSequence(parent) { it.parent }
-
-    @PublishedApi
-    internal fun selfAndAncestors() = generateSequence(this) { it.parent }
-
     /**
      * If true, arguments starting with `@` will be expanded as argument files. If false, they
      * will be treated as normal arguments.
@@ -448,7 +441,12 @@ inline fun <reified T : Any> BaseCliktCommand<*>.findOrSetObject(
 /** The current terminal's theme */
 val Context.theme: Theme get() = terminal.theme
 
+
 private val DEFAULT_CORRECTION_SUGGESTOR: TypoSuggestor = { enteredValue, possibleValues ->
     possibleValues.map { it to jaroWinklerSimilarity(enteredValue, it) }.filter { it.second > 0.8 }
         .sortedByDescending { it.second }.map { it.first }
 }
+
+@PublishedApi
+internal fun Context.selfAndAncestors() = generateSequence(this) { it.parent }
+internal fun Context.ancestors() = generateSequence(parent) { it.parent }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt
index e8c26620..b4d5f169 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt
@@ -84,7 +84,6 @@ inline fun <OutT> OptionWithValues<Boolean, Boolean, Boolean>.convert(
  * @param clamp If `true`, the counted value will be clamped to the [limit] if it is exceeded. If
  *   `false`, an error will be shown isntead of clamping.
  */
-@JvmOverloads // TODO(5.0): remove this annotation
 fun RawOption.counted(limit: Int = Int.MAX_VALUE, clamp: Boolean = true): OptionWithValues<Int, Int, Int> {
     return int().transformValues(0..0) { it.lastOrNull() ?: 1 }.transformAll {
         val s = it.sum()
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ExperimentalValueSourceApi.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ExperimentalValueSourceApi.kt
deleted file mode 100644
index 78581b89..00000000
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ExperimentalValueSourceApi.kt
+++ /dev/null
@@ -1,7 +0,0 @@
-package com.github.ajalt.clikt.sources
-
-@RequiresOptIn
-@Retention(AnnotationRetention.BINARY)
-@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
-@Deprecated(message = "This opt-in requirement is not used anymore. Remove its usages from your code.")
-annotation class ExperimentalValueSourceApi

From 057dcc01a636096efa1e8e30671a569da62d0615 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:09:28 -0700
Subject: [PATCH 41/43] Dump api

---
 clikt/api/clikt.api | 237 +++++++++++++++++++++++++++++++-------------
 1 file changed, 168 insertions(+), 69 deletions(-)

diff --git a/clikt/api/clikt.api b/clikt/api/clikt.api
index 1337c972..ed24bae0 100644
--- a/clikt/api/clikt.api
+++ b/clikt/api/clikt.api
@@ -1,6 +1,46 @@
+public abstract class com/github/ajalt/clikt/command/ChainedCliktCommand : com/github/ajalt/clikt/core/BaseCliktCommand {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public abstract fun run (Ljava/lang/Object;)Ljava/lang/Object;
+}
+
+public final class com/github/ajalt/clikt/command/ChainedCliktCommandKt {
+	public static final fun main (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/util/List;Ljava/lang/Object;)Ljava/lang/Object;
+	public static final fun main (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;[Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object;
+	public static final fun parse (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/util/List;Ljava/lang/Object;)Ljava/lang/Object;
+	public static final fun parse (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;[Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object;
+	public static final fun test (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static final fun test (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/util/List;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static final fun test (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;[Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;Ljava/util/List;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/ChainedCliktCommand;[Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+}
+
+public abstract class com/github/ajalt/clikt/command/SuspendingCliktCommand : com/github/ajalt/clikt/core/BaseCliktCommand {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public abstract fun run (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+}
+
+public final class com/github/ajalt/clikt/command/SuspendingCliktCommandKt {
+	public static final fun main (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun main (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;[Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun parse (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/util/List;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun parse (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;[Ljava/lang/String;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun test (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun test (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun test (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;[Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/command/SuspendingCliktCommand;[Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+}
+
 public final class com/github/ajalt/clikt/completion/CompletionBuiltinsKt {
-	public static final fun completionOption (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;Z)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static synthetic fun completionOption$default (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/core/CliktCommand;
+	public static final fun completionOption (Lcom/github/ajalt/clikt/core/BaseCliktCommand;[Ljava/lang/String;Ljava/lang/String;Z)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static synthetic fun completionOption$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;[Ljava/lang/String;Ljava/lang/String;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
 }
 
 public abstract class com/github/ajalt/clikt/completion/CompletionCandidates {
@@ -74,12 +114,11 @@ public final class com/github/ajalt/clikt/completion/CompletionCommand : com/git
 	public fun <init> ()V
 	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
 	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun help (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
+	public fun helpEpilog (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
 	public fun run ()V
 }
 
-public abstract interface annotation class com/github/ajalt/clikt/completion/ExperimentalCompletionCandidates : java/lang/annotation/Annotation {
-}
-
 public final class com/github/ajalt/clikt/core/Abort : com/github/ajalt/clikt/core/ProgramResult {
 	public fun <init> ()V
 }
@@ -92,42 +131,35 @@ public final class com/github/ajalt/clikt/core/BadParameterValue : com/github/aj
 	public fun formatMessage (Lcom/github/ajalt/clikt/output/Localization;Lcom/github/ajalt/clikt/output/ParameterFormatter;)Ljava/lang/String;
 }
 
-public abstract class com/github/ajalt/clikt/core/CliktCommand : com/github/ajalt/clikt/core/ParameterHolder {
+public abstract class com/github/ajalt/clikt/core/BaseCliktCommand : com/github/ajalt/clikt/core/ParameterHolder {
 	public fun <init> ()V
-	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Map;Ljava/lang/String;ZZZ)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Map;Ljava/lang/String;ZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun aliases ()Ljava/util/Map;
 	public fun allHelpParams ()Ljava/util/List;
 	public fun commandHelp (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
 	public fun commandHelpEpilog (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
-	public final fun confirm (Ljava/lang/String;Ljava/lang/Boolean;ZZLjava/util/List;Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Boolean;
-	public static synthetic fun confirm$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/Boolean;ZZLjava/util/List;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Ljava/lang/Boolean;
+	public final fun configureContext (Lkotlin/jvm/functions/Function1;)V
 	public final fun echo ()V
 	public final fun echo (Ljava/lang/Object;ZZ)V
-	public static synthetic fun echo$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/Object;ZZILjava/lang/Object;)V
+	public static synthetic fun echo$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/Object;ZZILjava/lang/Object;)V
 	public final fun echoFormattedHelp (Lcom/github/ajalt/clikt/core/CliktError;)V
-	public static synthetic fun echoFormattedHelp$default (Lcom/github/ajalt/clikt/core/CliktCommand;Lcom/github/ajalt/clikt/core/CliktError;ILjava/lang/Object;)V
-	public fun getCommandHelp ()Ljava/lang/String;
-	public fun getCommandHelpEpilog ()Ljava/lang/String;
+	public static synthetic fun echoFormattedHelp$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lcom/github/ajalt/clikt/core/CliktError;ILjava/lang/Object;)V
+	public fun getAllowMultipleSubcommands ()Z
+	public fun getAutoCompleteEnvvar ()Ljava/lang/String;
 	public final fun getCommandName ()Ljava/lang/String;
 	public final fun getCurrentContext ()Lcom/github/ajalt/clikt/core/Context;
 	public final fun getFormattedHelp (Lcom/github/ajalt/clikt/core/CliktError;)Ljava/lang/String;
-	public static synthetic fun getFormattedHelp$default (Lcom/github/ajalt/clikt/core/CliktCommand;Lcom/github/ajalt/clikt/core/CliktError;ILjava/lang/Object;)Ljava/lang/String;
-	public final fun getHelpTags ()Ljava/util/Map;
-	public final fun getInvokeWithoutSubcommand ()Z
+	public static synthetic fun getFormattedHelp$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lcom/github/ajalt/clikt/core/CliktError;ILjava/lang/Object;)Ljava/lang/String;
+	public fun getHelpTags ()Ljava/util/Map;
+	public fun getHiddenFromHelp ()Z
+	public fun getInvokeWithoutSubcommand ()Z
 	public final fun getMessages ()Ljava/util/List;
-	public final fun getPrintHelpOnEmptyArgs ()Z
+	public fun getPrintHelpOnEmptyArgs ()Z
+	public fun getTreatUnknownOptionsAsArgs ()Z
+	public fun help (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
+	public fun helpEpilog (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
 	public final fun issueMessage (Ljava/lang/String;)V
-	public final fun main (Ljava/util/List;)V
-	public final fun main ([Ljava/lang/String;)V
-	public final fun parse (Ljava/util/List;Lcom/github/ajalt/clikt/core/Context;)V
-	public final fun parse ([Ljava/lang/String;Lcom/github/ajalt/clikt/core/Context;)V
-	public static synthetic fun parse$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/List;Lcom/github/ajalt/clikt/core/Context;ILjava/lang/Object;)V
-	public static synthetic fun parse$default (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Lcom/github/ajalt/clikt/core/Context;ILjava/lang/Object;)V
-	public final fun prompt (Ljava/lang/String;Ljava/lang/Object;ZZZLjava/util/Collection;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
-	public final fun prompt (Ljava/lang/String;Ljava/lang/String;ZZZLjava/util/Collection;Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;
-	public static synthetic fun prompt$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/Object;ZZZLjava/util/Collection;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ljava/lang/Object;
-	public static synthetic fun prompt$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;ZZZLjava/util/Collection;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Ljava/lang/String;
 	public final fun registerArgument (Lcom/github/ajalt/clikt/parameters/arguments/Argument;)V
 	public fun registerOption (Lcom/github/ajalt/clikt/core/GroupableOption;)V
 	public final fun registerOption (Lcom/github/ajalt/clikt/parameters/options/Option;)V
@@ -137,16 +169,31 @@ public abstract class com/github/ajalt/clikt/core/CliktCommand : com/github/ajal
 	public final fun registeredParameterGroups ()Ljava/util/List;
 	public final fun registeredSubcommandNames ()Ljava/util/List;
 	public final fun registeredSubcommands ()Ljava/util/List;
-	public abstract fun run ()V
+	public final fun resetContext (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/clikt/core/Context;
+	public static synthetic fun resetContext$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lcom/github/ajalt/clikt/core/Context;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/Context;
 	protected final fun shortHelp (Lcom/github/ajalt/clikt/core/Context;)Ljava/lang/String;
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class com/github/ajalt/clikt/core/BaseCliktCommandKt {
+	public static final fun context (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static final fun getTerminal (Lcom/github/ajalt/clikt/core/BaseCliktCommand;)Lcom/github/ajalt/mordant/terminal/Terminal;
+	public static final fun subcommands (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/Iterable;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static final fun subcommands (Lcom/github/ajalt/clikt/core/BaseCliktCommand;[Lcom/github/ajalt/clikt/core/BaseCliktCommand;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+}
+
+public abstract class com/github/ajalt/clikt/core/CliktCommand : com/github/ajalt/clikt/core/BaseCliktCommand {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public abstract fun run ()V
+}
+
 public final class com/github/ajalt/clikt/core/CliktCommandKt {
-	public static final fun context (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static final fun getTerminal (Lcom/github/ajalt/clikt/core/CliktCommand;)Lcom/github/ajalt/mordant/terminal/Terminal;
-	public static final fun subcommands (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/Iterable;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static final fun subcommands (Lcom/github/ajalt/clikt/core/CliktCommand;[Lcom/github/ajalt/clikt/core/CliktCommand;)Lcom/github/ajalt/clikt/core/CliktCommand;
+	public static final fun main (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/List;)V
+	public static final fun main (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;)V
+	public static final fun parse (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/List;)V
+	public static final fun parse (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;)V
 }
 
 public class com/github/ajalt/clikt/core/CliktError : java/lang/RuntimeException {
@@ -157,10 +204,14 @@ public class com/github/ajalt/clikt/core/CliktError : java/lang/RuntimeException
 	public final fun getStatusCode ()I
 }
 
+public final class com/github/ajalt/clikt/core/CliktUtil {
+	public static final field INSTANCE Lcom/github/ajalt/clikt/core/CliktUtil;
+	public final fun exitProcess (I)V
+}
+
 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 synthetic fun <init> (Lcom/github/ajalt/clikt/core/Context;Lcom/github/ajalt/clikt/core/BaseCliktCommand;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;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun callOnClose (Lkotlin/jvm/functions/Function0;)V
 	public final fun close ()V
 	public final fun commandNameWithParents ()Ljava/util/List;
@@ -171,13 +222,14 @@ public final class com/github/ajalt/clikt/core/Context {
 	public final fun getAllowInterspersedArgs ()Z
 	public final fun getArgumentFileReader ()Lkotlin/jvm/functions/Function1;
 	public final fun getAutoEnvvarPrefix ()Ljava/lang/String;
-	public final fun getCommand ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public final fun getCommand ()Lcom/github/ajalt/clikt/core/BaseCliktCommand;
 	public final fun getCorrectionSuggestor ()Lkotlin/jvm/functions/Function2;
 	public final fun getErrorEncountered ()Z
 	public final fun getExpandArgumentFiles ()Z
 	public final fun getHelpFormatter ()Lkotlin/jvm/functions/Function1;
 	public final fun getHelpOptionNames ()Ljava/util/Set;
-	public final fun getInvokedSubcommand ()Lcom/github/ajalt/clikt/core/CliktCommand;
+	public final fun getInvokedSubcommand ()Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public final fun getInvokedSubcommands ()Ljava/util/List;
 	public final fun getLocalization ()Lcom/github/ajalt/clikt/output/Localization;
 	public final fun getObj ()Ljava/lang/Object;
 	public final fun getOriginalArgv ()Ljava/util/List;
@@ -189,14 +241,14 @@ public final class com/github/ajalt/clikt/core/Context {
 	public final fun getTokenTransformer ()Lkotlin/jvm/functions/Function2;
 	public final fun getValueSource ()Lcom/github/ajalt/clikt/sources/ValueSource;
 	public final fun parentNames ()Ljava/util/List;
-	public final fun selfAndAncestors ()Lkotlin/sequences/Sequence;
 	public final fun setArgumentFileReader (Lkotlin/jvm/functions/Function1;)V
 	public final fun setObj (Ljava/lang/Object;)V
+	public fun toString ()Ljava/lang/String;
 }
 
 public final class com/github/ajalt/clikt/core/Context$Builder {
-	public fun <init> (Lcom/github/ajalt/clikt/core/CliktCommand;Lcom/github/ajalt/clikt/core/Context;)V
-	public synthetic fun <init> (Lcom/github/ajalt/clikt/core/CliktCommand;Lcom/github/ajalt/clikt/core/Context;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lcom/github/ajalt/clikt/core/Context;)V
+	public synthetic fun <init> (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lcom/github/ajalt/clikt/core/Context;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getAllowGroupedShortOptions ()Z
 	public final fun getAllowInterspersedArgs ()Z
 	public final fun getArgumentFileReader ()Lkotlin/jvm/functions/Function1;
@@ -248,6 +300,7 @@ public final class com/github/ajalt/clikt/core/ContextJvmKt {
 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 static final fun selfAndAncestors (Lcom/github/ajalt/clikt/core/Context;)Lkotlin/sequences/Sequence;
 }
 
 public final class com/github/ajalt/clikt/core/FileNotFound : com/github/ajalt/clikt/core/UsageError {
@@ -319,9 +372,14 @@ public final class com/github/ajalt/clikt/core/MutuallyExclusiveGroupException :
 
 public class com/github/ajalt/clikt/core/NoOpCliktCommand : com/github/ajalt/clikt/core/CliktCommand {
 	public fun <init> ()V
-	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Map;Ljava/lang/String;ZZ)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Map;Ljava/lang/String;ZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public fun run ()V
+	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun run ()V
+}
+
+public final class com/github/ajalt/clikt/core/NoSuchArgument : com/github/ajalt/clikt/core/UsageError {
+	public fun <init> (Ljava/util/List;)V
+	public fun formatMessage (Lcom/github/ajalt/clikt/output/Localization;Lcom/github/ajalt/clikt/output/ParameterFormatter;)Ljava/lang/String;
 }
 
 public final class com/github/ajalt/clikt/core/NoSuchOption : com/github/ajalt/clikt/core/UsageError {
@@ -722,17 +780,17 @@ public final class com/github/ajalt/clikt/parameters/arguments/Argument$DefaultI
 
 public abstract interface class com/github/ajalt/clikt/parameters/arguments/ArgumentDelegate : com/github/ajalt/clikt/parameters/arguments/Argument, kotlin/properties/PropertyDelegateProvider, kotlin/properties/ReadOnlyProperty {
 	public abstract fun getValue ()Ljava/lang/Object;
-	public abstract fun getValue (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public abstract fun getValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
 public final class com/github/ajalt/clikt/parameters/arguments/ArgumentDelegate$DefaultImpls {
 	public static fun getCompletionCandidates (Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;)Lcom/github/ajalt/clikt/completion/CompletionCandidates;
-	public static fun getValue (Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public static fun getValue (Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
 public final class com/github/ajalt/clikt/parameters/arguments/ArgumentKt {
-	public static final fun argument (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
-	public static synthetic fun argument$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
+	public static final fun argument (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
+	public static synthetic fun argument$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
 	public static final fun check (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;
 	public static final fun check (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;
 	public static synthetic fun check$default (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/arguments/ArgumentDelegate;
@@ -790,7 +848,7 @@ public final class com/github/ajalt/clikt/parameters/arguments/ProcessedArgument
 	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lkotlin/jvm/functions/Function2;Ljava/lang/String;IZLkotlin/jvm/functions/Function1;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
 	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lkotlin/jvm/functions/Function2;Lkotlin/jvm/functions/Function2;Lkotlin/jvm/functions/Function2;Ljava/lang/String;IZLkotlin/jvm/functions/Function1;Ljava/util/Map;Lcom/github/ajalt/clikt/completion/CompletionCandidates;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;
 	public static fun getCompletionCandidates (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;)Lcom/github/ajalt/clikt/completion/CompletionCandidates;
-	public static fun getValue (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public static fun getValue (Lcom/github/ajalt/clikt/parameters/arguments/ProcessedArgument;Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
 public final class com/github/ajalt/clikt/parameters/arguments/ProcessedArgumentImpl : com/github/ajalt/clikt/parameters/arguments/ProcessedArgument {
@@ -809,11 +867,11 @@ public final class com/github/ajalt/clikt/parameters/arguments/ProcessedArgument
 	public fun getTransformValidator ()Lkotlin/jvm/functions/Function2;
 	public fun getTransformValue ()Lkotlin/jvm/functions/Function2;
 	public fun getValue ()Ljava/lang/Object;
-	public fun getValue (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public fun getValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public synthetic fun getValue (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public fun parameterHelp (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/clikt/output/HelpFormatter$ParameterHelp$Argument;
 	public fun postValidate (Lcom/github/ajalt/clikt/core/Context;)V
-	public fun provideDelegate (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public fun provideDelegate (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 	public synthetic fun provideDelegate (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public fun setName (Ljava/lang/String;)V
 	public fun setValue (Ljava/lang/Object;)V
@@ -824,11 +882,11 @@ public final class com/github/ajalt/clikt/parameters/groups/ChoiceGroup : com/gi
 	public fun finalize (Lcom/github/ajalt/clikt/core/Context;Ljava/util/Map;)V
 	public fun getGroupHelp ()Ljava/lang/String;
 	public fun getGroupName ()Ljava/lang/String;
-	public fun getValue (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public fun getValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public synthetic fun getValue (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public fun parameterHelp (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/clikt/output/HelpFormatter$ParameterHelp$Group;
 	public fun postValidate (Lcom/github/ajalt/clikt/core/Context;)V
-	public fun provideDelegate (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public fun provideDelegate (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 	public synthetic fun provideDelegate (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
@@ -846,11 +904,11 @@ public final class com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGro
 	public fun finalize (Lcom/github/ajalt/clikt/core/Context;Ljava/util/Map;)V
 	public fun getGroupHelp ()Ljava/lang/String;
 	public fun getGroupName ()Ljava/lang/String;
-	public fun getValue (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public fun getValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public synthetic fun getValue (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public fun parameterHelp (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/clikt/output/HelpFormatter$ParameterHelp$Group;
 	public fun postValidate (Lcom/github/ajalt/clikt/core/Context;)V
-	public fun provideDelegate (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public fun provideDelegate (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 	public synthetic fun provideDelegate (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
@@ -877,11 +935,11 @@ public final class com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOpt
 	public fun finalize (Lcom/github/ajalt/clikt/core/Context;Ljava/util/Map;)V
 	public fun getGroupHelp ()Ljava/lang/String;
 	public fun getGroupName ()Ljava/lang/String;
-	public fun getValue (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
+	public fun getValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public synthetic fun getValue (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 	public fun parameterHelp (Lcom/github/ajalt/clikt/core/Context;)Lcom/github/ajalt/clikt/output/HelpFormatter$ParameterHelp$Group;
 	public fun postValidate (Lcom/github/ajalt/clikt/core/Context;)V
-	public fun provideDelegate (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public fun provideDelegate (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 	public synthetic fun provideDelegate (Ljava/lang/Object;Lkotlin/reflect/KProperty;)Ljava/lang/Object;
 }
 
@@ -910,7 +968,7 @@ public final class com/github/ajalt/clikt/parameters/groups/ParameterGroup$Defau
 }
 
 public abstract interface class com/github/ajalt/clikt/parameters/groups/ParameterGroupDelegate : com/github/ajalt/clikt/parameters/groups/ParameterGroup, kotlin/properties/PropertyDelegateProvider, kotlin/properties/ReadOnlyProperty {
-	public abstract fun provideDelegate (Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public abstract fun provideDelegate (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 }
 
 public final class com/github/ajalt/clikt/parameters/groups/ParameterGroupDelegate$DefaultImpls {
@@ -918,22 +976,20 @@ public final class com/github/ajalt/clikt/parameters/groups/ParameterGroupDelega
 }
 
 public final class com/github/ajalt/clikt/parameters/groups/ParameterGroupKt {
-	public static final fun provideDelegate (Lcom/github/ajalt/clikt/parameters/groups/OptionGroup;Lcom/github/ajalt/clikt/core/CliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
+	public static final fun provideDelegate (Lcom/github/ajalt/clikt/parameters/groups/OptionGroup;Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/reflect/KProperty;)Lkotlin/properties/ReadOnlyProperty;
 }
 
 public final class com/github/ajalt/clikt/parameters/options/EagerOptionKt {
-	public static final fun eagerOption (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/Collection;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static final fun eagerOption (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static synthetic fun eagerOption$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/Collection;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static synthetic fun eagerOption$default (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static final fun versionOption (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Set;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/CliktCommand;
-	public static synthetic fun versionOption$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Set;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/CliktCommand;
+	public static final fun eagerOption (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/Collection;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static final fun eagerOption (Lcom/github/ajalt/clikt/core/BaseCliktCommand;[Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static synthetic fun eagerOption$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/Collection;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static synthetic fun eagerOption$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;[Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static final fun versionOption (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Set;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public static synthetic fun versionOption$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Set;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/core/BaseCliktCommand;
 }
 
 public final class com/github/ajalt/clikt/parameters/options/FlagOptionKt {
 	public static final fun convert (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;Lkotlin/jvm/functions/Function2;)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
-	public static final fun counted (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
-	public static final fun counted (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;I)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
 	public static final fun counted (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;IZ)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
 	public static synthetic fun counted$default (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;IZILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
 	public static final fun flag (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;[Ljava/lang/String;ZLjava/lang/String;)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
@@ -1258,6 +1314,45 @@ public final class com/github/ajalt/clikt/parameters/types/UlongKt {
 	public static synthetic fun ulong$default (Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/parameters/options/OptionWithValues;
 }
 
+public final class com/github/ajalt/clikt/parsers/ArgumentInvocation {
+	public fun <init> (Lcom/github/ajalt/clikt/parameters/arguments/Argument;Ljava/util/List;)V
+	public final fun getArgument ()Lcom/github/ajalt/clikt/parameters/arguments/Argument;
+	public final fun getValues ()Ljava/util/List;
+}
+
+public final class com/github/ajalt/clikt/parsers/CommandInvocation {
+	public fun <init> (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/Map;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V
+	public final fun getArgumentInvocations ()Ljava/util/List;
+	public final fun getCommand ()Lcom/github/ajalt/clikt/core/BaseCliktCommand;
+	public final fun getErrors ()Ljava/util/List;
+	public final fun getOptionInvocations ()Ljava/util/Map;
+	public final fun getSubcommandInvocations ()Ljava/util/List;
+}
+
+public final class com/github/ajalt/clikt/parsers/CommandLineParseResult {
+	public fun <init> (Lcom/github/ajalt/clikt/parsers/CommandInvocation;Ljava/util/List;Ljava/util/List;)V
+	public final fun getExpandedArgv ()Ljava/util/List;
+	public final fun getInvocation ()Lcom/github/ajalt/clikt/parsers/CommandInvocation;
+	public final fun getOriginalArgv ()Ljava/util/List;
+}
+
+public final class com/github/ajalt/clikt/parsers/CommandLineParser {
+	public static final field INSTANCE Lcom/github/ajalt/clikt/parsers/CommandLineParser;
+	public final fun finalize (Lcom/github/ajalt/clikt/parsers/CommandInvocation;)V
+	public final fun main (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/jvm/functions/Function1;)V
+	public final fun mainReturningValue (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
+	public final fun parse (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/List;)Lcom/github/ajalt/clikt/parsers/CommandLineParseResult;
+	public final fun parseAndRun (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/List;Lkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/parsers/CommandLineParseResult;
+	public final fun run (Lcom/github/ajalt/clikt/parsers/CommandInvocation;Lkotlin/jvm/functions/Function1;)V
+	public final fun tokenize (Ljava/lang/String;Ljava/lang/String;Lcom/github/ajalt/clikt/output/Localization;)Ljava/util/List;
+	public static synthetic fun tokenize$default (Lcom/github/ajalt/clikt/parsers/CommandLineParser;Ljava/lang/String;Ljava/lang/String;Lcom/github/ajalt/clikt/output/Localization;ILjava/lang/Object;)Ljava/util/List;
+}
+
+public final class com/github/ajalt/clikt/parsers/FlatInvocations : kotlin/sequences/Sequence {
+	public final fun close ()V
+	public fun iterator ()Ljava/util/Iterator;
+}
+
 public final class com/github/ajalt/clikt/parsers/Invocation {
 	public fun <init> (Ljava/lang/String;Ljava/util/List;)V
 	public final fun component1 ()Ljava/lang/String;
@@ -1271,15 +1366,17 @@ public final class com/github/ajalt/clikt/parsers/Invocation {
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class com/github/ajalt/clikt/parsers/InvocationKt {
+	public static final fun flatten (Lcom/github/ajalt/clikt/parsers/CommandInvocation;Z)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
+	public static synthetic fun flatten$default (Lcom/github/ajalt/clikt/parsers/CommandInvocation;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
+}
+
 public final class com/github/ajalt/clikt/sources/ChainedValueSource : com/github/ajalt/clikt/sources/ValueSource {
 	public fun <init> (Ljava/util/List;)V
 	public final fun getSources ()Ljava/util/List;
 	public fun getValues (Lcom/github/ajalt/clikt/core/Context;Lcom/github/ajalt/clikt/parameters/options/Option;)Ljava/util/List;
 }
 
-public abstract interface annotation class com/github/ajalt/clikt/sources/ExperimentalValueSourceApi : java/lang/annotation/Annotation {
-}
-
 public final class com/github/ajalt/clikt/sources/MapValueSource : com/github/ajalt/clikt/sources/ValueSource {
 	public fun <init> (Ljava/util/Map;Lkotlin/jvm/functions/Function2;)V
 	public synthetic fun <init> (Ljava/util/Map;Lkotlin/jvm/functions/Function2;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
@@ -1345,9 +1442,11 @@ public final class com/github/ajalt/clikt/testing/CliktCommandTestResult {
 }
 
 public final class com/github/ajalt/clikt/testing/CliktTestingKt {
+	public static final fun test (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/jvm/functions/Function1;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static final fun test (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static final fun test (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static final fun test (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;II)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
+	public static synthetic fun test$default (Lcom/github/ajalt/clikt/core/BaseCliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static synthetic fun test$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static synthetic fun test$default (Lcom/github/ajalt/clikt/core/CliktCommand;Ljava/util/List;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;
 	public static synthetic fun test$default (Lcom/github/ajalt/clikt/core/CliktCommand;[Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ZLcom/github/ajalt/mordant/rendering/AnsiLevel;IIILjava/lang/Object;)Lcom/github/ajalt/clikt/testing/CliktCommandTestResult;

From f2c5de456bb2e254b81840ad85980076d5812e3d Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:43:17 -0700
Subject: [PATCH 42/43] Update plugins sample

---
 .../github/ajalt/clikt/samples/plugins/clone.kt  | 16 +++++++++-------
 .../github/ajalt/clikt/samples/plugins/main.kt   | 16 +++++++++-------
 .../ajalt/clikt/samples/plugins/setuser.kt       | 13 +++++++------
 3 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/clone.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/clone.kt
index df6ad175..490ba5a3 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/clone.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/clone.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.requireObject
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.optional
@@ -13,14 +14,15 @@ import org.kodein.di.generic.inSet
 import org.kodein.di.generic.provider
 import java.io.File
 
-class Clone : CliktCommand(
-    help = """
-        Clones a repository.
+class Clone : CliktCommand() {
+    override fun help(context: Context) = """
+    Clones a repository.
+
+    This will clone the repository at SRC into the folder DEST. If DEST
+    is not provided this will automatically use the last path component
+    of SRC and create that folder.
+    """.trimIndent()
 
-        This will clone the repository at SRC into the folder DEST. If DEST
-        is not provided this will automatically use the last path component
-        of SRC and create that folder.
-        """.trimIndent()) {
     val repo: Repo by requireObject()
     val src: String by argument()
     val dest: String? by argument().optional()
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
index 007432e3..b1cd22bf 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/main.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.main
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.options.*
@@ -11,14 +12,15 @@ import org.kodein.di.generic.setBinding
 
 data class Repo(var home: String, val config: MutableMap<String, String>, var verbose: Boolean)
 
-class Cli : CliktCommand(
-    help = """
-        Repo is a command line tool that showcases how to build complex
-        command line interfaces with Clikt.
+class Cli : CliktCommand() {
+    override fun help(context: Context) = """
+    Repo is a command line tool that showcases how to build complex
+    command line interfaces with Clikt.
+
+    This tool is supposed to look like a distributed version control
+    system to show how something like this can be structured.
+    """.trimIndent()
 
-        This tool is supposed to look like a distributed version control
-        system to show how something like this can be structured.
-        """.trimIndent()) {
     init {
         versionOption("1.0")
     }
diff --git a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/setuser.kt b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/setuser.kt
index 1588b0f0..cd5223b6 100644
--- a/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/setuser.kt
+++ b/samples/plugins/src/main/kotlin/com/github/ajalt/clikt/samples/plugins/setuser.kt
@@ -1,6 +1,7 @@
 package com.github.ajalt.clikt.samples.plugins
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.core.requireObject
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.prompt
@@ -9,13 +10,13 @@ import org.kodein.di.generic.bind
 import org.kodein.di.generic.inSet
 import org.kodein.di.generic.provider
 
-class SetUser : CliktCommand(
-    name = "setuser",
-    help = """
-        Sets the user credentials.
+class SetUser : CliktCommand(name = "setuser") {
+    override fun help(context: Context) = """
+    Sets the user credentials.
+
+    This will override the current user config.
+    """.trimIndent()
 
-        This will override the current user config.
-        """.trimIndent()) {
     val repo: Repo by requireObject()
     val username: String by option(help = "The developer's shown username.")
         .prompt()

From 8a86b0da48d5455faae27b6566de99b2bd18fc08 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Sun, 14 Apr 2024 15:47:05 -0700
Subject: [PATCH 43/43] Remove Invocation -> OptionInvocation

---
 clikt/api/clikt.api                              | 16 ++++++++--------
 .../github/ajalt/clikt/internal/Finalization.kt  | 16 ++++++++--------
 .../ajalt/clikt/parameters/groups/ChoiceGroup.kt |  4 ++--
 .../parameters/groups/CoOccurringOptionGroup.kt  |  4 ++--
 .../parameters/groups/MutuallyExclusiveOption.kt |  4 ++--
 .../clikt/parameters/groups/ParameterGroup.kt    |  6 +++---
 .../ajalt/clikt/parameters/options/Option.kt     | 10 +++++-----
 .../clikt/parameters/options/OptionWithValues.kt | 10 +++++-----
 .../com/github/ajalt/clikt/parsers/Invocation.kt |  4 ++--
 .../ajalt/clikt/parsers/ParserInternals.kt       |  4 ++--
 10 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/clikt/api/clikt.api b/clikt/api/clikt.api
index ed24bae0..8b51218c 100644
--- a/clikt/api/clikt.api
+++ b/clikt/api/clikt.api
@@ -1353,12 +1353,17 @@ public final class com/github/ajalt/clikt/parsers/FlatInvocations : kotlin/seque
 	public fun iterator ()Ljava/util/Iterator;
 }
 
-public final class com/github/ajalt/clikt/parsers/Invocation {
+public final class com/github/ajalt/clikt/parsers/InvocationKt {
+	public static final fun flatten (Lcom/github/ajalt/clikt/parsers/CommandInvocation;Z)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
+	public static synthetic fun flatten$default (Lcom/github/ajalt/clikt/parsers/CommandInvocation;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
+}
+
+public final class com/github/ajalt/clikt/parsers/OptionInvocation {
 	public fun <init> (Ljava/lang/String;Ljava/util/List;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Ljava/util/List;
-	public final fun copy (Ljava/lang/String;Ljava/util/List;)Lcom/github/ajalt/clikt/parsers/Invocation;
-	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/parsers/Invocation;Ljava/lang/String;Ljava/util/List;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parsers/Invocation;
+	public final fun copy (Ljava/lang/String;Ljava/util/List;)Lcom/github/ajalt/clikt/parsers/OptionInvocation;
+	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/parsers/OptionInvocation;Ljava/lang/String;Ljava/util/List;ILjava/lang/Object;)Lcom/github/ajalt/clikt/parsers/OptionInvocation;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getName ()Ljava/lang/String;
 	public final fun getValues ()Ljava/util/List;
@@ -1366,11 +1371,6 @@ public final class com/github/ajalt/clikt/parsers/Invocation {
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class com/github/ajalt/clikt/parsers/InvocationKt {
-	public static final fun flatten (Lcom/github/ajalt/clikt/parsers/CommandInvocation;Z)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
-	public static synthetic fun flatten$default (Lcom/github/ajalt/clikt/parsers/CommandInvocation;ZILjava/lang/Object;)Lcom/github/ajalt/clikt/parsers/FlatInvocations;
-}
-
 public final class com/github/ajalt/clikt/sources/ChainedValueSource : com/github/ajalt/clikt/sources/ValueSource {
 	public fun <init> (Ljava/util/List;)V
 	public final fun getSources ()Ljava/util/List;
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
index 53f50da4..490f6d3c 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/internal/Finalization.kt
@@ -8,12 +8,12 @@ import com.github.ajalt.clikt.parameters.groups.ParameterGroup
 import com.github.ajalt.clikt.parameters.internal.LateinitException
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parsers.ArgumentInvocation
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 
 internal fun finalizeOptions(
     context: Context,
     options: List<Option>,
-    invocationsByOption: Map<Option, List<Invocation>>,
+    invocationsByOption: Map<Option, List<OptionInvocation>>,
 ) {
     iterateFinalization(
         context, getAllOptions(invocationsByOption, options).map { Opt(it.key, it.value) }
@@ -21,9 +21,9 @@ internal fun finalizeOptions(
 }
 
 private sealed class Param
-private data class Opt(val option: Option, val invs: List<Invocation>) : Param()
+private data class Opt(val option: Option, val invs: List<OptionInvocation>) : Param()
 private data class Arg(val argument: Argument, val invs: List<String>) : Param()
-private data class Group(val group: ParameterGroup, val invs: Map<Option, List<Invocation>>) :
+private data class Group(val group: ParameterGroup, val invs: Map<Option, List<OptionInvocation>>) :
     Param()
 
 internal fun finalizeParameters(
@@ -31,13 +31,13 @@ internal fun finalizeParameters(
     options: List<Option>,
     groups: List<ParameterGroup>,
     arguments: List<Argument>,
-    optionInvocations: Map<Option, List<Invocation>>,
+    optionInvocations: Map<Option, List<OptionInvocation>>,
     argumentInvocations: List<ArgumentInvocation>,
 ): List<UsageError> {
     // Add uninvoked params last so that e.g. we can skip prompting if there's an error in an
     // invoked option
 
-    val allGroups = buildMap<ParameterGroup?, Map<Option, List<Invocation>>> {
+    val allGroups = buildMap<ParameterGroup?, Map<Option, List<OptionInvocation>>> {
         optionInvocations.entries
             .groupBy({ it.key.group }, { it.key to it.value })
             .mapValuesTo(this) { it.value.toMap() }
@@ -65,9 +65,9 @@ internal fun finalizeParameters(
 }
 
 private fun getAllOptions(
-    invocations: Map<Option, List<Invocation>>,
+    invocations: Map<Option, List<OptionInvocation>>,
     options: List<Option>,
-): Map<Option, List<Invocation>> {
+): Map<Option, List<OptionInvocation>> {
     return buildMap {
         putAll(invocations)
         for (opt in options) {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
index db9db784..41ef5eb6 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
@@ -10,7 +10,7 @@ import com.github.ajalt.clikt.parameters.options.OptionDelegate
 import com.github.ajalt.clikt.parameters.options.RawOption
 import com.github.ajalt.clikt.parameters.options.switch
 import com.github.ajalt.clikt.parameters.types.choice
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import kotlin.properties.ReadOnlyProperty
 import kotlin.reflect.KProperty
 
@@ -50,7 +50,7 @@ class ChoiceGroup<GroupT : OptionGroup, OutT> internal constructor(
 
     override fun finalize(
         context: Context,
-        invocationsByOption: Map<Option, List<Invocation>>,
+        invocationsByOption: Map<Option, List<OptionInvocation>>,
     ) {
         val key = option.value
         if (key == null) {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
index c9eb5294..de22b6a0 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
@@ -7,7 +7,7 @@ import com.github.ajalt.clikt.parameters.internal.NullableLateinit
 import com.github.ajalt.clikt.parameters.options.Option
 import com.github.ajalt.clikt.parameters.options.hasEnvvarOrSourcedValue
 import com.github.ajalt.clikt.parameters.options.required
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import kotlin.properties.ReadOnlyProperty
 import kotlin.reflect.KProperty
 
@@ -47,7 +47,7 @@ class CoOccurringOptionGroup<GroupT : OptionGroup, OutT> internal constructor(
 
     override fun getValue(thisRef: BaseCliktCommand<*>, property: KProperty<*>): OutT = value
 
-    override fun finalize(context: Context, invocationsByOption: Map<Option, List<Invocation>>) {
+    override fun finalize(context: Context, invocationsByOption: Map<Option, List<OptionInvocation>>) {
         occurred = invocationsByOption.isNotEmpty() || group.options.any {
             it.hasEnvvarOrSourcedValue(context, invocationsByOption[it] ?: emptyList())
         }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
index e2f400b7..205e2378 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
@@ -4,7 +4,7 @@ import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.internal.finalizeOptions
 import com.github.ajalt.clikt.parameters.internal.NullableLateinit
 import com.github.ajalt.clikt.parameters.options.*
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import kotlin.properties.ReadOnlyProperty
 import kotlin.reflect.KProperty
 
@@ -44,7 +44,7 @@ class MutuallyExclusiveOptions<OptT : Any, OutT> internal constructor(
 
     override fun finalize(
         context: Context,
-        invocationsByOption: Map<Option, List<Invocation>>,
+        invocationsByOption: Map<Option, List<OptionInvocation>>,
     ) {
         finalizeOptions(context, options, invocationsByOption)
         val values = options.filter {
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
index 465fd157..b2f931a5 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/groups/ParameterGroup.kt
@@ -7,7 +7,7 @@ import com.github.ajalt.clikt.core.ParameterHolder
 import com.github.ajalt.clikt.internal.finalizeOptions
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.options.Option
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import kotlin.properties.PropertyDelegateProvider
 import kotlin.properties.ReadOnlyProperty
 import kotlin.reflect.KProperty
@@ -38,7 +38,7 @@ interface ParameterGroup {
      * @param context The context for this parse
      * @param invocationsByOption The invocations of options in this group.
      */
-    fun finalize(context: Context, invocationsByOption: Map<Option, List<Invocation>>)
+    fun finalize(context: Context, invocationsByOption: Map<Option, List<OptionInvocation>>)
 
     /**
      * Called after all of a command's parameters have been [finalize]d to perform validation of the final values.
@@ -90,7 +90,7 @@ open class OptionGroup(
         options += option
     }
 
-    override fun finalize(context: Context, invocationsByOption: Map<Option, List<Invocation>>) {
+    override fun finalize(context: Context, invocationsByOption: Map<Option, List<OptionInvocation>>) {
         finalizeOptions(context, options, invocationsByOption)
     }
 
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
index ed95529b..82061702 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt
@@ -6,7 +6,7 @@ import com.github.ajalt.clikt.core.GroupableOption
 import com.github.ajalt.clikt.core.ParameterHolder
 import com.github.ajalt.clikt.core.StaticallyGroupedOption
 import com.github.ajalt.clikt.output.HelpFormatter
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import com.github.ajalt.clikt.sources.ValueSource
 import kotlin.properties.PropertyDelegateProvider
 import kotlin.properties.ReadOnlyProperty
@@ -80,7 +80,7 @@ interface Option {
      * @param context The context for this parse
      * @param invocations A possibly empty list of invocations of this option.
      */
-    fun finalize(context: Context, invocations: List<Invocation>)
+    fun finalize(context: Context, invocations: List<OptionInvocation>)
 
     /**
      * Called after all of a command's parameters have been [finalize]d to perform validation of the final value.
@@ -141,14 +141,14 @@ internal fun splitOptionPrefix(name: String): Pair<String, String> =
 internal fun Option.longestName(): String? = names.maxByOrNull { it.length }
 
 internal sealed class FinalValue {
-    data class Parsed(val values: List<Invocation>) : FinalValue()
+    data class Parsed(val values: List<OptionInvocation>) : FinalValue()
     data class Sourced(val values: List<ValueSource.Invocation>) : FinalValue()
     data class Envvar(val key: String, val value: String) : FinalValue()
 }
 
 internal fun Option.getFinalValue(
     context: Context,
-    invocations: List<Invocation>,
+    invocations: List<OptionInvocation>,
     envvar: String?,
 ): FinalValue {
     return when {
@@ -170,7 +170,7 @@ internal fun Option.getFinalValue(
 // final value again to check for values from other sources.
 internal fun Option.hasEnvvarOrSourcedValue(
     context: Context,
-    invocations: List<Invocation>,
+    invocations: List<OptionInvocation>,
 ): Boolean {
     val envvar = (this as? OptionWithValues<*, *, *>)?.envvar
     val final = this.getFinalValue(context, invocations, envvar)
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
index 368fcba6..b9daee1f 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
@@ -12,7 +12,7 @@ import com.github.ajalt.clikt.parameters.transform.HelpTransformContext
 import com.github.ajalt.clikt.parameters.transform.TransformContext
 import com.github.ajalt.clikt.parameters.transform.message
 import com.github.ajalt.clikt.parameters.types.int
-import com.github.ajalt.clikt.parsers.Invocation
+import com.github.ajalt.clikt.parsers.OptionInvocation
 import com.github.ajalt.clikt.sources.ValueSource
 import com.github.ajalt.mordant.terminal.Terminal
 import kotlin.jvm.JvmMultifileClass
@@ -191,7 +191,7 @@ private class OptionWithValuesImpl<AllT, EachT, ValueT>(
         return helpGetter?.invoke(HelpTransformContext(context)) ?: ""
     }
 
-    override fun finalize(context: Context, invocations: List<Invocation>) {
+    override fun finalize(context: Context, invocations: List<OptionInvocation>) {
         val invs = when (val v = getFinalValue(context, invocations, envvar)) {
             is FinalValue.Parsed -> {
                 when (valueSplit) {
@@ -208,13 +208,13 @@ private class OptionWithValuesImpl<AllT, EachT, ValueT>(
             }
 
             is FinalValue.Sourced -> {
-                v.values.map { Invocation("", it.values) }
+                v.values.map { OptionInvocation("", it.values) }
             }
 
             is FinalValue.Envvar -> {
                 when (valueSplit) {
-                    null -> listOf(Invocation(v.key, listOf(v.value)))
-                    else -> listOf(Invocation(v.key, v.value.split(valueSplit)))
+                    null -> listOf(OptionInvocation(v.key, listOf(v.value)))
+                    else -> listOf(OptionInvocation(v.key, v.value.split(valueSplit)))
                 }
             }
         }
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
index e562aec2..b55aabcd 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/Invocation.kt
@@ -9,7 +9,7 @@ import com.github.ajalt.clikt.parameters.options.Option
 /**
  * The output of parsing a single option and its values.
  */
-data class Invocation(
+data class OptionInvocation(
     /**
      * The name that was used to invoke the option. May be empty if the value was not retrieved
      * from the command line (e.g. values from environment variables).
@@ -42,7 +42,7 @@ class ArgumentInvocation(
  */
 class CommandInvocation<T : BaseCliktCommand<T>>(
     val command: T,
-    val optionInvocations: Map<Option, List<Invocation>>,
+    val optionInvocations: Map<Option, List<OptionInvocation>>,
     val argumentInvocations: List<ArgumentInvocation>,
     /**
      * The subcommands of this command that were invoked.
diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
index cb687df7..241a7515 100644
--- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
+++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parsers/ParserInternals.kt
@@ -360,7 +360,7 @@ private data class CommandParseResult<T : BaseCliktCommand<T>>(
     val i: Int,
     val errors: List<CliktError>,
     val expandedArgv: List<String>,
-    val optInvocations: Map<Option, List<Invocation>>,
+    val optInvocations: Map<Option, List<OptionInvocation>>,
     val argInvocations: List<ArgumentInvocation>,
 ) {
     fun toInvocation(subcommands: List<CommandInvocation<T>>) = CommandInvocation(
@@ -373,7 +373,7 @@ private data class CommandParseResult<T : BaseCliktCommand<T>>(
 }
 
 private data class OptInvocation(val opt: Option, val name: String, val values: List<String>) {
-    val inv get() = Invocation(name, values)
+    val inv get() = OptionInvocation(name, values)
 }
 
 private data class OptParseResult(