Show HN: Markdown command line interface definition | Hacker News Reader

Show HN: Markdown command line interface definition

github.com

27 pointstmpfs7 comments

Great project!

I've been looking for something like this for quite a while. There's compleat [1], but it doesn't seem to allow you to "compile" completions down to bash or zsh - you have to keep compleat (and therefore the whole Haskell stack) on your system.

Of course, none of this would be a problem if there was a standard "--complete <shell>" flag. I ended up doing something a bit like that on a recent project [2] to avoid editing my completion scripts every time I added a new subcommand or flag to a utility.

[1]: https://github.com/mbrubeck/compleat

[2]: https://github.com/woodruffw/kbsecret/blob/master/completion...

Thanks!

Only zsh support at the moment but would like to add bash support when I get some more time to spend on it. I find zsh completion far more powerful and easier to work with.

There is also a nodejs runtime library[1] for parsing arguments from the descriptor and some basic plugins. Later I would like to add runtime libraries for other languages :)

[1]: https://github.com/mkdoc/mkcli-runtime

> I find zsh completion far more powerful and easier to work with.

I'm a bash user, but I can't blame you ;)

Isn't docopt kinda like like this too?

> Of course, none of this would be a problem if there was a standard "--complete <shell>" flag.

PowerShell has interesting (if not very applicable to unix) approach: cmdlet parameters have some standard annotations attached that can be queried with reflection

> PowerShell has interesting (if not very applicable to unix) approach: cmdlet parameters have some standard annotations attached that can be queried with reflection

Yeah, I think that's a tremendously useful feature. The status quo on unix of having 3-4 different program related files (man/info page, shell completions, i18n files) could really cleanly be replaced via a few standardized flags and pipe compositions. Take for example `man`:

    man() { ${1} --man | less }

That's not feature-complete, of course, but IMO that's even more unixy than a bunch of out-of-sync /usr/share clutter.

Do the compiled JSON files have direct compatibility with any JS argument parsing libraries? I read through everything and it wasn't clear to me whether you are on your own once you get the JSON or if there is an automated way to make use of these.

It's an awesome project in either case, but it would be incredibly useful if this could somehow be a stepping stone towards a more language agnostic way of defining command-line interfaces. I do a fair bit of language hopping and it can be frustrating how much the quality of argument parsing frameworks varies between language ecosystems. It's even worse from a user perspective when a utility's interface was obviously determined by the limitations of its language or argument parsing library.

No - not direct compatibility per se, because I don't think it's the responsibility of the argument parsing library to work with the definition. The nodejs runtime[1] uses a lightweight argparse[2] library which is implemented as a plugin. You can then enable additional plugins for argument validation or any other processing you require.

Effectively you end up with two objects, one describing the program and another describing the parsed arguments which should then be passed through a plugin pipeline. The existing runtime plugins[3] illustrate this.

> if there is an automated way to make use of these.

There is using the nodejs runtime, take a look at the source for the mkcli program[4] to get a feel for how it works.

> stepping stone towards a more language agnostic way of defining command-line interfaces

I couldn't agree more, ideally we would implement runtimes in most of the mainstream languages using the pattern described above :)

Hope that helps & thanks for the feedback!

[1]: https://github.com/mkdoc/mkcli-runtime [2]: https://github.com/cli-kit/cli-argparse [3]: https://github.com/mkdoc/mkcli-runtime/tree/master/plugin [4]: https://github.com/mkdoc/mkdoc/blob/master/cli/cli.js

Reply on news.ycombinator.com