docopt

README

docopt-go

An implementation of docopt in the Go programming language.

docopt helps you create beautiful command-line interfaces easily:

package main

import (
	"fmt"
	"github.com/docopt/docopt-go"
)

func main() {
	  usage := `Naval Fate.

Usage:
  naval_fate ship new <name>...
  naval_fate ship <name> move <x> <y> [--speed=<kn>]
  naval_fate ship shoot <x> <y>
  naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate -h | --help
  naval_fate --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.`

	  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:

import "github.com/docopt/docopt-go"

To install docopt according to your $GOPATH:

$ go get github.com/docopt/docopt-go

API

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.

More documentation for docopt is available at GoDoc.org.

Testing

All tests from the Python version are implemented and passing at Travis CI. New language-agnostic tests have been added to test_golang.docopt.

To run tests for docopt-go, use go test.

Documentation

Overview

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/docopt/docopt-go

Index

• func Merge(dst interface{}, src map[string]interface{}) error
• func Parse(doc string, argv []string, help bool, version string, optionsFirst bool, ...) (map[string]interface{}, error)
• type LanguageError
  • func (e LanguageError) Error() string
• type Merger
• type UserError
  • func (e UserError) Error() string

Examples

• Parse

Functions

func Merge

func Merge(dst interface{}, src map[string]interface{}) error

Merge the results of a previous Parse into `dst` using Go reflection.

Given a pointer to a structure, `dst`, and a the results of a previous Parse, `src`, docopt will merge values from `src` into the fields of `dst`. Each public field in `dst` is examined using Go's `reflect` package and updated unless it has been tagged `docopt:"-"`.

Merge selects a value from `src` for each field in `dst`, based on the following:

- If the field is private, it is skipped. (Go reflection won't indicate it exists, anyway.)

- If the docopt tag is "-", it is skipped.

- If the field has an all uppercase name, it will be updated; e.g. `FILES` will use `src["FILES"]`

- If there is a docopt tag, it is used as the key for `dst`; e.g. `docopt:"-d"` will use `src["-d"]`

- Otherwise, docopt will ignore the field.

Given a value selected from `src` based on the rules above, Merge will update the field based on the field's type. If the type is not supported, Merge will panic, unless it has been bypassed using the `docopt:"-"` tag. The following field types are currently supported:

- Integers and Floating Point numbers are parsed using `encoding/json` and updated.

- Boolean fields are updated based on the presence or absence of a flag.

- Strings are updated with the value provided by dst.

- Slices of any of the previous types will be updated with the values found in dst.

- Merger implementations will be permitted to Merge themselves. (Slices of Mergers are not currently supported.)

The following example defines bindings for `-j`, `-w` and `-n` flags, and accepts zero or more URL values:

var opt struct {
	Home 	  string `docopt:"-"`  // not updated by Merge
	JsonInput bool   `docopt:"-j"`
	WriteFile string `docopt:"-w"`
	N         int    `docopt:"-n"`
	URL       []string
}

If a value in `dst` does not have a field associated with it in `src`, it is silently ignored. However, if a field in `dst` does not have a corresponding value in `src`, a panic is produced, since the type is no longer consistent with the documented command line interface.

func Parse

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`.

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`.

Example

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

Types

type LanguageError

type LanguageError struct {
	// contains filtered or unexported fields
}

LanguageError records an error with the doc string.

func (LanguageError) Error

func (e LanguageError) Error() string

type Merger

type Merger interface {
	MergeDocopt(v interface{}) error
}

Merger indicates fields that know how to merge a docopt flag or argument value for Merge.

Implementations of Merger should generally use pointer or slice types as the recipient, so they can update themselves with the provided value.

Example:

// Base16 is a hexadecimal encoded string
type Base16 string
...
func (b16 *Base16) MergeDocopt(v interface{}) error {
	str, ok := v.(string)
	if !ok {
		return fmt.Errorf("expected base16 string, got %v", v)
	}
	p, err = hex.DecodeString(str)
	*b16 = string(p)
	return err
}

type UserError

type UserError struct {
	Usage string
	// contains filtered or unexported fields
}

UserError records an error with program arguments.

func (UserError) Error

func (e UserError) Error() string