Common core for man pages, etc?

[epage]

An idea I've been kicking around is providing an API for describing a CLI, that is agnostic of the parser, so man pages, completions, etc can be shared across parsers. Describing a full CLI gets into a lot of parser-specialized knowledge, but at least something like man pages relies on such a small subset of information that I suspect it could be possible. I suspect the same could be true for static completions but probably not dynamic completions (which I see you are going with in #40).

This something of interest for collaborating on?

[epage]

One aspect of how practical this would be is how well we can define the common definition and integrate it into the parsers.

Using traits for describing a CLI means that the CLI parser will need to implement them and would put them in the public API and would require an extra dependency.

Using custom structs means that a crate on top could convert between the CLI parser and the common definition but there is a little bit more of overhead (could probably borrow for most/all strings?).

Could also offer both.

[pacak]

man page generator maybe - this is something that can be in theory shared. That said I already have a working copy implemented in a private branch, about 100 lines in total, mostly boring templating code. Not particularly interested in publishing it, experiments for now - what can be done.

For completions - #40 is done, will be publishing it in a day or two after I do some more testing. Are there any reasons to prefer static completions? Dynamic seems to be easier to implement (took me a weekend) - for static ones you'll have to deal with a bunch of different shells and more useful in general - experimenting with a cargo thing to autocomplete parameters to binaries and examples in a current workspace.

Common definition might be interesting, but if you look at bpaf's API and squint really hard - you have 4 primitive types: flag, argument, positional and command - created by builders and 2 operations: construct! and parse (at least as far as internal monad is concerned, users sees only applicative interface so in addition to parse there's optional and many). Plus run to extract things. plus now complete for completions. construct! must be strictly typed so most of the things are code, not data. Can this be made compatible with other approaches in either direction?

[pacak]

Do you have any code or any notes already?

[epage]

man page generator maybe - this is something that can be in theory shared. That said I already have a working copy implemented in a private branch, about 100 lines in total, mostly boring templating code. Not particularly interested in publishing it, experiments for now - what can be done.

If you already have a form of man pages and only care about dynamic completions, probably not worth it at this time.

Part of my interest in this (and projects like os_str_bytes and lexopt / clap_lex) is to make it easier for people to bring up a new CLI parser so they can iterate on and try out new ideas. I was hoping bpaf would be a motivating opportunity but it seems I reached out too late.

For completions - #40 is done, will be publishing it in a day or two after I do some more testing. Are there any reasons to prefer static completions? Dynamic seems to be easier to implement (took me a weekend) - for static ones you'll have to deal with a bunch of different shells and more useful in general - experimenting with a cargo thing to autocomplete parameters to binaries and examples in a current workspace.

Benefits of dynamic completions

• More shared code between shells
• Fewer chances for escaping bugs
• More complex functionality (like having users provide a completion function)

Benefits of static completions

• The user can choose to have no runtime overhead by having completions shipped with the binary
• More shells can be supported (e.g. fig, haven't looked into needs of all of the other shells yet)

Overall, I prefer the dynamic completion approach and want to move clap in that direction (we have a PoC of it).

Can this be made compatible with other approaches in either direction?

Most of what you listed deal with parsing semantics which isn't needed for man pages. For arguments, its just a question of what flags and value names exist for it, the help, and maybe one or two other details.

Even static completions can get away with basic parsing semantics and don't need more complex parsing nuance.

Do you have any code or any notes already?

We have clap-rs/clap#2912 but it doesn't have much in the way of details as I've been focusing in other areas.

[pacak]

The user can choose to have no runtime overhead by having completions shipped with the binary

Completions are not shipped with the binary, monad runner is. It adds about extra 40kb - bpaf 0.5.x apps with completions should be smaller than 0.4.x without them... Will probably be even less after I look at what takes up most of the size :)

More shells can be supported (e.g. fig, haven't looked into needs of all of the other shells yet)

Any shell that supports calling a function "command arguments" -> "completions" should be possible to support dynamically.

Even static completions can get away with basic parsing semantics and don't need more complex parsing nuance.

I see.. Yea, for manpages it's enough to dump flags/parameters/etc along with help messages. But once you get that the difference between dumping them and dumping manpage itself is kind of small.

We have clap-rs/clap#2912

Thank you, will take a look tomorrow.

[pacak]

Came up with this with man page specific stuff sitting in src/manpage.rs: #137

Taking a closer look at roff crate, most of this code can probably live there.