BurntSushi/docopt.rs — pull request #5 by alexcrichton (2014-07-25 21:22:37+00:00)
Title: Push failure to consumers instead of built-in

Currently it does not appear to be a way to parse a structure defined by the
docopt! macro without failing the task on error. it is possible to parse without
failing using the `Docopt` structure, but this require the documentation string
which would otherwise have to be duplicated. Going down the rabbit hole ends up
meaning that most "convenient" functionality is all tied up with failure.

This commit alters top-level `docopt*` functions and the `FlagParser` functions
to all return `Result`. The `Error` type was enhanced with a
few new variants:

* Help - indicates that the "error" is that the specified help message should be
printed
* Version - indicates that the program should immediately print the version and
exit
* WithProgramUsage - indicates that the specified error caused parsing/decoding
to fail and that the usage string should be printed
afterwards.

With this, the new version of a succinct example is:

```
let args: Args = match docopt::docopt(doc) {
Ok(args) => args,
Err(e) => e.exit(),
};
```

I'm unsure if this is the best design for a change such as this. Results are
tempting to `unwrap` if you don't care about the error value within, but there
are some error variants that shouldn't cause the program to fail with an invalid
exit code.