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.
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
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.
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.
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 ;)
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.
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].
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.
