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<T, docopt::Error>`. 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.
Merge pull request #5 from alexcrichton/parse-without-failing

Push failure to consumers instead of built-in
Cleaning up a few straggling errors from API change.
Hide the parser method. Only exposed for the macro.
expand_expr -> expander().fold_expr
Update examples in README.
Version sync with docopt.
Add in required error implementation.

This doesn't do anything, but at least docopt.rs can compile.

Fixes #9.
Merge pull request #10 from steveklabnik/fix_error

Add in required error implementation.
Update examples to exit better.
w00t. Proper application level error handling has landed!
Merge branch 'master' of github.com:docopt/docopt.rs
I goofed the merge.
Split examples so 'cargo test' works.

Fixes #11.
Update the README.

Fixing the Travis link to go to the correct repository.
Changing the filetype referenced as well.
Merge pull request #12 from leighlondon/update-travis-link

Update the README.
Rust is now supported on Travis CI!
Fix build break due to generalized type parameter bounds
docopt_macros: fix build break due to generalized object bounds
Merge pull request #15 from bkoropoff/fix-lifetimes

Fix build break due to generalized type parameter bounds