docopt API about docopt.rs

[BurntSushi]

@jjpe I must admit, this is a bit of an odd request. The API is experimental with respect to designing an idiomatic Rust interface to Docopt. argparse is an entirely different beast. I've used argparse extensively over the past several years (I still do), and it's a great library. But Docopt is a fundamentally different (read: not better, not worse) way of solving the problem of parsing command line arguments. Not everyone likes generating a parser from a usage string. That's OK. Personally, I think both approaches have merit, but I am enjoying Docopt.

With that said, could you expand on what you meant by, "the current Docopt API feels a bit lacking?" Are you saying that you don't like the idea of generating a parser from a usage string? If so, then I think you're rejecting the fundamental premise of Docopt (which is OK!). Or are you saying that there are features supported by argparse that aren't supported by Docopt? If so, which ones? Maybe I can help you figure something out.

For what it's worth, the experimental aspect of the API is about balancing three distinct approaches:

1. The traditional route that the reference Docopt implementation supports. A successful parse gives you a hash map.
2. A successful parse can be decoded into a Rust struct. (But this requires you to duplicate the flags/arguments. Once in the usage string and another in the struct.)
3. The struct can be generated for you from the usage string through the docopt! macro. This is extremely convenient, preserves a single point of truth and type safety. The downside is that it is very magical.

Figuring out how to balance these things is the design challenge IMO. It's assumed that if you're using this library, then you buy into the Docopt idea.

[jjpe]

I'm not arguing against the model of generating a parser. It's merely the syntax that bothers me. It feels like a lot of incidental complexity API-wise and really counter-intuitive. As a result I constantly need to look things up. This is also what I mean by "lacking", I have found no lack in features as such.

As a concrete example of what I mean: someone who wants to parse CLI args shouldn't have to care about what Decoder is or does. This is mandated by the current setup (and I get the whole separation of concerns idea behind it) but conceptually it is superfluous and therefore I'd rather not deal with it.

[BurntSushi]

I am deeply confused by your comments. Your first comment talked about argparse and asked me to look into it. I'm familiar with the library. So what did you want to point out about it?

It's merely the syntax that bothers me. It feels like a lot of incidental complexity API-wise and really counter-intuitive.

Which syntax? Could you please give concrete examples. Are you talking about the Docopt syntax? Rust syntax? The docopt! macro?

someone who wants to parse CLI args shouldn't have to care about what Decoder is or does

If you're using the docopt! macro, then the Decoder is entirely opaque.

Otherwise, a successful parse of Docopt, by definition, produces a map from argument/command/flag to value. The Decoder stuff built on top of that is meant to provide 1) more convenience in a statically typed language and 2) some level of data validation.

@jjpe Could you please provide more specific details? Ideally, you could include some code to help you demonstrate. As it is, I can honestly say that I have no idea what you're talking about. :-(

[BurntSushi]

I'm going to close this since OP hasn't responded. Moreover, the API underwent several changes, including switching to the "builder" pattern. As a result, the surface of the API has become a bit smaller.

@jjpe I'd be very happy to entertain feedback/criticism, but please include some code samples so that I know what you're talking about. :-)