Fix lints and doc typos

CHANGELOG.md

@@ -288,7 +288,7 @@
 
 ### Changed
 - `option()` and `argument()` now take optional `completionCandidates` parameters to override how completion is generated. The constructor and `copy` functions of `OptionsWithValues` and `ProcessedArgument` have changed to support default values.
-- The overloads of `findObject` ([1](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/-context/find-object/) [2](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/find-object/)) that take a default value have been renamed `findOrSetObject`. The existing names are marked with `@Deprecated`, and IntelliJ can convert your callsites automatically. ([#110](https://github.com/ajalt/clikt/issues/110))
+- The overloads of `findObject` ([1](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/-context/find-object/) [2](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/find-object/)) that take a default value have been renamed `findOrSetObject`. The existing names are marked with `@Deprecated`, and IntelliJ can convert your call sites automatically. ([#110](https://github.com/ajalt/clikt/issues/110))
 - `enum()` parameters now accept case-insensitive values by default. You change this behavior by passing `ignoreCase = false` to `enum()` ([#115](https://github.com/ajalt/clikt/issues/115))
 
 ### Fixed
@@ -334,7 +334,7 @@
 - Marking options as deprecated with [`option().deprecated()`](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.parameters.options/deprecated/)
 - You can manually set the pattern to split envvars on by passing a pattern to the `envvarSplit` parameter of [`option()`](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.parameters.options/option/)
 - [Option groups](https://ajalt.github.io/clikt/documenting/#grouping-options-in-help), [mutually exclusive groups](https://ajalt.github.io/clikt/options/#prompting-for-input), [co-occurring groups](https://ajalt.github.io/clikt/options/#co-occurring-option-groups), and [choice options with groups](https://ajalt.github.io/clikt/options/#choice-options-with-groups)
-- Support for [Command line argument files](https://ajalt.github.io/clikt/advanced/#command-line-argument-files-files) a.k.a "@-files"
+- Support for [Command line argument files](https://ajalt.github.io/clikt/advanced/#command-line-argument-files-files) a.k.a. "@-files"
 
 ### Changed
 - If multiple `--` tokens are present on the command line, all subsequent occurrences after the first are now parsed as positional arguments. Previously, subsequent `--` tokens were skipped.  

README.md

@@ -15,7 +15,7 @@ Clikt has:
  * arbitrary nesting of commands
  * composable, type safe parameter values
  * generation of help output and shell autocomplete scripts
- * multiplatform packages for JVM, NodeJS, and native Linux, Windows and MacOS 
+ * multiplatform packages for JVM, Node.js, and native Linux, Windows and macOS 
 
 What does it look like? Here's a complete example of a simple Clikt program:
 
@@ -69,10 +69,10 @@ dependencies {
 
 #### Multiplatform
 
-Clikt supports the following targets: `jvm`, `mingwX64`, `linuxX64`, `macosX64`, and `js` (for both NodeJS and
-Browsers). Artifacts for macosArm64 are also published, but not tested with CI.
-[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 supports the following targets: `jvm`, `mingwX64`, `linuxX64`, `macosX64`, and `js` (for both
+Node.js and Browsers). Artifacts for macosArm64 are also published, but not tested with CI. [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.
 
 #### Snapshots
 

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt

@@ -11,16 +11,16 @@ annotation class ExperimentalCompletionCandidates
  */
 sealed class CompletionCandidates {
     /** Do not autocomplete this parameter */
-    object None : CompletionCandidates()
+    data object None : CompletionCandidates()
 
     /** Complete with filesystem paths */
-    object Path : CompletionCandidates()
+    data object Path : CompletionCandidates()
 
     /** Complete with entries in the system's hostfile */
-    object Hostname : CompletionCandidates()
+    data object Hostname : CompletionCandidates()
 
     /** Complete with usernames from the current system */
-    object Username : CompletionCandidates()
+    data object Username : CompletionCandidates()
 
     /** Complete the parameter with a fixed set of strings */
     data class Fixed(val candidates: Set<String>) : CompletionCandidates() {

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt

@@ -249,7 +249,7 @@ abstract class CliktCommand(
     /**
      * 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
+     * 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) {
@@ -270,7 +270,7 @@ abstract class CliktCommand(
     /**
      * 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
+     * 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) {

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/ParameterHolder.kt

@@ -11,7 +11,7 @@ interface ParameterHolder {
     /**
      * Register an option with this command or group.
      *
-     * This is called automatically for the built in options, but you need to call this if you want to add a
+     * 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: GroupableOption)

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/mpp/MppH.kt

@@ -8,7 +8,7 @@ internal expect fun readEnvvar(key: String): String?
 
 internal expect fun isWindowsMpp(): Boolean
 
-/** Doesn't return Nothing, since it's a no-op on the browser */
+/** Doesn't return [Nothing], since it's a no-op on the browser */
 internal expect fun exitProcessMpp(status: Int)
 
 internal expect fun isLetterOrDigit(c: Char): Boolean

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/output/TermUi.kt

@@ -34,6 +34,7 @@ object TermUi {
      *
      * @see editText for usage and parameter descriptions.
      */
+    @Suppress("unused")
     fun editFile(
         filename: String,
         editor: String? = null,

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt

@@ -271,7 +271,7 @@ internal fun <T> defaultValidator(): ArgValidator<T> = {}
  * @param help The description of this argument for help output.
  * @param helpTags Extra information about this option to pass to the help formatter
  */
-@Suppress("unused")
+@Suppress("UnusedReceiverParameter")
 fun CliktCommand.argument(
     name: String = "",
     help: String = "",

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt

@@ -70,7 +70,7 @@ typealias ValueConverter<InT, ValueT> = OptionCallTransformContext.(InT) -> Valu
 typealias ValuesTransformer<ValueT, EachT> = OptionCallTransformContext.(List<ValueT>) -> EachT
 
 /**
- * A callback that transforms all of the calls to the final option type.
+ * A callback that transforms all the calls to the final option type.
  *
  * The input list will have a size equal to the number of times the option appears on the command line.
  */

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/TransformAll.kt

@@ -194,7 +194,7 @@ fun <T : Any> NullableOption<T, T>.prompt(
     promptSuffix: String = ": ",
     showDefault: Boolean = true,
     requireConfirmation: Boolean = false,
-    confirmationPrompt: String = "Repeat for confirmation: ",
+    confirmationPrompt: String = "Repeat for confirmation",
     confirmationMismatchMessage: String = "Values do not match, try again",
 ): OptionWithValues<T, T, T> = transformAll { invocations ->
     val promptText = text ?: longestName()?.let { splitOptionPrefix(it).second }

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ValueSource.kt

@@ -45,7 +45,7 @@ interface ValueSource {
          * @param joinSubcommands If null, keys will not include names of subcommands. If given,
          *   this string be used will join subcommand names to the beginning of keys. For options
          *   that are in a root command, this has no effect. For option in subcommands, the
-         *   subcommand name will joined. The root command name is never included.
+         *   subcommand name will be joined. The root command name is never included.
          * @param uppercase If true, returned keys will be entirely uppercase.
          * @param replaceDashes `-` characters in option names will be replaced with this character.
          */

clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/PromptOptionsTest.kt

@@ -16,6 +16,7 @@ import io.kotest.matchers.string.shouldContain
 import kotlin.js.JsName
 import kotlin.test.Test
 
+@Suppress("unused")
 class PromptOptionsTest {
     @Test
     @JsName("command_prompt")

clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/SubcommandTest.kt

@@ -21,6 +21,7 @@ import io.kotest.matchers.string.shouldContain
 import kotlin.js.JsName
 import kotlin.test.Test
 
+@Suppress("BooleanLiteralArgument")
 class SubcommandTest {
     @Test
     fun subcommand() = forAll(

clikt/src/commonTest/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt

@@ -1,4 +1,4 @@
-@file:Suppress("UnusedImport")
+@file:Suppress("UnusedImport", "unused")
 
 package com.github.ajalt.clikt.parameters.groups
 
@@ -610,6 +610,6 @@ private class Group6 : OptionGroup() {
 }
 
 private sealed class Sealed {
-    object Sealed1 : Sealed()
-    object Sealed2 : Sealed()
+    data object Sealed1 : Sealed()
+    data object Sealed2 : Sealed()
 }

clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/parameters/types/InputStreamTest.kt

@@ -18,7 +18,6 @@ import kotlin.test.Test
 
 
 @Suppress("unused")
-@OptIn(ExperimentalStdlibApi::class)
 class InputStreamTest {
     @get:Rule
     val stdin: TextFromStandardInputStream = emptyStandardInputStream()

clikt/src/nativeMain/kotlin/com/github/ajalt/clikt/mpp/MppImpl.kt

@@ -29,7 +29,7 @@ internal actual fun readFileIfExists(filename: String): String? {
 
             while (true) {
                 val chunk = fgets(buffer, bufferLength, file)?.toKString()
-                if (chunk == null || chunk.isEmpty()) break
+                if (chunk.isNullOrEmpty()) break
                 chunks.append(chunk)
             }
         }

docs/advanced.md

@@ -365,7 +365,7 @@ advantages:
 
 Clikt supports the following platforms in addition to JVM:
 
-### Desktop native (Linux, Windows, and MacOS)
+### Desktop native (Linux, Windows, and macOS)
 
 All functionality is supported, except:
 

docs/autocomplete.md

@@ -24,7 +24,7 @@ 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,
+[`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.
@@ -211,7 +211,7 @@ Bash must be at least version 3, or Zsh must be at least version 4.1.
 [CliktCommand]:          api/clikt/com.github.ajalt.clikt.core/-clikt-command/index.html
 [command-aliases]:       advanced.md#command-aliases
 [file]:                  api/clikt/com.github.ajalt.clikt.parameters.types/file.html
-[fromStdout]:            api/clikt/com.github.ajalt.clikt.completion/-completion-candidates/-custom/from-stdout/
+[fromStdout]:            api/clikt/com.github.ajalt.clikt.completion/-completion-candidates/-custom/-companion/from-stdout.html
 [option]:                api/clikt/com.github.ajalt.clikt.parameters.options/option.html
 [path]:                  api/clikt/com.github.ajalt.clikt.parameters.types/path.html
 [token-normalization]:   advanced.md#token-normalization

docs/migration.md

@@ -64,7 +64,7 @@ without needing the `ExperimentalValueSourceApi` or `ExperimentalCompletionCandi
 ### Localization
 
 By default, all strings are defined in the [`Localization`][Localization] object set on your
-[context][[Context.localization].
+[context][Context.localization].
 
 This means that string parameters like `usageTitle` in the constructor for
 `CliktHelpFormatter` have been removed in favor of functions like

docs/options.md

@@ -105,7 +105,7 @@ independently:
 
 Since the three types of customizations are orthogonal, you can choose
 which ones you want to use, and if you implement a new customization, it
-can be used with all of the existing functions without any repeated
+can be used with all the existing functions without any repeated
 code.
 
 ## Default Values
@@ -596,7 +596,7 @@ you can make an option group [`cooccurring`][cooccurring].
 Co-occurring groups must have at least one
 [`required`][required] option, and may also
 have non-required options. The `required` constraint is enforced if any of the options in the group
-are given on the command line. If none if the options are given, the value of the group is null.
+are given on the command line. If none of the options are given, the value of the group is null.
 
 === "Example"
     ```kotlin
@@ -786,7 +786,7 @@ The default prompt string is based on the option name, but
 
 ## Password Prompts
 
-You can also create a option that uses a hidden prompt and asks for
+You can also create an option that uses a hidden prompt and asks for
 confirmation. This combination of behavior is commonly used for
 passwords.
 
@@ -1026,7 +1026,7 @@ You can enable automatic envvar name inference by setting the `autoEnvvarPrefix`
 [`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 a subcommand called `foo` with an option `--bar`, and your prefix is
+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"

docs/parameters.md

@@ -54,7 +54,7 @@ Both options and arguments can convert the String that the user inputs
 to other types.
 
 Types work by transforming the return value of the property delegate. By
-default parameters have a string type:
+default, parameters have a string type:
 
 ```kotlin
 val opt: String? by option(help="an option")
@@ -71,7 +71,7 @@ val arg: Int by argument(help="an argument").int()
 
 ## Built-In Types
 
-There are a number of built in types that can be applied to options and
+There are a number of built-in types that can be applied to options and
 arguments.
 
 ### Int and Long

docs/testing.md

@@ -62,8 +62,9 @@ envvars as well, pass `includeSystemEnvvars=true` to `test`.
 
 ## Testing Prompt Options
 
-If you use [`prompt`][prompt] options, you can use the `stdin` parameter of `test` to pass a string containg all the
-lines of input. If you have multiple prompts, each input should be separated by `\n`.
+If you use [`prompt`][prompt] options, you can use the `stdin` parameter of `test` to pass a string
+containing all the lines of input. If you have multiple prompts, each input should be separated by
+`\n`.
 
 === "Test"
     ```kotlin
@@ -104,6 +105,7 @@ To capture output, [override the command's console][replacing-stdin].
 [main]:                api/clikt/com.github.ajalt.clikt.core/-clikt-command/main.html
 [override-envvar]:     options.md#overriding-system-environment-variables
 [parse]:               api/clikt/com.github.ajalt.clikt.core/-clikt-command/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
 [test]:                api/clikt/com.github.ajalt.clikt.testing/test.html

docs/whyclikt.md

@@ -118,11 +118,11 @@ The Clikt version is of course much simpler, but there are more
 fundamental issues with the `kotlin-argparser` version that drove the
 creation of Clikt:
 
-* Its inheritance-based design means that if you wanted to change the type of each value, you would have to copy all of the code for each type. With Clikt, you could just do `option().int().transformValues(2) { it[0] to it[1] }`
+* Its inheritance-based design means that if you wanted to change the type of each value, you would have to copy all the code for each type. With Clikt, you could just do `option().int().transformValues(2) { it[0] to it[1] }`
 * Its inheritance-based design means that supporting types, multiple values, and multiple option occurrences would require a combinatorial number of copies of the above code. With Clikt, these are all orthogonal.
 * You have to do all error checking yourself. The `argparser` example silently discards extra values, or copies the single value, rather than inform the user of the mistake. You could write more code to do so, but Clikt takes care of it for you.
 * Option name inference is not automatic, requiring you to wrap the delegate with yet another function.
-* Each delegate function has a different name, with no indication of whether its creating an option or positional argument. With Clikt, all options are created with [`option()`][option], and all arguments with [`argument()`][argument].
+* Each delegate function has a different name, with no indication of whether it's creating an option or positional argument. With Clikt, all options are created with [`option()`][option], and all arguments with [`argument()`][argument].
 
 Some of these problems can be solved by writing more code, and some
 can't. On the other hand, Clikt attempts to have a consistent, intuitive,

samples/copy/src/main/kotlin/com/github/ajalt/clikt/samples/copy/main.kt

@@ -1,11 +1,13 @@
 package com.github.ajalt.clikt.samples.copy
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.terminal
 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.types.file
+import com.github.ajalt.mordant.terminal.YesNoPrompt
 
 class Copy : CliktCommand(help = "Copy SOURCE to DEST, or multiple SOURCE(s) to directory DEST.") {
     val interactive by option("-i", "--interactive", help = "prompt before overwrite").flag()
@@ -20,7 +22,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 = confirm("overwrite '$dest'?", default = true)
+                    val response = YesNoPrompt("overwrite '$dest'?", terminal, default = true).ask()
                     if (response == false) continue
                 }
                 if (recursive) file.copyRecursively(dest, overwrite = true)

samples/helpformat/src/main/kotlin/com/github/ajalt/clikt/samples/helpformat/main.kt

@@ -9,6 +9,7 @@ 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
@@ -71,18 +72,13 @@ class Echo(t: Terminal) : CliktCommand(help = "Echo the STRING(s) to standard ou
     }
 }
 
-
+class C : CliktCommand() {
+    val foo by option().prompt(requireConfirmation = true)
+    override fun run() {
+        println("foo: $foo")
+    }
+}
 
 fun main(args: Array<String>) {
-    val theme = Theme {
-        // Use ANSI-16 codes for help colors
-        styles["info"] = TextColors.green
-        styles["warning"] = TextColors.blue
-        styles["danger"] = TextColors.magenta
-        styles["muted"] = TextColors.gray
-
-        // Remove the border around code blocks
-        flags["markdown.code.block.border"] = false
-    }
-    Echo(Terminal(theme = theme)).main(args)
+    C().main(args)
 }