From 3371beffc04d169a29a16525275e84381c92a434 Mon Sep 17 00:00:00 2001 From: AJ Date: Sun, 24 Apr 2022 20:23:42 -0700 Subject: [PATCH] Deprecate TermUi IO functions --- CHANGELOG.md | 4 ++++ .../github/ajalt/clikt/core/CliktCommand.kt | 2 -- .../com/github/ajalt/clikt/output/TermUi.kt | 8 +++++++- docs/advanced.md | 3 --- docs/utilities.md | 18 +++++++++--------- .../github/ajalt/clikt/samples/aliases/main.kt | 9 ++++----- samples/copy/README.md | 2 +- .../github/ajalt/clikt/samples/copy/main.kt | 3 +-- .../ajalt/clikt/samples/plugins/setuser.kt | 3 +-- 9 files changed, 27 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f23465082..c84b76db4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased +### Deprecated +- `TermUi.echo`, `TermUi.prompt`, and `TermUi.confirm`. Use the equivalent methods on `CliktCommand` instead. ([#344](https://github.com/ajalt/clikt/issues/344)) + ## 3.4.1 ### Added - Publish JS artifacts with new IR compiler, in addition to the legacy format 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 308557c42..dfed03f5c 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 @@ -263,8 +263,6 @@ abstract class CliktCommand( * * This is similar to [print] or [println], but converts newlines to the system line separator. * - * This is equivalent to calling [TermUi.echo] with the console from the current context. - * * @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 diff --git a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/output/TermUi.kt b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/output/TermUi.kt index 1489322c7..12d7306f4 100644 --- a/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/output/TermUi.kt +++ b/clikt/src/commonMain/kotlin/com/github/ajalt/clikt/output/TermUi.kt @@ -17,6 +17,7 @@ object TermUi { * @param console The console to echo to * @param lineSeparator The line separator to use, defaults to the [console]'s `lineSeparator` */ + @Deprecated("Use ClickCommand.echo instead") fun echo( message: Any?, trailingNewline: Boolean = true, @@ -90,6 +91,7 @@ object TermUi { * of [default] will be passed to this callback. * @return the user's input, or null if the stdin is not interactive and EOF was encountered. */ + @Deprecated("Use ClickCommand.prompt instead") fun prompt( text: String, default: String? = null, @@ -152,8 +154,10 @@ object TermUi { * @param confirmationPrompt The text to show the user when [requireConfirmation] is true. * @param promptSuffix A delimiter printed between the [text] and the user's input. * @param showDefault If true, the [default] value will be shown as part of the prompt. + * @param console The console to prompt to * @return the user's input, or null if the stdin is not interactive and EOF was encountered. */ + @Deprecated("Use ClickCommand.prompt instead") fun prompt( text: String, default: String? = null, @@ -162,9 +166,10 @@ object TermUi { confirmationPrompt: String = "Repeat for confirmation: ", promptSuffix: String = ": ", showDefault: Boolean = true, + console: CliktConsole = defaultCliktConsole(), ): String? { return prompt(text, default, hideInput, requireConfirmation, - confirmationPrompt, promptSuffix, showDefault) { it } + confirmationPrompt, promptSuffix, showDefault, console) { it } } /** @@ -179,6 +184,7 @@ object TermUi { * @param showDefault if false, the choices will not be shown in the prompt. * @return the user's response, or null if stdin is not interactive and EOF was encountered. */ + @Deprecated("Use ClickCommand.confirm instead") fun confirm( text: String, default: Boolean = false, diff --git a/docs/advanced.md b/docs/advanced.md index e05861ae2..cd215b7f7 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -287,9 +287,6 @@ class CustomCLI : NoOpCliktCommand() { } ``` -If you are using [`TermUI`][TermUI] directly, -you can also pass your custom console as an argument. - ## Command Line Argument Files ("@argfiles") Similar to `javac`, Clikt supports loading command line parameters from a file using the "@argfile" diff --git a/docs/utilities.md b/docs/utilities.md index 6c9ae5f2c..b4edcf033 100644 --- a/docs/utilities.md +++ b/docs/utilities.md @@ -7,7 +7,7 @@ commonly used in command line programs. ## Launching Editors If you need to ask users for multi-line input, or need to have the user edit a file, you can do so -through [`TermUi.editText`][editText] and [`TermUi.editFile`][editFile]. These functions open the +through [`editText`][editText] and [`editFile`][editFile]. These functions open the program defined in the `VISUAL` or `EDITOR` environment variables, or a sensible default if neither are defined. The functions return the edited text if the user saved their changes. @@ -18,7 +18,7 @@ are defined. The functions return the edited text if the user saved their change # Enter your message. # Lines starting with # are ignored """.trimIndent() - return TermUi.editText(message, requireSave = true) + return editText(message, requireSave = true) ?.replace(Regex("#[^\n]*\n"), "") } ``` @@ -26,17 +26,17 @@ are defined. The functions return the edited text if the user saved their change ## Input Prompts Options can [prompt for values automatically][prompting-for-input], but you can also do -so manually with [`TermUi.prompt`][prompt]. By +so manually with [`prompt`][prompt]. By default, it accepts any input string, but you can also pass in a conversion function. If the conversion raises a [`UsageError`][UsageError], the prompt will ask the user to enter a different value. === "Example" ```kotlin - val input = TermUi.prompt("Enter a number") { + val input = prompt("Enter a number") { it.toIntOrNull() ?: throw UsageError("$it is not a valid integer") } - TermUi.echo("Twice your number is ${input * 2}") + echo("Twice your number is ${input * 2}") ``` === "Interactive Session" @@ -50,11 +50,11 @@ the prompt will ask the user to enter a different value. ## Confirmation Prompts You can also ask the user for a yes or no response with -[`TermUi.confirm`][confirm]: +[`confirm`][confirm]: ```kotlin -if (TermUi.confirm("Continue?") == true) { - TermUi.echo("OK!") +if (confirm("Continue?") == true) { + echo("OK!") } ``` @@ -62,7 +62,7 @@ If you simply want to abort the program in the user gives a negative response, you can pass `abort=true`: ```kotlin -TermUi.confirm("Continue?", abort=true) +confirm("Continue?", abort=true) ``` 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 f3f3aac13..6edb71cbd 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 @@ -3,7 +3,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.subcommands -import com.github.ajalt.clikt.output.TermUi import com.github.ajalt.clikt.parameters.options.multiple import com.github.ajalt.clikt.parameters.options.option import java.io.File @@ -23,20 +22,20 @@ class AliasedCli(private val configFile: File) : NoOpCliktCommand( class Push : CliktCommand(help = "push changes") { - override fun run() = TermUi.echo("push") + override fun run() = echo("push") } class Pull : CliktCommand(help = "pull changes") { - override fun run() = TermUi.echo("pull") + override fun run() = echo("pull") } class Clone : CliktCommand(help = "clone a repository") { - override fun run() = TermUi.echo("clone") + override fun run() = echo("clone") } class Commit : CliktCommand(help = "clone a repository") { val message by option("-m", "--message").multiple() - override fun run() = TermUi.echo("commit message=${message.joinToString("\n")}") + override fun run() = echo("commit message=${message.joinToString("\n")}") } fun main(args: Array) { diff --git a/samples/copy/README.md b/samples/copy/README.md index 27f71a017..1d3c0c13d 100644 --- a/samples/copy/README.md +++ b/samples/copy/README.md @@ -1,7 +1,7 @@ # File copy sample This example works like the `cp` command, copying files or directories. -It shows how to use `TermUi` to prompt the user for input. +It shows how to use `prompt` to get an input from user. ``` $ touch src.txt dest.txt 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 087753ff3..1be1fbe3d 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,7 +1,6 @@ package com.github.ajalt.clikt.samples.copy import com.github.ajalt.clikt.core.CliktCommand -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.flag @@ -21,7 +20,7 @@ class Copy : CliktCommand(help = "Copy SOURCE to DEST, or multiple SOURCE(s) to else file.copyTo(dest) } catch (e: FileAlreadyExistsException) { if (interactive) { - val response = TermUi.confirm("overwrite '$dest'?", default = true) + val response = confirm("overwrite '$dest'?", default = true) if (response == false) continue } if (recursive) file.copyRecursively(dest, overwrite = true) 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 444ee683c..996c344f5 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 @@ -2,7 +2,6 @@ package com.github.ajalt.clikt.samples.plugins import com.github.ajalt.clikt.core.CliktCommand import com.github.ajalt.clikt.core.requireObject -import com.github.ajalt.clikt.output.TermUi import com.github.ajalt.clikt.parameters.options.option import com.github.ajalt.clikt.parameters.options.prompt import org.kodein.di.Kodein @@ -27,7 +26,7 @@ class SetUser : CliktCommand( repo.config["username"] = username repo.config["email"] = email repo.config["password"] = "*".repeat(password.length) - TermUi.echo("Changed credentials.") + echo("Changed credentials.") } }