cli

README

cli

Package cli makes it easy to create CLIs by defining options using struct tags.

Example

package main

import (
	"fmt"

	"github.com/isobit/cli"
)

type App struct {
	Excited  bool   `cli:"help='when true, use exclamation point'"`
	Greeting string `cli:"env=GREETING,help=the greeting to use"`
	Name     string `cli:"required,short=n,help=your name"`
}

func (app *App) Run() error {
	punctuation := "."
	if app.Excited {
		punctuation = "!"
	}
	fmt.Printf("%s, %s%s\n", app.Greeting, app.Name, punctuation)
	return nil
}

func main() {
	cli.New("greet", &App{Greeting: "Hey"}).
		Parse().
		RunFatal()
}

$ greet --help
USAGE:
    greet [OPTIONS]

OPTIONS:
    -h, --help                    show usage help
    --excited                     when true, use exclamation point
    --greeting <VALUE>  GREETING  the greeting to use  (default: Hey)
    -n, --name <VALUE>            your name  (required)

$ GREETING="Hello" greet -n world --excited
Hello, world!

Struct Tags

The parsing behavior for config fields can be controlled by adding a struct tag that cli understands. Command struct tags look like cli:"key1,key2=value,key3='blah'"; for example:

struct Example {
	Foo string `cli:"required,placeholder=quux,short=f,env=FOO,help='hello, world'"`
}

Tag	Value	Description
-	No	Ignore field (similar to encoding/json)
required	No	Error if the field is not set at least once
help	Yes	Custom help text
placeholder	Yes	Custom value placeholder in help text
name	Yes	Explicit flag name (by default names are derived from the struct field name)
short	Yes	Single character short name alias
env	Yes	Environment variable to use as a default value
repeatable	No	Allow flag to be specified many times (value must be a slice type, each flag will be appended)
hidden	No	Don't show field in help text

Tags are parsed according to this ABNF:

tags = "cli:" DQUOTE *(tag ",") tag DQUOTE
tag = key [ "=" value ]
key = *<anything except "=">
value = *<anything except ","> / "'" *<anything except "'"> "'"

Field Types and Flag Parsing

Primitive types (e.g. int and string), and pointers to primitive types (e.g. *int and *string) are handled natively by cli. In the case of pointers, if the default value is a nil pointer, and a value is passed, cli will construct a new value of the inner type and set the struct field to be a pointer to the newly constructed value.

There is no special parsing for string fields, they are set directly from input.

The following primitives are parsed by fmt.Sscanf using the %v directive:

• bool
• int, int8, int16, int32, int64
• uint8, uint16, uint32, uint64
• float32, float64

Additionally, time.Duration fields are automatically parsed using time.ParseDuration.

All other types are parsed using the first method below that is implemented with the type itself or a pointer to the type as the receiver:

• Set(s string) error (similar to flag.Value)
• UnmarshalText(text []byte) error (encoding.TextUnmarshaler)
• UnmarshalBinary(data []byte) error (encoding.BinaryUnmarshaler)

Many standard library types already implement one of these methods. For example, time.Time implements encoding.TextUnmarshaler for parsing RFC 3339 timestamps.

Custom types can be used so long as they implement one of the above methods. Here is an example which parses a string slice from a comma-delimited flag value string:

type App struct {
	Foos Foos
}

type Foos []string

func (foos *Foos) UnmarshalText(text []byte) error {
	s := string(text)
	*foos = append(*foos, strings.Split(s, ",")...)
	return nil
}

Documentation

Index

• Variables
• type Beforer
• type Command
  • func Build(name string, config interface{}) (*Command, error)
  • func New(name string, config interface{}) *Command
  • func (cmd *Command) AddCommand(subCmd *Command) *Command
  • func (cmd *Command) Description(description string) *Command
  • func (cmd *Command) Help(help string) *Command
  • func (cmd *Command) HelpString() string
  • func (cmd *Command) Parse() ParsedCommand
  • func (cmd *Command) ParseArgs(args []string) ParsedCommand
  • func (cmd *Command) WriteHelp(w io.Writer)
• type Context
  • func (ctx Context) Build(name string, config interface{}) (*Command, error)
  • func (ctx Context) New(name string, config interface{}) *Command
• type LookupEnvFunc
• type ParsedCommand
  • func (po ParsedCommand) Run() error
  • func (po ParsedCommand) RunFatal()
• type Runner
• type Setter
• type SetterFunc
• type Setuper

Variables

var DefaultContext = Context{
	ErrWriter: os.Stderr,
	LookupEnv: func(key string) (string, bool, error) {
		val, ok := os.LookupEnv(key)
		return val, ok, nil
	},
	Setter: nil,
}

var ErrHelp = fmt.Errorf("cli: help requested")

Types

type Beforer

type Beforer interface {
	Before() error
}

type Command

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

func Build

func Build(name string, config interface{}) (*Command, error)

Build is like New, but it returns any errors instead of calling panic, at the expense of being harder to chain.

func New

func New(name string, config interface{}) *Command

New creates a new Command with the provided name and config. The config must be a pointer to a configuration struct. Default values can be specified by simply setting them on the config struct.

New returns an Command pointer for further method chaining. If an error is encountered while building the options, such as a struct field having an unsupported type, New will panic. If you would like to have errors returned for handling, use Build instead.

func (*Command) AddCommand

func (cmd *Command) AddCommand(subCmd *Command) *Command

AddCommand registers another Command instance as a subcommand of this Command instance.

func (*Command) Description

func (cmd *Command) Description(description string) *Command

func (*Command) Help

func (cmd *Command) Help(help string) *Command

func (*Command) HelpString

func (cmd *Command) HelpString() string

func (*Command) Parse

func (cmd *Command) Parse() ParsedCommand

Parse is a convenience method for calling ParseArgs(os.Args)

func (*Command) ParseArgs

func (cmd *Command) ParseArgs(args []string) ParsedCommand

ParseArgs parses using the passed-in args slice and OS-provided environment variables and returns a ParsedCommand instance which can be used for further method chaining.

If there are args remaining after parsing this Command' fields, subcommands will be parsed recursively. The returned ParsedCommand.Runner represents the command which was specified (if it has a Run method). If a Before method is implemented on the Command' config, this method will call it before recursing into any subcommand parsing.

func (*Command) WriteHelp

func (cmd *Command) WriteHelp(w io.Writer)

type Context

type Context struct {
	ErrWriter io.Writer
	LookupEnv LookupEnvFunc
	Setter    SetterFunc
}

func (Context) Build

func (ctx Context) Build(name string, config interface{}) (*Command, error)

Build is like New, but it returns any errors instead of calling panic, at the expense of being harder to chain.

func (Context) New

func (ctx Context) New(name string, config interface{}) *Command

New creates a new Command with the provided name and config. The config must be a pointer to a configuration struct. Default values can be specified by simply setting them on the config struct.

New returns an Command pointer for further method chaining. If an error is encountered while building the options, such as a struct field having an unsupported type, New will panic. If you would like to have errors returned for handling, use Build instead.

type LookupEnvFunc

type LookupEnvFunc func(string) (string, bool, error)

type ParsedCommand

type ParsedCommand struct {
	Err     error
	Command *Command
	Runner  Runner
}

func (ParsedCommand) Run

func (po ParsedCommand) Run() error

Run calls the Run method of the Command config for the parsed command or, if an error occurred during parsing, prints the help text and returns that error instead. If help was requested, the error will flag.ErrHelp.

func (ParsedCommand) RunFatal

func (po ParsedCommand) RunFatal()

RunFatal is like Run, except it automatically handles printing out any errors returned by the Run method of the underlying Command config, and exits with an appropriate status (1 if error, 0 otherwise).

type Runner

type Runner interface {
	Run() error
}

type Setter

type Setter interface {
	Set(s string) error
}

type SetterFunc

type SetterFunc func(interface{}) Setter

type Setuper

type Setuper interface {
	SetupCommand(cmd *Command)
}