Command-line interface description language | Hacker News Reader

Command-line interface description language

docopt.org

133 pointsprimroot27 comments

What would make this killer is if it automatically generated a top-notch bash completion script, like the kind that exists for git. There are very few that exploit the full potential. In fact, without that feature, this seems like overkill for a CLI. A CLI is already the simplest kind of interface, and it usually takes years for a tool to acquire that many features.

Oh nice, a golang opt parser that doesn't flout age-old Unix traditions.

I'm curious, what's the significance of the use of --optname instead of -optname in a lot of *nix CLI apps?

It disambiguates multiple short flags from a long flag. Ie. if the program happened to have short flags l, o, n, g, and l could also be the whole word long, which would

    -long

mean?

For example, single hyphens are stackable.

For example, this: http://explainshell.com/explain?cmd=tar+-z+-c+-f

Is the same as: http://explainshell.com/explain?cmd=tar+-zcf

But trying to stack double-dashed arguments would be stupid: http://explainshell.com/explain?cmd=tar+--helpversion

> For example, this: http://explainshell.com/explain?cmd=tar+-z+-c+-f

> Is the same as: http://explainshell.com/explain?cmd=tar+-zcf

Which is also the same as http://explainshell.com/explain?cmd=tar+zcf because of the unique way tar treats argv[1].

as mentioned by others, the double hyphen makes all the difference, since `foo -flags` is the same as `foo -f -l -a -g -s`. if you allow single-dash long options you'll lose the appeal of short options. my favorite example is `grep -FIHnrie sth smw`: short option bundling is a massive usability enabler.

let me turn the question around: you imply that you wouldn't miss bundling of short options. what tools do you use most? how come you'd not find `-a -b -c -d -e` inferior to `-abcde`?

I come from the DOS/Windows side, where it's relatively uncommon for CLI programs to support bundled options. When it's done, it usually is disambiguated by context -- for instance, -Oxyz to enable compiler optimizations x, y, and z. That's always worked OK for the programs I've dealt with, but obviously the *nix world has a culture of more elaborate and advanced command line tool usage. So it just didn't occur to me that this is what the -- business was for.

I wasn't objecting to it, just wondering why it was done that way.

I think getopt provides a better middle ground between flag and docopt. Flag package syntax with short and long flag support

http://godoc.org/code.google.com/p/getopt

Although it seems like a great tool (and it is), when you start using docopt, it becomes tedious to check for complex command subcommand cases, for example, especially when you have lots of them, and you then switch to Click, JCommander, or the likes.

We've found docopt to a great fit for complex subcommands. Create a simple global usage string `command <subcommand> [options]` and call docopt again with the subcommand's specific usage.

It would be a nice convention if CLI applications shipped a USAGE.txt or OPTIONS.txt file written in docopt in the root of their repo, along other standard files that one expects to be there like README.txt, requirements.txt, setup.py, project.json, etc.

That way it would be easier to write utilities for testing the CLI, to generate the shell completion script and to change the interface without messing with hard-coded strings in the code.

There is a convention of providing concise documentation of options in `<command> --help` and more verbose documentation of options in the man page. When you look through a variety of common tools' documentation, you will notice that there are conventions that could almost be called a standard. But when you look carefully, you will find minor but important differences in how various tools write the options documentation -- enough to inhibit parsing it automatically.

I remember there was http://click.pocoo.org/ once on the front-page too.

This https://news.ycombinator.com/item?id=7639214 I guess

After using docopt for a while you're realize you don't want to google and trial&error text strings somewhere in the file and eventually switch to argtools to realize how easy it can really be ;)

This is how simple all code should be :-) Good Job!

Hm! I once looked at auto-generating GUI wrappers for command line programs from their manpage syntax, but it turned out that manpage syntax, while it looks standardised to a human, isn't. This would open a lot of really exciting possibilities if it were more widely used.

So elegant and obvious in retrospect. More stuff like this, please!

I think it'd be better if the CLI is described in a simpler and machine readable language, and then generate usage text and parser from that.

Well, I think the concept is to force you to write documentation by holding your code hostage. :)

docopt is cool, but is there something new here? It's been around for a while.

Clearly quite a few find this interesting since it made its way to the front page.

I certainly found this interesting and implemented the node.js package[1] in a project just now. I found it super easy to use -- much moreso than minimist[2] or commander[3].

[1]: https://github.com/docopt/docopt.coffee

[2]: https://github.com/substack/minimist

[3]: https://github.com/visionmedia/commander.js

I certainly didn't know about it. I had the exact same issue with argparse as the video on the page showed, I always had to look of the documentation to use it or copy and paste it from old scripts to get it to work. This is soo much better, I don't think I'll use argparse again.

HN submissions don't have to be new—just interesting.

There's been quite a lot of new progress - implementations for new languages in particular. Last time I checked there was no backend for C.

Reply on news.ycombinator.com