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
}

Contexts and Signal Handling

Here is an example of a "sleep" program which sleeps for the specified duration, but can be cancelled by a SIGINT or SIGTERM:

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/isobit/cli"
)

type SleepCommand struct {
	Duration time.Duration `cli:"short=d,required"`
}

func (cmd *Sleep) Run(ctx context.Context) error {
	fmt.Printf("sleeping for %s\n", cmd.Duration)
	select {
	case <-ctx.Done():
		return ctx.Err()
	case <-time.After(cmd.Duration):
		fmt.Println("done")
	}
	return nil
}

func main() {
	cli.New("sleep", &SleepCommand{}).
		Parse().
		RunFatalWithSigCancel()
}

Documentation

Index

• Variables
• type Beforer
• type CLI
  • func (cli CLI) Build(name string, config interface{}) (*Command, error)
  • func (cli CLI) New(name string, config interface{}) *Command
• 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() ParseResult
  • func (cmd *Command) ParseArgs(args []string) ParseResult
  • func (cmd *Command) WriteHelp(w io.Writer)
• type ContextRunner
• type ExitCoder
• type LookupEnvFunc
• type ParseResult
  • func (r ParseResult) Run() error
  • func (r ParseResult) RunFatal()
  • func (r ParseResult) RunFatalWithContext(ctx context.Context)
  • func (r ParseResult) RunFatalWithSigCancel()
  • func (r ParseResult) RunWithContext(ctx context.Context) error
  • func (r ParseResult) RunWithSigCancel() error
• type Runner
• type Setter
• type SetterFunc
• type Setuper

Variables

var Defaults = CLI{
	HelpWriter: os.Stderr,
	ErrWriter:  os.Stderr,
	LookupEnv:  osLookupEnv,
	Setter:     nil,
}

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

Types

type Beforer

type Beforer interface {
	Before() error
}

type CLI

type CLI struct {
	// HelpWriter is used to print help output when calling ParseResult.Run
	// (and other similar methods).
	HelpWriter io.Writer

	// ErrWriter is used to print errors when calling ParseResult.Run (and
	// other similar methods).
	ErrWriter io.Writer

	// LookupEnv is called during parsing for any fields which define an env
	// var key, but are not set by argument.
	LookupEnv LookupEnvFunc

	// Setter can be used to define custom setters for arbitrary field types,
	// or to override the default field setters.
	//
	// Here is an example which uses a custom layout for parsing any time.Time
	// fields:
	//
	//  type CustomTimeSetter struct {
	//  	value *time.Time
	//  }
	//  func (ts *CustomTimeSetter) Set(s string) error {
	//  	parsed, err := time.Parse("2006-01-02 15:04", s)
	//  	if err != nil {
	//  		return err
	//  	}
	//  	*ts.value = parsed
	//  	return nil
	//  }
	//  cli := cli.CLI{
	//  	ErrWriter: cli.Defaults.ErrWriter,
	//  	LookupEnv: cli.Defaults.LookupEnv,
	//  	Setter: func(i interface{}) cli.Setter {
	//  		switch v := i.(type) {
	//  		case *time.Time:
	//  			return &CustomTimeSetter{v}
	//  		default:
	//  			// return nil to fall back on default behavior
	//  			return nil
	//  		}
	//  	},
	//  }
	Setter SetterFunc
}

CLI defines functionality which is global to all commands which it constructs. The top-level New and Build methods use a CLI with good defaults for most cases, but custom CLI structs can be used to modify behavior.

func (CLI) Build

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

func (CLI) New

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

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() ParseResult

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

func (*Command) ParseArgs

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

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

If there are args remaining after parsing this Command's fields, subcommands will be recursively parsed until a concrete result is returned. If a Before method is implemented on the config, this method will call it before recursing into any subcommand parsing.

func (*Command) WriteHelp

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

type ContextRunner

type ContextRunner interface {
	Run(context.Context) error
}

type ExitCoder

type ExitCoder interface {
	ExitCode() int
}

type LookupEnvFunc

type LookupEnvFunc func(key string) (val string, ok bool, err error)

type ParseResult

type ParseResult struct {
	Err     error
	Command *Command
	// contains filtered or unexported fields
}

ParseResult contains information about the results of command argument parsing.

func (ParseResult) Run

func (r ParseResult) 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. If the underlying command Run method accepts a context, context.Background() will be passed.

func (ParseResult) RunFatal

func (r ParseResult) 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 code.

If no error occurs, the exit code will be 0. If an error is returned and it implements the ExitCoder interface, the result of ExitCode() will be used as the exit code. If an error is returned that does not implement ExitCoder, the exit code will be 1.

func (ParseResult) RunFatalWithContext

func (r ParseResult) RunFatalWithContext(ctx context.Context)

RunFatalWithContext is like RunFatal, but it accepts an explicit context which will be passed to the command's Run method if it accepts one.

func (ParseResult) RunFatalWithSigCancel

func (r ParseResult) RunFatalWithSigCancel()

RunFatalWithSigCancel is like RunFatal, but it automatically registers a signal handler for SIGINT and SIGTERM that will cancel the context that is passed to the command's Run method, if it accepts one.

func (ParseResult) RunWithContext

func (r ParseResult) RunWithContext(ctx context.Context) error

RunWithContext is like Run, but it accepts an explicit context which will be passed to the command's Run method, if it accepts one.

func (ParseResult) RunWithSigCancel

func (r ParseResult) RunWithSigCancel() error

RunWithSigCancel is like Run, but it automatically registers a signal handler for SIGINT and SIGTERM that will cancel the context that is passed to the command's Run method, if it accepts one.

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