Rewrite parser to support custom run signatures

CHANGELOG.md

@@ -1,10 +1,47 @@
 # 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.
+- 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.
 
+### 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:** Moved the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
+
+  | removed parameter           | 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`            |
+- 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.
+
+### 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))

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.

clikt/build.gradle.kts

@@ -38,6 +38,8 @@ kotlin {
             dependencies {
                 api(kotlin("test"))
                 api(libs.kotest)
+                api(libs.coroutines.core)
+                api(libs.coroutines.test)
             }
         }
 

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/ChainedCliktCommand.kt

@@ -0,0 +1,171 @@
+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
+ * subcommands.
+ *
+ * This command works best if you set [allowMultipleSubcommands] to `true`.
+ */
+abstract class ChainedCliktCommand<T>(
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
+    name: String? = null,
+) : BaseCliktCommand<ChainedCliktCommand<T>>(name) {
+    /**
+     * 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.mainReturningValue(this) { 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): T {
+    return 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
+}
+
+
+/**
+ * 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)
+    }
+}

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/command/SuspendingCliktCommand.kt

@@ -0,0 +1,156 @@
+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.
+ */
+abstract class SuspendingCliktCommand(
+    /**
+     * The name of the program to use in the help output. If not given, it is inferred from the
+     * class name.
+     */
+    name: String? = null,
+) : BaseCliktCommand<SuspendingCliktCommand>(name) {
+    /**
+     * 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) { parse(argv) }
+}
+
+/**
+ * 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: 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() }
+}
+
+/**
+ * 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)
+    }
+}