kingpin

kingpin copied to clipboard

This issue is to track feature implementation for v3. I'm mostly happy with the core functionality in v2, but there are a few rough edges. To that end, v3 will be mostly cleanup and streamlining.

• [x] Make hooks less ugly: Action(*Context) should be something like Action(value Value) perhaps, and called something other than Action. Not sure. See #125.
• [x] Clean up how boolean flags work (see #54).
• [x] Convert more values to use the generator.
• [x] Some way to manipulate flags after configuration but before parsing. This is useful when a package has defaults that you'd like to override in the main binary. This is currently impossible. (implemented in 292d4f20095c70c7599634c58870b0567d6a6820)
• [ ] Help "sections". This would be used to add sections to man pages, and to the plain text output.
• [ ] Rethink the way @ and - work. See #65.
• [x] Make usage functions more consistently follow a pattern. Similar to how the regexp package works.
• [ ] Support a single environment variable that is parsed for flags. eg. APP="-a -bfoo --something"
• [x] Configurable help. Some people want enums displayed, default values, envars, etc. Maybe help strings should have their own var expansion.
• [ ] Allow recursive value expansion: eg. given flag foo=${BAR} and flag bar=asdf, foo will evaluate to asdf.
• [x] Cleaner usage/help API. eg. Usage(text) and WriteUsage*.
• [x] Usage templates should allow custom template functions/context.
• [ ] Support mutually exclusive groups.
• [ ] Support for mixed mode boolean+value flags. eg. --purge, --purge=24h? Could use a nil value to indicate not provided? Not sure this is a good idea, plus it's hard to parse.
• [x] Use comma (or semi-colon) separated environment variables, with support for escaping (fixed by resolvers added in b62665b4ea4ea556c9a1ed1525ee77e8e289a9ef).
• [ ] "Fix" default values (see #115).
  • [x] Values that open files result in leaked FDs if they have default values (removed feature).
• [x] Ability to customise --help flag (see #119)
• [x] --version and --help should go to stdout, errors to stderr (eg. #120) (implemented in 9f68dc0167caf0e2b2765183636f38d4780e9d44)
• [x] Make TCP types et al return strings rather than net.* types.
• [ ] Allow values to be configurable somehow (1)
• [x] Make Default() apply before parsing (implemented in 3f9c38e642472881fff9512eae289b40ac4148e1)
• [x] Support flag definitions from tagged structs (implemented in 319ba9076ccd5d047ba10d27a84922a393fbe76d).
• [x] Internationalisation support (started in 20700aa670b125872f58acd318986e777a103ab7)
• [x] Provide a list of environment variables to use as fallback (see #92) (achievable with custom resolvers).
• [x] Some values, such as repeating ones, would benefit from being more configurable. eg. Making sequences optionally support being comma-separated lists. I'm not sure how this would work in practice, but perhaps use the XXXOption configuration closure convention? eg. Strings(options...ValueOption) where type ValueOption func(conf map[string]string) error? (b88248d8da3f8a9eb99fc83b47a53b295e9fc8ee)
• [x] Support for interspersing arguments and commands (eg. cmd0 <arg0> <arg1> cmd1 <arg2>) (801d8e545ccdde3fcaaec3ddafc4827969635aa5).
• [x] Distinct boolean and negatable-boolean flags (bf710ba16f982acf6eca0084acd9cb933151aa45).

It would be nice when kingpin used the package godoc (maybe even the function goods) to generate the manpage.

I'm not sure how that would work. What documentation would it extract? From where?

+1 for "Rethink the way @ and - work"

specifically the single - by itself

+1 for comma-separated lists with autocompletion: --roles quorum,master,worker

(I'm not sure if this issue is an invitation for feature requests, sorry 😇 ).

There's one thing I've wanted more than once that might fall under what you mean for for 'Help "sections"', I'm not sure: "long" help for certain items, usually subcommands. Basically, I wish for a one-line help summary that shows in --help (as it works today), with additional explanation that appears for command help subcommand. When I first started using Kingpin the --help-long led me to believe that may do what I want out of the box, but that isn't how it works.

In one (internal tool) case I resorted to using backtick literals for such long help, but that isn't ideal—it makes the default usage --help output too verbose, I manually wrapped text to sane column widths, etc. Custom template work could most likely solve this (I think?) but IMHO it seems like a use case that might be common enough to be built in. Given some time I'll try to take a stab at it, let me know if you already have some design ideas (perhaps we can open a new todo issue to keep this thread under control).

Also, +1 on @ handling, like #65 I have also repeatedly had cases where I want to implement things like --json @config.json.

That's a good idea @ches.

Maybe it is already possible, but otherwise an idea would be to show boolean flags with Default("true") set, as --no-theflag instead of --theflag. Since otherwise the user has to know about the fact that --no- is supported, or one has to write it in the description.

Yes, agreed, that would be very useful.

Also, what You think about allowing the hintAction on .Short('')? That doesn't work at the moment...

Can you clarify? Do you mean completion won't complete short flags?

Is it possible to have the HintAction() on one option be dependent on the value of another part of the command. e.g. I have a sub-command with a --installThisVersion flag, but the list of available versions would be dependent on something specified earlier on the same command line, like :

./myapp install apache_tomcat --version <tab>{"1.6", "2.4"}
./myapp install websphere --version <tab>{"6.0", "7.0"}

In my actual use case, I'd like the HintAction command to go off to a web service and query it for a list of possible completions, but I need someway to get a parameter into the HintAction function, and the value of that parameter needs to come from another part of the command line. Is this at all possible?

@godeater This sounds like a question that would be more appropriate for someplace like Stack Overflow than this roadmap issue. I have done something similar to what you're asking with Kingpin, it's a bit ugly and I'm not entirely happy with the solution, but it does get the job done for me. I can share it in a more topical forum.

@ches as is ever the way, in writing up the stackoverflow question, I made this work. So I guess this isn't a feature request :)

@ has been removed in v3-unstable.

Maybe I am too late to the game to suggest features for V3. Any thoughts about trying to guess the command a user wanted? For example:

myprompt: git shwo git: 'shwo' is not a git command. See 'git --help'.

Did you mean this? show

ps. Just used kingpin for the first time. Switched from the default "flag" library. Kingpin made my application better, plus resulted in less code that was clearer to understand.

That would be quite useful, though I think it could be already possible with use of the app.ParseContext(args). I'm pretty sure it has all of the information required to do this.

In reference to:

Support for mixed mode boolean+value flags. eg. --purge, --purge=24h? Could use a nil value to indicate not provided? Not sure this is a good idea, plus it's hard to parse.

I'm not sure if you're looking to see if it was specifically passed bare once, or if it was passed at all. At times I see problems distinguishing between the default for a flag and that same value passed.

I personally have another flag package that adds an .IsSet() method to the flag. If the flag was ever set on CLI, .IsSet() returns true, otherwise it returns false.

I believe similar behavior could currently be achieved with *flag.Counter() > 0, but an .IsSetFlag() would likely be more obvious.

Something like LegalFileOrDirPath would be nice. Similar to a ExistingFileOrDir that only accepts the path to an existing file, directory, or absent file in a directory. E.g: /tmp/foo, /tmp/, are both accepted because /tmp/ exists, but /tmp/bar/foo would not if /tmp/bar does not exist.

Errors for Required() flags (e.g. missing value) should not only indicate the flag name, but also the environmental variable key - e.g.

{"msg":"required flag --twitter-consumer-secret not provided","ts":"2018/01/14 21:10:52"}

... should be:

{"msg":"required flag --twitter-consumer-secret not provided (envar: "TWITTER_CONSUMER_SECRET")","ts":"2018/01/14 21:10:52"}

this issue is abandoned?

Will you consider release a preview or alpha version for v3 in recent future?