commander

README

go-commander

The exported functions could change at any time before the first stable release(>=1.0.0).

The solution for Go command-line interfaces, drive by <docopt>, inspired by <commander>

Installation

To use commander in your Go code:

import "github.com/WindomZ/go-commander"

To install commander according to your $GOPATH:

go get github.com/WindomZ/go-commander

Examples

Quick example

Such as the following help message

Usage:
  quick_example tcp <host> <port> [--timeout=<seconds>]
  quick_example serial <port> [--baud=9600] [--timeout=<seconds>]
  quick_example -h | --help
  quick_example --version

To coding with go-commander just like this:

import "github.com/WindomZ/go-commander"

// quick_example
commander.Program.
	Command("quick_example").
	Version("0.1.1rc")

// quick_example tcp <host> <port> [--timeout=<seconds>]
commander.Program.
	Command("tcp <host> <port>").
	Option("--timeout=<seconds>")

// quick_example serial <port> [--baud=9600] [--timeout=<seconds>]
commander.Program.
	Command("serial <port>").
	Option("--baud=9600").
	Option("--timeout=<seconds>")

Counted example

Such as the following help message

Usage:
  counted_example [-v...]
  counted_example go [go]
  counted_example (--path=<path>)...
  counted_example <file> <file>
  counted_example -h | --help
  counted_example --version

To coding with go-commander just like this:

import "github.com/WindomZ/go-commander"

// counted_example -v...
commander.Program.
	Command("counted_example").
	Option("-v...")

// counted_example go [go]
commander.Program.
	Command("go [go]")

// counted_example (--path=<path>)...
commander.Program.
	LineOption("(--path=<path>)...")

// counted_example <file> <file>
commander.Program.
	LineArgument("<file> <file>")

Calculator example

Such as the following help message

Simple calculator example

Usage:
  calculator_example <value> ( ( + | - | * | / ) <value> )...
  calculator_example <function> <value> [( , <value> )]...
  calculator_example -h | --help
  calculator_example --version

Examples:
  calculator_example 1 + 2 + 3 + 4 + 5
  calculator_example 1 + 2 '*' 3 / 4 - 5    # note quotes around '*'
  calculator_example sum 10 , 20 , 30 , 40

To coding with go-commander just like this:

import "github.com/WindomZ/go-commander"

// calculator_example
commander.Program.
	Command("calculator_example").
	Version("0.0.1").
	Description("Simple calculator example")

// calculator_example <value> ( ( + | - | * | / ) <value> )...
commander.Program.
	LineArgument("<value> ( ( + | - | * | / ) <value> )...").
	Action(func(c commander.Context) error {
		if c.Contain("<function>") {
			return nil
		}
		var result int
		values := c.Doc.GetStrings("<value>")
		for index, value := range values {
			if i, err := strconv.Atoi(value); err != nil {
			} else if index == 0 {
				result = i
			} else {
				switch c.Args.Get(index*2 - 1) {
				case "+":
					result += i
				case "-":
					result -= i
				case "*":
					result *= i
				case "/":
					result /= i
				}
			}
		}
		fmt.Println(c.Args.String(), "=", result)
		return nil
	})

// calculator_example <function> <value> [( , <value> )]...
commander.Program.
	LineArgument("<function> <value> [( , <value> )]...").
	Action(func(c commander.Context) error {
		var result int
		switch c.Doc.GetString("<function>") {
		case "sum":
			values := c.Doc.GetStrings("<value>")
			for _, value := range values {
				if i, err := strconv.Atoi(value); err == nil {
					result += i
				}
			}
		}
		fmt.Println(c.Args.String(), "=", result)
		return nil
	})

// Examples: ...
commander.Program.
	Annotation(
		"Examples",
		[]string{
			"calculator_example 1 + 2 + 3 + 4 + 5",
			"calculator_example 1 + 2 '*' 3 / 4 - 5    # note quotes around '*'",
			"calculator_example sum 10 , 20 , 30 , 40",
		},
	)

Get the terminal output:

calculator_example 1 + 2 + 3 + 4 + 5
# output: 15

calculator_example 1 + 2 '*' 3 / 4 - 5
# output: -3

calculator_example sum 10 , 20 , 30 , 40
# output: 100

License

The MIT License

Documentation

Index

• Variables
• type Action
• type ActionNative
• type ActionNativeDocopt
• type ActionNativeSimple
• type ActionNormal
• type ActionSimple
• type Commander
• type Context
• type DocoptMap
  • func Parse(doc string, argv []string, help bool, version string, optionsFirst bool, ...) (DocoptMap, error)
  • func (d DocoptMap) Contain(key string) bool
  • func (d DocoptMap) Get(key string) interface{}
  • func (d DocoptMap) GetBool(key string) bool
  • func (d DocoptMap) GetFloat(key string) (float32, bool)
  • func (d DocoptMap) GetFloat64(key string) (float64, bool)
  • func (d DocoptMap) GetInt(key string) (int, bool)
  • func (d DocoptMap) GetInt64(key string) (int64, bool)
  • func (d DocoptMap) GetString(key string) string
  • func (d DocoptMap) GetStrings(key string) []string
  • func (d DocoptMap) Map() map[string]interface{}
  • func (d DocoptMap) String() string
• type ErrFunc
• type GoCommander
• type Result
  • func NewResult(text string) Result
  • func NewResultCode(code int, text ...string) Result
  • func NewResultError(err error, codes ...int) Result
• type ResultCode
  • func (e ResultCode) Break() bool
  • func (e ResultCode) Code() int
  • func (e ResultCode) Error() error
  • func (e ResultCode) ErrorString() string

Variables

var (
	ErrNil     error = errors.New("error nil")
	ErrCommand       = errors.New("error command")
	ErrOption        = errors.New("error option")
)

Types

type Action

type Action func(c Context) Result // default internal function

The following are ACTION functions, chose one if you like it.

type ActionNative

type ActionNative func()

The following are ACTION functions, chose one if you like it.

type ActionNativeDocopt

type ActionNativeDocopt func(m map[string]interface{}) error

The following are ACTION functions, chose one if you like it.

type ActionNativeSimple

type ActionNativeSimple func() error

The following are ACTION functions, chose one if you like it.

type ActionNormal

type ActionNormal func(c Context) error

The following are ACTION functions, chose one if you like it.

type ActionSimple

type ActionSimple func(c Context)

The following are ACTION functions, chose one if you like it.

type Commander

type Commander interface {
	Version(ver string) Commander
	Description(desc string) Commander
	Annotation(title string, contents []string) Commander
	Action(action interface{}, keys ...[]string) Commander
	Command(usage string, args ...interface{}) Commander
	Option(usage string, args ...interface{}) Commander
	LineArgument(usage string, args ...interface{}) Commander
	LineOption(usage string, args ...interface{}) Commander
	UsagesString() []string
	OptionsString() []string
	HelpMessage() string
	ShowHelpMessage() string
	Parse(argv ...[]string) (Context, error)
}

Commander Command line implementation

type Context

type Context interface {
	// _ContextArguments
	GetArg(index int) string
	ArgsString() string
	ArgsStringSeparator(sep string, offsets ...int) string
	// DocoptMap
	Map() map[string]interface{}
	Get(key string) interface{}
	Contain(key string) bool
	GetString(key string) string
	GetStrings(key string) []string
	GetBool(key string) bool
	GetInt64(key string) (int64, bool)
	GetInt(key string) (int, bool)
	GetFloat64(key string) (float64, bool)
	GetFloat(key string) (float32, bool)
	String() string
}

type DocoptMap

type DocoptMap map[string]interface{}

DocoptMap docopt returns a map of option names to the values

func Parse

func Parse(doc string, argv []string, help bool, version string,
	optionsFirst bool, exit ...bool) (DocoptMap, error)

func (DocoptMap) Contain

func (d DocoptMap) Contain(key string) bool

func (DocoptMap) Get

func (d DocoptMap) Get(key string) interface{}

func (DocoptMap) GetBool

func (d DocoptMap) GetBool(key string) bool

func (DocoptMap) GetFloat

func (d DocoptMap) GetFloat(key string) (float32, bool)

func (DocoptMap) GetFloat64

func (d DocoptMap) GetFloat64(key string) (float64, bool)

func (DocoptMap) GetInt

func (d DocoptMap) GetInt(key string) (int, bool)

func (DocoptMap) GetInt64

func (d DocoptMap) GetInt64(key string) (int64, bool)

func (DocoptMap) GetString

func (d DocoptMap) GetString(key string) string

func (DocoptMap) GetStrings

func (d DocoptMap) GetStrings(key string) []string

func (DocoptMap) Map

func (d DocoptMap) Map() map[string]interface{}

func (DocoptMap) String

func (d DocoptMap) String() string

type ErrFunc

type ErrFunc func(err error, obj interface{})

type GoCommander

type GoCommander interface {
	Commander
	Context
}

var Program GoCommander = newProgram()

type Result

type Result interface {
	Code() int
	Error() error
	ErrorString() string
	Break() bool
}

var (
	ResultPass  Result = &ResultCode{}
	ResultBreak        = &ResultCode{_break: true}
)

func NewResult

func NewResult(text string) Result

func NewResultCode

func NewResultCode(code int, text ...string) Result

func NewResultError

func NewResultError(err error, codes ...int) Result

type ResultCode

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

func (ResultCode) Break

func (e ResultCode) Break() bool

func (ResultCode) Code

func (e ResultCode) Code() int

func (ResultCode) Error

func (e ResultCode) Error() error

func (ResultCode) ErrorString

func (e ResultCode) ErrorString() string