
Command-line interface description language - primroot
http://docopt.org/
======
mtdewcmu
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.

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

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

~~~
stormbrew
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?

~~~
ChristianBundy
For example, single hyphens are stackable.

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

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

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

~~~
spb
> For example, this:
> [http://explainshell.com/explain?cmd=tar+-z+-c+-f](http://explainshell.com/explain?cmd=tar+-z+-c+-f)

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

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

------
kolev
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.

~~~
gabrtv
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.

------
rbonvall
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.

~~~
mtdewcmu
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.

------
X4
I remember there was [http://click.pocoo.org/](http://click.pocoo.org/) once
on the front-page too.

~~~
agumonkey
This
[https://news.ycombinator.com/item?id=7639214](https://news.ycombinator.com/item?id=7639214)
I guess

------
buster
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 ;)

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

------
dTal
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.

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

------
nialv7
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.

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

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

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

~~~
skeoh
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](https://github.com/docopt/docopt.coffee)

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

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

