docs(readme): update for API change, cleanup
Refs #9.
diff --git a/README.md b/README.md
index 1082b00..d3b5d94 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,23 @@
-docopt.go
+docopt-go
=========
[](https://travis-ci.org/docopt/docopt.go)
-Golang implementation of [docopt](http://docopt.org/) 0.6.1+fix
+An implementation of [docopt](http://docopt.org/) in the
+[Go](http://golang.org/) programming language.
-## Installation
+**docopt** helps you create *beautiful* command-line interfaces easily:
-import "github.com/docopt/docopt-go" and then run `go get`.
-
-## API
-
-``` go
-func docopt.Parse(doc string, argv []string, help bool, version string, optionsFirst bool)
-(args map[string]interface{}, err error)
-```
-
-Parse `argv` based on command-line interface described in `doc`.
-
-docopt creates your command-line interface based on its description that you pass as `doc`. Such description can contain --options, <positional-argument>, commands, which could be [optional], (required), (mutually | exclusive) or repeated...
-
-### arguments
-
-`doc` Description of your command-line interface.
-
-`argv` Argument vector to be parsed. os.Args[1:] is used if nil.
-
-`help` Set to false to disable automatic help on -h or --help options..
-
-`version` If set to something besides an empty string, the string will be printed
- if --version is in argv.
-
-`optionsFirst` Set to true to require options precede positional arguments,
- i.e. to forbid options and positional arguments intermix..
-
-### return values
-
-`args`, map[string]interface{}. A map, where keys are names of command-line elements such as e.g. "--verbose" and "<path>", and values are the parsed values of those elements. interface{} can be `bool`, `int`, `string`, `[]string`.
-
-`err`, error. Either *docopt.LanguageError, *docopt.UserError or nil
-
-## Example
-
-``` go
+```go
package main
import (
- "fmt"
- "github.com/docopt/docopt-go"
+ "fmt"
+ "github.com/docopt/docopt-go"
)
func main() {
-usage := `Naval Fate.
+ usage := `Naval Fate.
Usage:
naval_fate ship new <name>...
@@ -68,15 +34,50 @@
--moored Moored (anchored) mine.
--drifting Drifting mine.`
- arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
- fmt.Println(arguments)
+ arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
+ fmt.Println(arguments)
}
```
+**docopt** parses command-line arguments based on a help message. Don't
+write parser code: a good help message already has all the necessary
+information in it.
+
+## Installation
+
+⚠ Use the alias “docopt-go”. To use docopt in your Go code:
+
+```go
+import "github.com/docopt/docopt-go"
+```
+
+To install docopt according to your `$GOPATH`:
+
+```console
+$ go get github.com/docopt/docopt-go
+```
+
+## API
+
+```go
+func Parse(doc string, argv []string, help bool, version string,
+ optionsFirst bool, exit ...bool) (map[string]interface{}, error)
+```
+Parse `argv` based on the command-line interface described in `doc`.
+
+Given a conventional command-line help message, docopt creates a parser and
+processes the arguments. See
+https://github.com/docopt/docopt#help-message-format for a description of the
+help message format. If `argv` is `nil`, `os.Args[1:]` is used.
+
+docopt returns a map of option names to the values parsed from `argv`, and an
+error or `nil`.
+
## Testing
-All tests from the python version have been implemented and all are passing.
+All tests from the Python version are implemented and passing
+at [Travis CI](https://travis-ci.org/docopt/docopt.go). New
+language-agnostic tests have been added
+to [test_golang.docopt](test_golang.docopt).
-New language agnostic tests have been added to `test_golang.docopt`.
-
-To run them use `go test`.
+To run tests for docopt-go, use `go test`.
diff --git a/docopt.go b/docopt.go
index e513ae5..c44a123 100644
--- a/docopt.go
+++ b/docopt.go
@@ -1,12 +1,14 @@
// Licensed under terms of MIT license (see LICENSE-MIT)
// Copyright (c) 2013 Keith Batten, kbatten@gmail.com
-// Package docopt creates beautiful command-line interfaces based on the
-// command help message
-//
-// Port of docopt for python
-// https://github.com/docopt/docopt
-// http://docopt.org
+/*
+Package docopt parses command-line arguments based on a help message.
+
+⚠ Use the alias “docopt-go”:
+ import "github.com/docopt/docopt-go"
+or
+ $ go get github.com/github/docopt-go
+*/
package docopt
import (
@@ -18,73 +20,28 @@
"unicode"
)
-// Parse `argv` based on command-line interface described in `doc`.
-//
-// docopt creates your command-line interface based on its
-// description that you pass as `doc`. Such description can contain
-// --options, <positional-argument>, commands, which could be
-// [optional], (required), (mutually | exclusive) or repeated...
-//
-// Parameters:
-// doc : string
-// Description of your command-line interface.
-//
-// argv : list of string or nil
-// Argument vector to be parsed. os.Args[1:] is used if nil.
-//
-// help : bool (default: true)
-// Set to false to disable automatic help on -h or --help options.
-//
-// version : string
-// If set to something besides an empty string, the string will be printed
-// if --version is in argv
-//
-// optionsFirst : bool (default: false)
-// Set to true to require options precede positional arguments,
-// i.e. to forbid options and positional arguments intermix.
-//
-// Returns:
-// args : map[string]interface{}
-// A map, where keys are names of command-line elements
-// such as e.g. "--verbose" and "<path>", and values are the
-// parsed values of those elements.
-//
-// err : error, *docopt.LanguageError, *docopt.UserError
-//
-// os.Exit on user error or help
-//
-// Example:
-// package main
-//
-// import (
-// "fmt"
-// "github.com/docopt/docopt-go"
-// )
-//
-// func main() {
-// doc := `
-// Usage:
-// my_program tcp <host> <port> [--timeout=<seconds>]
-// my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
-// my_program (-h | --help | --version)
-//
-// Options:
-// -h, --help Show this screen and exit.
-// --baud=<n> Baudrate [default: 9600]
-// `
-// argv := []string{"tcp", "127.0.0.1", "80", "--timeout", "30"}
-// fmt.Println(docopt.Parse(doc, argv, true, "", false))
-// }
-//
-// Example output:
-// {"--baud": "9600",
-// "--help": false,
-// "--timeout": "30",
-// "--version": false,
-// "<host>": "127.0.0.1",
-// "<port>": "8"',
-// "serial": false,
-// "tcp": true}
+/*
+Parse `argv` based on the command-line interface described in `doc`.
+
+Given a conventional command-line help message, docopt creates a parser and
+processes the arguments. See
+https://github.com/docopt/docopt#help-message-format for a description of the
+help message format. If `argv` is `nil`, `os.Args[1:]` is used.
+
+docopt returns a map of option names to the values parsed from `argv`, and an
+error or `nil`.
+
+Set `help` to `false` to disable automatic help messages on `-h` or `--help`.
+If `version` is a non-empty string, it will be printed when `--version` is
+specified. Set `optionsFirst` to `true` to require that options always come
+before positional arguments; otherwise they can overlap.
+
+By default, docopt calls `os.Exit(0)` if it handled a built-in option such as
+`-h` or `--version`. If the user errored with a wrong command or options,
+docopt exits with a return code of 1. To stop docopt from calling `os.Exit()`
+and to handle your own return codes, pass an optional last parameter of `false`
+for `exit`.
+*/
func Parse(doc string, argv []string, help bool, version string,
optionsFirst bool, exit ...bool) (map[string]interface{}, error) {
// if "false" was the (optional) last arg, don't call os.Exit()
@@ -94,11 +51,13 @@
}
args, output, err := parse(doc, argv, help, version, optionsFirst)
if _, ok := err.(*UserError); ok {
+ // the user gave us bad input
fmt.Println(output)
if exitOk {
os.Exit(1)
}
} else if len(output) > 0 && err == nil {
+ // the user asked for help or `--version`
fmt.Println(output)
if exitOk {
os.Exit(0)
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 0000000..b87a149
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,37 @@
+package docopt
+
+import (
+ "fmt"
+ "sort"
+)
+
+func ExampleParse() {
+ usage := `Usage:
+ config_example tcp [<host>] [--force] [--timeout=<seconds>]
+ config_example serial <port> [--baud=<rate>] [--timeout=<seconds>]
+ config_example -h | --help | --version`
+ // parse the command line `comfig_example tcp 127.0.0.1 --force`
+ argv := []string{"tcp", "127.0.0.1", "--force"}
+ arguments, _ := Parse(usage, argv, true, "0.1.1rc", false)
+ // sort the keys of the arguments map
+ var keys []string
+ for k := range arguments {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ // print the argument keys and values
+ for _, k := range keys {
+ fmt.Printf("%9s %v\n", k, arguments[k])
+ }
+ // output:
+ // --baud <nil>
+ // --force true
+ // --help false
+ // --timeout <nil>
+ // --version false
+ // -h false
+ // <host> 127.0.0.1
+ // <port> <nil>
+ // serial false
+ // tcp true
+}
