halst

Such a sensible syntax, right? The official ARM docs use it too. Not even sure who invented it, ARM or GAS. Anyway, that's another good reason to start with ARM.

There's also legacy ARMASM syntax that is barely worth mentioning.

ARM32 is much simpler to explain compared to ARM64. Registers are so much simpler, conditional execution is orthogonal, three-operand form is consistent. ARM64 made all the right practical choices, but has doubled the complexity. Still much better than x86 with its 10x complexity.

ARM32 is a gem, in my opinion. A truly simple instruction set, and easy to get your hands on with Raspberry Pi or emulation.

Yeah, and picking a language was the hardest decision for the book. I wrote the compiler prototype for it in OCaml, but using it for the book would have narrowed its audience unnecessarily. In the end, I'm very happy with picking TypeScript: it allowed to discuss the matters of static and dynamic typing within the same language. Using Python with mypy would be another option, but then, since I wanted the source language to be a subset of the implementation language, I would have to explain parsing whitespace-sensitive code, which is tricky.

Thank you for such a favorable comparison with the classics!

Thanks for your early support and going through the draft! I'm glad you've been enjoying it!

In the book, lexing and parsing is done from scratch. I think tools like Flex and Bison are very handy, but for the book, my focus is on learning value.

So far, I got away with "In the following figure…"

About long options repeated: you can either specify "[options]" shortcut in a pattern in order not to put all options in that pattern, or you can have all options listed in the pattern--then you can avoid having them in option description.

About repeating program's name (say "naval_fate"), you can do:

    """Usage: prog <bla> ...
              prog <bla> --bla
    """
    args = docopt(__doc__.replace('prog', 'naval_fate'))

One of the early versions of docopt (0.1) was ported to bash: https://github.com/colinta/bocopsh

It should be relatively easy to update it to work with 0.4; if you can make it work with 0.4 it would be great if you make a pull request to the project above.

Quite similar approach. But I think usage-pattern matching is where docopt shines.

You can just change the second line to:

    naval_fate ship move <name> <x> <y> [--speed=<kn>]

to eliminate all the problems you named. Those problems are about specific interface, not docopt.

But I must warn you: Ruby port (as of now) implements only a small subset of docopt language, but we're working on it.

Thanks a lot for the link. Your suggestion will probably make into next version of docopt.

Getopt::Euclid from CPAN is also very similar.

docopt will maybe borrow a few ideas from dreamopts.js :-) Would you like to join forces on [docopt.coffee](https://github.com/docopt/docopt.coffee)?

When the DSL (http://docopt.org/) was designed, the main goal was just to formalise that pattern-language used for decades in man pages and `--help` screens. So variations that are conventional (such as `UPPER-CASE` for arguments or `<angular-brackets>` for arguments) are supported.

I think Clap is good. But you can't beat the readability and succinctness of a DSL (docopt).

Right now we have two full-blown working implementations: - Python - CoffeeScript

We have just started to port to Ruby and Lua. All ports live under `docopt` organization on GitHub: https://github.com/docopt

You are very welcome to help us out with Ruby, Lua, and your favorite language :-).

I'm also a fan of idea of using function-docstrings for separate subcommand help-screens. Problems: (1) exact API, (2) how to do that in non-python implementations. You (and everyone) is very welcome to suggest APIs for that in issues: https://github.com/docopt/docopt/issues

BTW, about bad pitch: maybe :-)

I wanted to improve on presentation, since my last post: http://news.ycombinator.com/submitted?id=halst

docopt is even more terse than 1 line per argument/option/command.

Take an example:

    Usage: quick_example.py tcp <host> <port> [--timeout=<seconds>]
           quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
           quick_example.py -h | --help | --version

2 commands, 3 arguments, 5 options: in only 3 lines of DSL.

Take a look at more examples: https://github.com/docopt/docopt/tree/master/examples

You can already have deeply nested subcommands in docopt, take this example: https://github.com/docopt/docopt/blob/master/examples/git_ex...

Making possible several help-screens for different commands is on it's way. The only stopper—deciding on API: https://github.com/docopt/docopt/issues/17

That exactly what [docopt](http://docopt.org/) is—DSL that allows implement almost any interface in one line (having formal interface description).

I know a tiny bit of Lua. Write me halst@ya.ru or skype "halst." we can discuss your Lua port.

It should be easy to port it - docopt is only 366 LOC itself.

wow, great! what is your scripting language?