commander

README

go-commander

The solution for building command shell programs, drive by <docopt>, inspired by <commander.js>

Features

• Has all the features of docopt.
• Usage like commander.js as simple and readable.
• Automatic generated a help message, easy to use, or advanced usage see documents of docopt.
• Automatically execute the correct action function, don't worry about conflict.
• Can customize the action function, better with context.
• Code colloquial use, from top to bottom.

Installation

To get the package, execute:

go get gopkg.in/WindomZ/go-commander.v1

To import this package, add the following line to your code:

import "gopkg.in/WindomZ/go-commander.v1"

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

Options:
  -h --help     output usage information
  -v --version  output the version number

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>").
	Action(func() {
		fmt.Printf("tcp %s %s %s\n",
			commander.Program.MustString("<host>"),
			commander.Program.MustString("<port>"),
			commander.Program.MustString("--timeout"),
		)
	})

// quick_example serial <port> [--baud=9600] [--timeout=<seconds>]
commander.Program.
	Command("serial <port>").
	Option("--baud=9600").
	Option("--timeout=<seconds>").
	Action(func() {
		fmt.Printf("serial %s %s %s\n",
			commander.Program.MustString("<port>"),
			commander.Program.MustString("--baud"),
			commander.Program.MustString("--timeout"),
		)
	})

commander.Program.Parse()

Get the terminal output:

$ quick_example --version
# output: 0.1.1rc

$ quick_example tcp 127.0.0.1 1080 --timeout=110
# output: tcp 127.0.0.1 1080 110

$ quick_example serial 80 --baud=5800 --timeout=120
# output: serial 80 5800 120

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

Options:
  -h --help     output usage information
  -v --version  output the version number

To coding with go-commander just like this:

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

// counted_example -v...
commander.Program.
	Command("counted_example").
	Option("-v...", "", func(c commander.Context) {
		fmt.Println("-v =", c.Get("-v"))
	})

// counted_example go [go]
commander.Program.
	Command("go [go]").
	Action(func(c commander.Context) {
		fmt.Println("go =", c.Get("go"))
	})

// counted_example (--path=<path>)...
commander.Program.
	Command("(--path=<path>)...", "", func(c commander.Context) {
		fmt.Printf("--path = %q\n",
			c.MustStrings("--path"))
	})

// counted_example <file> <file>
commander.Program.
	Command("<file> <file>", "", func(c commander.Context) {
		fmt.Printf("<file> = %q\n",
			c.MustStrings("<file>"))
	})

commander.Program.Parse()

Get the terminal output:

$ counted_example -vvvvvvvvvv
# output: -v = 10

$ counted_example go go
# output: go = 2

$ counted_example --path ./here --path ./there
# output: --path = ["./here" "./there"]

$ counted_example this.txt that.txt
# output: <file> = ["this.txt" "that.txt"]

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

Options:
  -h --help     output usage information
  -v --version  output the version number

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
Program.Command("calculator_example").
	Version("0.0.1").
	Description("Simple calculator example")

// calculator_example <value> ( ( + | - | * | / ) <value> )...
Program.Command("<value> ( ( + | - | * | / ) <value> )...", "", func() {
	var result int
	values := Program.MustStrings("<value>")
	for index, value := range values {
		if i, err := strconv.Atoi(value); err != nil {
		} else if index == 0 {
			result = i
		} else {
			switch Program.GetArg(index*2 - 1) {
			case "+":
				result += i
			case "-":
				result -= i
			case "*":
				result *= i
			case "/":
				result /= i
			}
		}
	}
	fmt.Println(Program.ArgsString(), "=", result)
})

// calculator_example <function> <value> [( , <value> )]...
Program.Command("<function> <value> [( , <value> )]...", "", func() {
	var result int
	switch Program.MustString("<function>") {
	case "sum":
		values := Program.MustStrings("<value>")
		for _, value := range values {
			if i, err := strconv.Atoi(value); err == nil {
				result += i
			}
		}
	}
	fmt.Println(Program.ArgsString(), "=", result)
})

// Examples: ...
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",
	},
)

commander.Program.Parse()

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

• func ExecPipeCommand(name string, arg ...string) (string, string, error)
• func ExecPipeStatementCommand(statement string) (string, string, error)
• func ExecStdCommand(name string, arg ...string) (string, error)
• func ExecStdStatementCommand(statement string) (string, error)
• func FormatDescription(title, desc string) string
• func SplitCommandStatement(statement string) (result []string)
• type Action
• type ActionNative
• type ActionNativeDocopt
• type ActionNativeSimple
• type ActionNormal
• type ActionResult
• 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, 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, bool)
  • func (d DocoptMap) GetStrings(key string) ([]string, bool)
  • func (d DocoptMap) Map() map[string]interface{}
  • func (d DocoptMap) MustBool(key string) bool
  • func (d DocoptMap) MustFloat(key string) float32
  • func (d DocoptMap) MustFloat64(key string) float64
  • func (d DocoptMap) MustInt(key string) int
  • func (d DocoptMap) MustInt64(key string) int64
  • func (d DocoptMap) MustString(key string) string
  • func (d DocoptMap) MustStrings(key string) []string
• type GoCommander

Functions

func ExecPipeCommand

func ExecPipeCommand(name string, arg ...string) (string, string, error)

func ExecPipeStatementCommand

func ExecPipeStatementCommand(statement string) (string, string, error)

func ExecStdCommand

func ExecStdCommand(name string, arg ...string) (string, error)

func ExecStdStatementCommand

func ExecStdStatementCommand(statement string) (string, error)

func FormatDescription

func FormatDescription(title, desc string) string

FormatDescription format a line description to symmetric string title and desc are shown the content by default format.

func SplitCommandStatement

func SplitCommandStatement(statement string) (result []string)

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 ActionResult

type ActionResult func() _Result

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 {
	Doc(doc string) Commander
	Version(ver string) Commander
	ShowVersion() string
	Description(desc string) Commander
	Annotation(title string, contents []string) Commander
	Command(usage string, args ...interface{}) Commander
	Aliases(aliases []string) Commander
	Option(usage string, args ...interface{}) Commander
	Action(action interface{}, keys ...[]string) Commander
	HelpMessage() string
	ShowHelpMessage() string
	Parse(argv ...[]string) (Context, error)
	ErrorHandling(func(error)) Commander
}

Commander Command line implementation

type Context

type Context interface {
	// _Argv
	GetArg(index int) string
	GetArgs(offsets ...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, bool)
	MustString(key string) string
	GetStrings(key string) ([]string, bool)
	MustStrings(key string) []string
	GetBool(key string) (bool, bool)
	MustBool(key string) bool
	GetInt64(key string) (int64, bool)
	MustInt64(key string) int64
	GetInt(key string) (int, bool)
	MustInt(key string) int
	GetFloat64(key string) (float64, bool)
	MustFloat64(key string) float64
	GetFloat(key string) (float32, bool)
	MustFloat(key string) float32
}

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, 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, bool)

func (DocoptMap) GetStrings

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

func (DocoptMap) Map

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

func (DocoptMap) MustBool

func (d DocoptMap) MustBool(key string) bool

func (DocoptMap) MustFloat

func (d DocoptMap) MustFloat(key string) float32

func (DocoptMap) MustFloat64

func (d DocoptMap) MustFloat64(key string) float64

func (DocoptMap) MustInt

func (d DocoptMap) MustInt(key string) int

func (DocoptMap) MustInt64

func (d DocoptMap) MustInt64(key string) int64

func (DocoptMap) MustString

func (d DocoptMap) MustString(key string) string

func (DocoptMap) MustStrings

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

type GoCommander

type GoCommander interface {
	Commander
	Context
}

var Program GoCommander = newProgram()