Deprecate TermUi IO functions

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 

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

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 <T> 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,

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"

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,25 +18,25 @@ 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"), "")
     }
     ```
 
 ## 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,19 +50,19 @@ 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!")
 }
 ```
 
 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)
 ```
 
 

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<String>) {

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

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)

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.")
     }
 }