Refactor and API improvements

aviddiviner commented 7 years ago

Hi there. I've been working on my own fork of this project for a while to clean up the API. I've reached a stage where I'm happy for my changes to be merged back in if you're interested in using them. You can see what's basically changed by reading the README: https://github.com/aviddiviner/docopt-go#api

But I'll list the salient points here for your summary:

Instead of the previous single, all-purpose API exposed by this package, namely: Parse(doc string, argv []string, help bool, version string, optionsFirst bool, exit ...bool) (map[string]interface{}, error), I've added two simpler APIs, such as ParseDoc(doc string) (Opts, error), as well as a custom Parser that you can use.
I have left the Parse(...) function in place (using a new Parser under the hood), so there is no break in backward compatibility.
This configurable Parser was the reason I did this refactor; previously there was no way for me to unit test my own docopt docs (i.e. test some command line invocations and see that I was getting the correct options back). With the addition of the parser, you can control the usage printing / exit behaviour.

The new Opts type which is returned has some convenience methods for easy type conversion, so this code:

opts, _ := Parse("Usage: foo <option>", nil, true, "", false, true)
if opt, ok := opts["<option>"]; ok {
if s, ok := opt.(string); ok {
if val, err := strconv.Atoi(s); err != nil {
  ...
}
}
}

becomes this:

opts, _ := ParseDoc("Usage: foo <option>")
val, _ := opts.Int("<option>")

while still being just a map[string]interface{} under the hood.

The examples in the examples/ folder are now tested as part of the build process. Some other small coverage improvements were made.

And some other little fixes here and there. But mostly, it's about having a cleaner API, and being able to control the "exit and print usage" behaviour for testing.

Take a look. I hope you like it, and would want to merge it back in! Let me know 😄

aviddiviner commented 7 years ago

Oh, and I fixed the broken Travis build and all of that. The build for this PR will fail, because the examples all reference the new APIs at github.com/docopt/docopt-go (which aren't there yet). Take a look on my repo to see the build passing.

aviddiviner commented 7 years ago

I've added in a Bind API, which allows you to bind to a struct, assigning option values to the exported fields of that struct, all at once.

var config struct {
  Command string `docopt:"<cmd>"`
  Tries   int    `docopt:"-n"`
  Force   bool   // Gets the value of --force
}
opts.Bind(&config)

aviddiviner commented 7 years ago

By my count, this PR fixes these issues: https://github.com/docopt/docopt.go/issues/3, https://github.com/docopt/docopt.go/issues/4, https://github.com/docopt/docopt.go/issues/17, https://github.com/docopt/docopt.go/issues/31, https://github.com/docopt/docopt.go/issues/39

And provides the features requested by these PRs: https://github.com/docopt/docopt.go/pull/20, https://github.com/docopt/docopt.go/pull/30, https://github.com/docopt/docopt.go/pull/42

mboersma commented 6 years ago

@aviddiviner obviously this fell completely through the cracks--what can I say when something is ignored for over a year, other than I'm so sorry your good work was ignored.

I'm trying to rejuvanate interest and improve the health of docopt and docopt.go because I think @keleshev's idea is still brilliant. If you would be willing to revisit your improvements and rebase them against master, I promise they will not be ignored now.