Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs with latest usage recommendations #528

Merged
merged 1 commit into from
Jul 9, 2024
Merged

Update docs with latest usage recommendations #528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,

Expand Down
44 changes: 23 additions & 21 deletions clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CoreCliktCommand.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
* }
* }
* }
* }
* }
* ```
*
*/
Expand Down
24 changes: 13 additions & 11 deletions docs/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
4 changes: 2 additions & 2 deletions docs/documenting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) }
}
}
Expand Down
6 changes: 3 additions & 3 deletions docs/options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
Loading