Update docs with latest usage recommendations (#528)

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

@@ -104,7 +104,7 @@ class Context private constructor(
     val data: MutableMap<String, Any?>,
 
     /**
-     * The terminal echoer to use for output.
+     * The callable to call to echo output.
      */
     val echoMessage: MessageEchoer,
 

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

@@ -20,27 +20,29 @@ import com.github.ajalt.clikt.parsers.CommandLineParser
  * On JVM, if you want to use this class and define the above features:
  *
  * ```kotlin
- *    abstract class MyCoreCommand : CoreCliktCommand() {
- *        init {
- *            context {
- *                argumentFileReader = {
- *                    with(Paths.get(it)) {
- *                        if (isRegularFile()) readText() else throw FileNotFound(it)
- *                    }
- *                }
- *                envvarReader = { System.getenv(it) }
- *                exitProcess = { System.exit(it) }
- *                echoer = { context, message, newline, err ->
- *                    val writer = if (err) System.err else System.out
- *                    if (newline) {
- *                        writer.println(message)
- *                    } else {
- *                        writer.print(message)
- *                    }
- *                }
- *            }
- *        }
- *    }
+ * abstract class MyCoreCommand : CoreCliktCommand() {
+ *     init {
+ *         context {
+ *             readArgumentFile = {
+ *                 try {
+ *                     Path(it).readText()
+ *                 } catch (e: IOException) {
+ *                     throw FileNotFound(it)
+ *                 }
+ *             }
+ *             readEnvvar = { System.getenv(it) }
+ *             exitProcess = { System.exit(it) }
+ *             echoMessage = { context, message, newline, err ->
+ *                 val writer = if (err) System.err else System.out
+ *                 if (newline) {
+ *                     writer.println(message)
+ *                 } else {
+ *                     writer.print(message)
+ *                 }
+ *             }
+ *         }
+ *     }
+ * }
  * ```
  *
  */

docs/advanced.md

@@ -237,16 +237,16 @@ You also use this functionality to implement command prefixes:
 
 To prevent ambiguities in parsing, aliases are only supported for
 command names. However, there's another way to modify user input that
-works on more types of tokens. You can set a [`tokenTransformer`][tokenTransformer] on the
-[command's context][customizing-context] that will be
-called for each option and command name that is input. This can be used
+works on more types of tokens. You can set [`transformToken`][transformToken] on the
+[command's context][customizing-context], which will be
+called for each option and command name that's input. This can be used
 to implement case-insensitive parsing, for example:
 
 === "Example"
     ```kotlin
     class Hello : CliktCommand() {
         init {
-            context { tokenTransformer = { it.lowercase() } }
+            context { transformToken = { it.lowercase() } }
         }
 
         val name by option()
@@ -336,7 +336,7 @@ If you want to use a value starting with `@` as an argument without expanding it
 
 1. Pass it after a `--`, [which disables expansion for everything that occurs after it][dash-dash].
 2. Escape it with `@@`. The first `@` will be removed and the rest used as the argument value. For example, `@@file` will parse as the string `@file`
-3. Disable @argfile expansion entirely by setting [`Context.argumentFileReader = null`][argumentFileReader]
+3. Disable @argfile expansion entirely by setting [`Context.readArgumentFile = null`][readArgumentFile]
 
 ### File format
 
@@ -584,12 +584,14 @@ use:
 abstract class MyCoreCommand : CoreCliktCommand() {
     init {
         context {
-            argumentFileReader = {
-                with(Paths.get(it)) {
-                    if (isRegularFile()) readText() else throw FileNotFound(it)
+            readArgumentFile = {
+                try {
+                    Path(it).readText()
+                } catch (e: IOException) {
+                    throw FileNotFound(it)
                 }
             }
-            envvarReader = { System.getenv(it) }
+            readEnvvar = { System.getenv(it) }
             exitProcess = { System.exit(it) }
             echoMessage = { context, message, newline, err ->
                 val writer = if (err) System.err else System.out
@@ -648,7 +650,7 @@ These platforms are supported for the [core module](#core-module) only.
 [SuspendingCliktCommand]:        api/clikt-mordant/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
-[argumentFileReader]:            api/clikt/com.github.ajalt.clikt.core/-context/argument-file-reader.html
+[readArgumentFile]:              api/clikt/com.github.ajalt.clikt.core/-context/read-argument-file.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
@@ -665,4 +667,4 @@ These platforms are supported for the [core module](#core-module) only.
 [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-mordant/com.github.ajalt.clikt.testing/test.html
-[tokenTransformer]:              api/clikt/com.github.ajalt.clikt.core/-context/token-transformer.html
+[transformToken]:                api/clikt/com.github.ajalt.clikt.core/-context/transform-token.html

docs/documenting.md

@@ -432,15 +432,15 @@ When an option or subcommand is mistyped, Clikt will suggest corrections that ar
     ```
 
 By default, Clikt will suggest corrections of any similar option or subcommand name based on a
-similarity metric. You can customize the suggestions by setting a `correctionSuggestor` on your
+similarity metric. You can customize the suggestions by setting `suggestTypoCorrection` on your
 command's context.
 
 ```kotlin
 class Cli : NoOpCliktCommand() {
     init {
         context {
             // Only suggest corrections that start with the entered value
-            correctionSuggestor = { enteredValue, possibleValues ->
+            suggestTypoCorrection = { enteredValue, possibleValues ->
                 possibleValues.filter { it.startsWith(enteredValue) }
             }
         }

docs/options.md

@@ -1083,14 +1083,14 @@ All other values are invalid.
 ### Overriding system environment variables
 
 You can set a custom function that will be used instead of the system environment variables with
-[ContextBuilder.envvarReader][envvarReader].
+[ContextBuilder.readEnvvar][readEnvvar].
 
 ```kotlin
 @Test
 fun `test envvar`() {
     val envvars = mapOf("MY_TOOL_OPTION" to "value")
     val tool = MyTool().context {
-        envvarReader = { envvars[it] }
+        readEnvvar = { envvars[it] }
     }
     tool.parse(emptyList())
     assertEquals("value", tool.option)
@@ -1242,7 +1242,7 @@ val opt: Pair<Int, Int> by option("-o", "--opt")
 [defaultLazy]:                 api/clikt/com.github.ajalt.clikt.parameters.options/default-lazy.html
 [deprecated]:                  api/clikt/com.github.ajalt.clikt.parameters.options/deprecated.html
 [eagerOption]:                 api/clikt/com.github.ajalt.clikt.parameters.options/eager-option.html
-[envvarReader]:                api/clikt/com.github.ajalt.clikt.core/-context/-builder/envvar-reader.html
+[readEnvvar]:                  api/clikt/com.github.ajalt.clikt.core/-context/-builder/read-envvar.html
 [feature-switch-flags]:        #feature-switch-flags
 [file]:                        api/clikt/com.github.ajalt.clikt.parameters.types/file.html
 [flag]:                        api/clikt/com.github.ajalt.clikt.parameters.options/flag.html