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.

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

Add help() as a separate function for option/argument #207

Closed
serpro69 opened this issue Jul 20, 2020 · 2 comments
Closed

Add help() as a separate function for option/argument #207

serpro69 opened this issue Jul 20, 2020 · 2 comments

Comments

@serpro69
Copy link

serpro69 commented Jul 20, 2020

Would be nice to have the possibility to provide help text through a separate function for options/arguments, as opposed to only having a help argument for option()/argument() functions.
This is particularly useful if you have a multi-line help-text:

Right now it's only possible to do one of the following:

private val test by option("-t", "--test", help = "This is a first help line\nAnd a second line\nAnd another one")
    .choice("unit", "integration", ignoreCase = true)
    .default("unit")

This gets a bit too long to read in an IDE.
Or it could be done like this using kotlin's multi-line strings:

    private val test by option(
        "-t", "--test",
        help = """
            This is a first help line
            And a second line
            And another one
        """)
        .choice("unit", "integration", ignoreCase = true)
        .default("unit")

but it is also not that good if we have any extra functions afterwards such as choice() etc.

With the help() function we could put it at the end like so:

    private val test by option("-t", "--test")
        .choice("unit", "integration", ignoreCase = true)
        .default("unit")
        .help("""
            This is a first help line
            And a second line
            And another one
        """)

This, in my opinion, looks much better than any of the above.

I could try to make a PR for this if you think it would be a good thing to add.

@ajalt
Copy link
Owner

ajalt commented Jul 20, 2020

You can do almost exactly what you want today with the copy function:

private val test by option("-t", "--test")
        .choice("unit", "integration", ignoreCase = true)
        .default("unit")
        .copy(help="""
            This is a first help line
            And a second line
            And another one
        """)

I'm generally not in favor of there being multiple ways to specify the same thing, since that often makes the code harder to understand.

@serpro69
Copy link
Author

Right, I didn't know that was possible. Thanks!

ajalt added a commit that referenced this issue Aug 14, 2020
As discussed in #207 and mentioned in #214, passing command and parameter help as function arguments is not always ideal, especially for longer help text.

For parameters, you can use `.copy(help="...")`, but this is undocumented, and doesn't apply to command help. It might be better to support this officially.

This PR adds `.help()` extensions to options and arguments, and makes `CliktCommand.commandHelp` open so that you can override it rather than passing the command's help to its constructor.

This allows you to write your help like this:

```kotlin
class Echo : CliktCommand() {
    override val commandHelp = "Echo the STRING(s) to standard output"

    val suppressNewline by option("-n").flag()
            .help("do not output the trailing newline")

    val strings by argument().multiple()
            .help("the strings to echo")
}
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants