cli

Documentation

Index

• Variables
• func ContextWithOptions(ctx context.Context, fs *FlagSet) context.Context
• func Exit(r CLI, code int)
• func OptionFromContext(ctx context.Context, name string) (v interface{}, ok bool)
• func Parse(fs *FlagSet, expectedArgs int, args []string) (actualArgs []string, rest []string, err error)
• func ParseAndRunCommand(ctx context.Context, c CLI, fs *FlagSet, cmds map[string]CLI, args []string) error
• func ParseUsage(cli CLI, fs *FlagSet, expectedArgs int, args []string) (rargs, rest []string, ok bool, err error)
• func Run(ctx context.Context, cli CLI) error
• func RunCommand(ctx context.Context, args []string, cmds map[string]CLI) error
• func Usage(cli CLI)
• func UsageError(cli CLI, err error)
• type CLI
  • func Lazy(constructor func(context.Context) (CLI, error)) CLI
• type FlagSet
  • func NewFlagSet(name string) *FlagSet
• type Manual

Variables

var (
	// ErrInvalidArgs is returned by CLI Run's method when invalid arguments
	// were passed.
	ErrInvalidArgs = errors.New("invalid usage of CLI")

	// ErrHelp returned when -h or --help flags are passed.
	ErrHelp = errors.New("help requested")
)

Functions

func ContextWithOptions

func ContextWithOptions(ctx context.Context, fs *FlagSet) context.Context

ContextWithOptions iterates over the options in fs and returns a context with the options defined as values.

Options parsed are propagated to sub-command CLI via context.Context and can be retrieved by using OptionFromContext.

func Exit

func Exit(r CLI, code int)

Exit prints r's usage and exits the program exit code.

func OptionFromContext

func OptionFromContext(ctx context.Context, name string) (
	v interface{}, ok bool,
)

OptionFromContext attempts to retrieve the value of an flag named `name` from this context.

func Parse

func Parse(fs *FlagSet, expectedArgs int, args []string) (
	actualArgs []string, rest []string, err error,
)

Parse parses all flags in args and returns the remaining arguments as defined by expectedArgs. Note that options are expected to be passed first, then arguments: [options] <arg1> <arg2> ...

Example:

  var myBoolOpt
  fs := NewFlagSet("ie", []string{"my-mandatory-arg"})
  fs.BoolVar(&myBoolOpt, "bool-opt", false, "bool opt flag")

	 fs.Parse([]string{"-bool-opt"}) // returns nil, ErrInvalidArgs
	 fs.Parse([]string{"my-value"}) // returns []string{"my-value"}, nil
	 fs.Parse([]string{"-bool-opt", "my-value"}) // returns []string{"my-value"}, nil
	 fs.Parse([]string{"-bool-opt", "my-value", "other-values"}) // returns []string{"my-value"}, nil

Note that ErrHelp is returned if -h or --help flags are in args.

func ParseAndRunCommand

func ParseAndRunCommand(
	ctx context.Context, c CLI, fs *FlagSet, cmds map[string]CLI, args []string,
) error

ParseAndRunCommand is a helper to run CLI implementations that expect no arguments and simply run a sub-command CLI.

Options parsed are propagated to sub-command CLI via context.Context and can be retrieved by using OptionFromContext.

func ParseUsage

func ParseUsage(cli CLI, fs *FlagSet, expectedArgs int, args []string) (
	rargs, rest []string, ok bool, err error,
)

ParseUsage calls Parse and handles ErrHelp by returning false. If flags are parsed with no errors and usage flag is not passed, then this function returns true.

func Run

func Run(ctx context.Context, cli CLI) error

Run runs cli with os.Args

func RunCommand

func RunCommand(ctx context.Context, args []string, cmds map[string]CLI) error

RunCommand is a helper that attempts to find and run the next command in cmds.

func Usage

func Usage(cli CLI)

Usage is the function called when an error occurs while parsing a CLI's arguments or when -h flag is passed.

func UsageError

func UsageError(cli CLI, err error)

UsageError prints err and the cli Usage.

Types

type CLI

type CLI interface {
	// Parse takes args and interprets them.
	Run(ctx context.Context, args []string) error

	Man() Manual
}

CLI represents a command-line interface.

func Lazy

func Lazy(constructor func(context.Context) (CLI, error)) CLI

Lazy returns a CLI that lazily uses the given constructor to initialize a CLI when Run is called for the first time.

type FlagSet

type FlagSet struct {
	flag.FlagSet
	// contains filtered or unexported fields
}

FlagSet is just a type alias used to foster NewFlagSet usage.

func NewFlagSet

func NewFlagSet(name string) *FlagSet

NewFlagSet is a helper around flag.NewFlagSet that sets sane defaults.

type Manual

type Manual struct {
	Name string

	// Summary is a short 80-100 character description.
	Summary string

	// Synopsis is a single line synopsis of how
	// this CLI is to be used. It should ONLY include
	// the semantic information about how arguments are parsed.
	//
	// Example: [<options>] [<revision-range>] [[--] <path>...]
	Synopsis string

	// Commands is a list of accepted commands or nil
	// if no commands are expected.
	Commands []Manual

	Options FlagSet
}

Manual represents a CLI's manual and documentation.