Skip to content

Commit 326192f

Browse files
mboersmamboersma
committed
docs(readme): update for API change, cleanup
Refs #9.
1 parent 3fc770e commit 326192f

File tree

3 files changed

+118
-121
lines changed

3 files changed

+118
-121
lines changed

‎README.md

Lines changed: 49 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,23 @@
1-
docopt.go
1+
docopt-go
22
=========
33

44
[![Build Status](https://travis-ci.org/docopt/docopt.go.svg?branch=master)](https://travis-ci.org/docopt/docopt.go)
55

6-
Golang implementation of [docopt](http://docopt.org/) 0.6.1+fix
6+
An implementation of [docopt](http://docopt.org/) in the
7+
[Go](http://golang.org/) programming language.
78

8-
## Installation
9-
10-
import "github.com/docopt/docopt-go" and then run `go get`.
11-
12-
## API
13-
14-
``` go
15-
func docopt.Parse(doc string, argv []string, help bool, version string, optionsFirst bool)
16-
(args map[string]interface{}, err error)
17-
```
18-
19-
Parse `argv` based on command-line interface described in `doc`.
20-
21-
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...
22-
23-
### arguments
24-
25-
`doc` Description of your command-line interface.
26-
27-
`argv` Argument vector to be parsed. os.Args[1:] is used if nil.
28-
29-
`help` Set to false to disable automatic help on -h or --help options..
30-
31-
`version` If set to something besides an empty string, the string will be printed
32-
if --version is in argv.
33-
34-
`optionsFirst` Set to true to require options precede positional arguments,
35-
i.e. to forbid options and positional arguments intermix..
36-
37-
### return values
38-
39-
`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`.
40-
41-
`err`, error. Either *docopt.LanguageError, *docopt.UserError or nil
9+
**docopt** helps you create *beautiful* command-line interfaces easily:
4210

43-
## Example
44-
45-
``` go
11+
```go
4612
package main
4713

4814
import (
49-
"fmt"
50-
"github.com/docopt/docopt-go"
15+
"fmt"
16+
"github.com/docopt/docopt-go"
5117
)
5218

5319
func main() {
54-
usage := `Naval Fate.
20+
usage := `Naval Fate.
5521
5622
Usage:
5723
naval_fate ship new <name>...
@@ -68,15 +34,50 @@ Options:
6834
--moored Moored (anchored) mine.
6935
--drifting Drifting mine.`
7036

71-
arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
72-
fmt.Println(arguments)
37+
arguments, _ := docopt.Parse(usage, nil, true, "Naval Fate 2.0", false)
38+
fmt.Println(arguments)
7339
}
7440
```
7541

76-
## Testing
42+
**docopt** parses command-line arguments based on a help message. Don't
43+
write parser code: a good help message already has all the necessary
44+
information in it.
45+
46+
## Installation
47+
48+
⚠ Use the alias “docopt-go”. To use docopt in your Go code:
7749

78-
All tests from the python version have been implemented and all are passing.
50+
```go
51+
import "github.com/docopt/docopt-go"
52+
```
53+
54+
To install docopt according to your `$GOPATH`:
55+
56+
```console
57+
$ go get github.com/docopt/docopt-go
58+
```
59+
60+
## API
61+
62+
```go
63+
func Parse(doc string, argv []string, help bool, version string,
64+
optionsFirst bool, exit ...bool) (map[string]interface{}, error)
65+
```
66+
Parse `argv` based on the command-line interface described in `doc`.
67+
68+
Given a conventional command-line help message, docopt creates a parser and
69+
processes the arguments. See
70+
https://github.com/docopt/docopt#help-message-format for a description of the
71+
help message format. If `argv` is `nil`, `os.Args[1:]` is used.
72+
73+
docopt returns a map of option names to the values parsed from `argv`, and an
74+
error or `nil`.
75+
76+
## Testing
7977

80-
New language agnostic tests have been added to `test_golang.docopt`.
78+
All tests from the Python version are implemented and passing
79+
at [Travis CI](https://travis-ci.org/docopt/docopt.go). New
80+
language-agnostic tests have been added
81+
to [test_golang.docopt](test_golang.docopt).
8182

82-
To run them use `go test`.
83+
To run tests for docopt-go, use `go test`.

‎docopt.go

Lines changed: 32 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
// Licensed under terms of MIT license (see LICENSE-MIT)
22
// Copyright (c) 2013 Keith Batten, kbatten@gmail.com
33

4-
// Package docopt creates beautiful command-line interfaces based on the
5-
// command help message
6-
//
7-
// Port of docopt for python
8-
// https://github.com/docopt/docopt
9-
// http://docopt.org
4+
/*
5+
Package docopt parses command-line arguments based on a help message.
6+
7+
⚠ Use the alias “docopt-go”:
8+
import "github.com/docopt/docopt-go"
9+
or
10+
$ go get github.com/github/docopt-go
11+
*/
1012
package docopt
1113

1214
import (
@@ -18,73 +20,28 @@ import (
1820
"unicode"
1921
)
2022

21-
// Parse `argv` based on command-line interface described in `doc`.
22-
//
23-
// docopt creates your command-line interface based on its
24-
// description that you pass as `doc`. Such description can contain
25-
// --options, <positional-argument>, commands, which could be
26-
// [optional], (required), (mutually | exclusive) or repeated...
27-
//
28-
// Parameters:
29-
// doc : string
30-
// Description of your command-line interface.
31-
//
32-
// argv : list of string or nil
33-
// Argument vector to be parsed. os.Args[1:] is used if nil.
34-
//
35-
// help : bool (default: true)
36-
// Set to false to disable automatic help on -h or --help options.
37-
//
38-
// version : string
39-
// If set to something besides an empty string, the string will be printed
40-
// if --version is in argv
41-
//
42-
// optionsFirst : bool (default: false)
43-
// Set to true to require options precede positional arguments,
44-
// i.e. to forbid options and positional arguments intermix.
45-
//
46-
// Returns:
47-
// args : map[string]interface{}
48-
// A map, where keys are names of command-line elements
49-
// such as e.g. "--verbose" and "<path>", and values are the
50-
// parsed values of those elements.
51-
//
52-
// err : error, *docopt.LanguageError, *docopt.UserError
53-
//
54-
// os.Exit on user error or help
55-
//
56-
// Example:
57-
// package main
58-
//
59-
// import (
60-
// "fmt"
61-
// "github.com/docopt/docopt-go"
62-
// )
63-
//
64-
// func main() {
65-
// doc := `
66-
// Usage:
67-
// my_program tcp <host> <port> [--timeout=<seconds>]
68-
// my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
69-
// my_program (-h | --help | --version)
70-
//
71-
// Options:
72-
// -h, --help Show this screen and exit.
73-
// --baud=<n> Baudrate [default: 9600]
74-
// `
75-
// argv := []string{"tcp", "127.0.0.1", "80", "--timeout", "30"}
76-
// fmt.Println(docopt.Parse(doc, argv, true, "", false))
77-
// }
78-
//
79-
// Example output:
80-
// {"--baud": "9600",
81-
// "--help": false,
82-
// "--timeout": "30",
83-
// "--version": false,
84-
// "<host>": "127.0.0.1",
85-
// "<port>": "8"',
86-
// "serial": false,
87-
// "tcp": true}
23+
/*
24+
Parse `argv` based on the command-line interface described in `doc`.
25+
26+
Given a conventional command-line help message, docopt creates a parser and
27+
processes the arguments. See
28+
https://github.com/docopt/docopt#help-message-format for a description of the
29+
help message format. If `argv` is `nil`, `os.Args[1:]` is used.
30+
31+
docopt returns a map of option names to the values parsed from `argv`, and an
32+
error or `nil`.
33+
34+
Set `help` to `false` to disable automatic help messages on `-h` or `--help`.
35+
If `version` is a non-empty string, it will be printed when `--version` is
36+
specified. Set `optionsFirst` to `true` to require that options always come
37+
before positional arguments; otherwise they can overlap.
38+
39+
By default, docopt calls `os.Exit(0)` if it handled a built-in option such as
40+
`-h` or `--version`. If the user errored with a wrong command or options,
41+
docopt exits with a return code of 1. To stop docopt from calling `os.Exit()`
42+
and to handle your own return codes, pass an optional last parameter of `false`
43+
for `exit`.
44+
*/
8845
func Parse(doc string, argv []string, help bool, version string,
8946
optionsFirst bool, exit ...bool) (map[string]interface{}, error) {
9047
// if "false" was the (optional) last arg, don't call os.Exit()
@@ -94,11 +51,13 @@ func Parse(doc string, argv []string, help bool, version string,
9451
}
9552
args, output, err := parse(doc, argv, help, version, optionsFirst)
9653
if _, ok := err.(*UserError); ok {
54+
// the user gave us bad input
9755
fmt.Println(output)
9856
if exitOk {
9957
os.Exit(1)
10058
}
10159
} else if len(output) > 0 && err == nil {
60+
// the user asked for help or `--version`
10261
fmt.Println(output)
10362
if exitOk {
10463
os.Exit(0)

‎example_test.go

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
package docopt
2+
3+
import (
4+
"fmt"
5+
"sort"
6+
)
7+
8+
func ExampleParse() {
9+
usage := `Usage:
10+
config_example tcp [<host>] [--force] [--timeout=<seconds>]
11+
config_example serial <port> [--baud=<rate>] [--timeout=<seconds>]
12+
config_example -h | --help | --version`
13+
// parse the command line `comfig_example tcp 127.0.0.1 --force`
14+
argv := []string{"tcp", "127.0.0.1", "--force"}
15+
arguments, _ := Parse(usage, argv, true, "0.1.1rc", false)
16+
// sort the keys of the arguments map
17+
var keys []string
18+
for k := range arguments {
19+
keys = append(keys, k)
20+
}
21+
sort.Strings(keys)
22+
// print the argument keys and values
23+
for _, k := range keys {
24+
fmt.Printf("%9s %v\n", k, arguments[k])
25+
}
26+
// output:
27+
// --baud <nil>
28+
// --force true
29+
// --help false
30+
// --timeout <nil>
31+
// --version false
32+
// -h false
33+
// <host> 127.0.0.1
34+
// <port> <nil>
35+
// serial false
36+
// tcp true
37+
}

0 commit comments

Comments
 (0)