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 Parse(doc string, argv []string, help bool, version string, optionsFirst bool, ...) (map[string]interface{}, error)
• type LanguageError
  • func (e LanguageError) Error() string
• type UserError
  • func (e UserError) Error() string

Examples

• Parse

Functions

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