cli

README

bitbucket.org/ulfurinn/cli

This package is a fork/rewrite of github.com/codegangsta/cli with the purpose of providing smarter shell completion.

If you want to migrate from github.com/codegangsta/cli, you'll need to make minor changes in your command setup as there are differences in exposed types.

Documentation

Overview

DOC DRAFT

Package cli provides a toolset for writing command line interfaces.

This package started off as a fork of package github.com/codegangsta/cli with an aim to enhance shell completion but has diverged since then. Application definition structure is similar but not identical.

The following sections briefly describe the main components; see the API index for information on further customization.

Application basics

A minimally viable application looks like this:

func main() {
	a := cli.NewApp()
	a.Main.Action = func(*cli.Context) error {
		fmt.Println("hello, world")
		return nil
	}
	a.RunMain()
}

Named options

Options can be used as follows:

...
a.Main.Options = []cli.Option{
	cli.StringOption{
		Name:  "flag",
		Value: "default value",
	},
}
a.Main.Action = func(ctx *cli.Context) error {
	fmt.Println(ctx.String("flag"))
	return nil
}
...

$ app --flag value
> value

$ app
> default value

Positional arguments

Any command line argument that cannot be identified and parsed as a named option will be available in Args(), but a formal declaration provides type-specific parsing and better help messages.

Named options and positional arguments are declared and accessed through the same interface.

...
a.Main.Args = []cli.Option{
	cli.StringOption{
		Name:  "flag",
		Value: "default value",
	},
}
a.Main.Action = func(ctx *cli.Context) error {
	fmt.Println(ctx.String("flag"))
	return nil
}
...

$ app value
> value

Subcommands

Subcommands are created as follows:

...
a.Main.Commands = []cli.Command{
	Name:   "cmd",
	Action: func(*ctx.Context) error {
		fmt.Println("subcommand")
		return nil
	},
}
...

$ app cmd
> subcommand

Like the root command Main, subcommands can have their own options and subcommands.

Help

The root command has an implicit "help" subcommand, showing usage instructions. For help on subcommands, it is invoked as "app help subcmd1 subcmd2 ...".

Alternatively, every command has an implicit "--help" option that has the same effect.

The implicit "help-commands" subcommand prints a recursive list of all declared subcommands.

Shell completion

All subcommand and options are available for shell completion. Additionally, they can declare custom completion functions, returning a list of accepted values.

The bash completion function is available at https://bitbucket.org/ulfurinn/cli/raw/default/bash_completion; replace $PROG with the name of your executable.

Index

• func StdCompletion(*Context, Option) []string
• func StdCompletionFlags() string
• func ValueListCompletion(ctx *Context, opt Option) []string
• func ValueListValidation(ctx *Context, opt Option) error
• type App
  • func NewApp() *App
  • func (a *App) Run(arguments []string) error
  • func (a *App) RunMain()
• type BoolOption
  • func (f BoolOption) ApplyNamed(set *flags.Set)
  • func (f BoolOption) ApplyPositional(set *flags.Set)
  • func (f BoolOption) CompletionStrings() []string
  • func (f BoolOption) HelpString() string
• type Command
• type CompletionCallback
• type Context
  • func (c *Context) Arg(i int) string
  • func (c *Context) ArgLen() int
  • func (c *Context) Args() []string
  • func (c *Context) Bool(name string) (v bool)
  • func (c *Context) Float64(name string) (v float64)
  • func (c *Context) Int(name string) (v int)
  • func (c *Context) String(name string) (v string)
  • func (c *Context) StringSlice(name string) (v []string)
• type Exit
  • func (e Exit) Error() string
  • func (e Exit) IsError() bool
• type Float64Option
  • func (f Float64Option) ApplyNamed(set *flags.Set)
  • func (f Float64Option) ApplyPositional(set *flags.Set)
  • func (f Float64Option) CompletionStrings() []string
  • func (f Float64Option) HelpString() string
• type IntOption
  • func (f IntOption) ApplyNamed(set *flags.Set)
  • func (f IntOption) ApplyPositional(set *flags.Set)
  • func (f IntOption) CompletionStrings() []string
  • func (f IntOption) HelpString() string
• type Option
• type StringOption
  • func (f StringOption) ApplyNamed(set *flags.Set)
  • func (f StringOption) ApplyPositional(set *flags.Set)
  • func (f StringOption) CompletionStrings() []string
  • func (f StringOption) HelpString() string
• type StringSlice
  • func (f *StringSlice) Explicit() bool
  • func (f *StringSlice) Set(value string) error
  • func (f *StringSlice) String() string
  • func (f *StringSlice) Value() []string
• type StringSliceOption
  • func (f StringSliceOption) ApplyNamed(set *flags.Set)
  • func (f StringSliceOption) ApplyPositional(set *flags.Set)
  • func (f StringSliceOption) CompletionStrings() []string
  • func (f StringSliceOption) HelpString() string
  • func (f StringSliceOption) String() string
• type ValidationCallback

Functions

func StdCompletion

func StdCompletion(*Context, Option) []string

func StdCompletionFlags

func StdCompletionFlags() string

func ValueListCompletion

func ValueListCompletion(ctx *Context, opt Option) []string

ValueListCompletion is a shell completion generator for option values suggesting possible alternatives from a given list.

func ValueListValidation

func ValueListValidation(ctx *Context, opt Option) error

ValueListValidator is an option value validator checking against a given list of allowed values.

Types

type App

type App struct {
	HideHelp bool
	Name     string
	Usage    string
	Main     Command // the top-level command
	Out      io.Writer
}

App defines the entire application interface.

func NewApp

func NewApp() *App

NewApp sets up a new app instance.

func (*App) Run

func (a *App) Run(arguments []string) error

Run parses the given argument list and executes the matching command.

func (*App) RunMain

func (a *App) RunMain()

RunMain is an entry point suitable for most common cases.

type BoolOption

type BoolOption struct {
	Name     string
	Value    bool
	Usage    string
	EnvVar   string
	Hidden   bool
	Var      *bool
	Optional bool
	Local    bool
}

func (BoolOption) ApplyNamed

func (f BoolOption) ApplyNamed(set *flags.Set)

func (BoolOption) ApplyPositional

func (f BoolOption) ApplyPositional(set *flags.Set)

func (BoolOption) CompletionStrings

func (f BoolOption) CompletionStrings() []string

func (BoolOption) HelpString

func (f BoolOption) HelpString() string

type Command

type Command struct {
	Commands   []Command            // a list of subcommands
	Options    []Option             // a list of named options
	Args       []Option             // a list of positional arguments
	Name       string               // command name, used when parsing the argument list
	ShortName  string               // an alternative abbreviated name
	Usage      string               // usage documentation
	Before     func(*Context) error // a callback to run before the action
	Action     func(*Context) error // entry callback
	Completion func(*Context)       // an override for default shell completion
}

Command defines an executable action. Commands can be nested.

type CompletionCallback

type CompletionCallback func(*Context, Option) []string

type Context

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

Context represents the parsed process arguments.

func (*Context) Arg

func (c *Context) Arg(i int) string

Arg returns an unparsed argument.

func (*Context) ArgLen

func (c *Context) ArgLen() int

ArgLen returns the count of unparsed arguments.

func (*Context) Args

func (c *Context) Args() []string

Args returns all unparsed arguments.

func (*Context) Bool

func (c *Context) Bool(name string) (v bool)

Bool returns the value of an argument.

func (*Context) Float64

func (c *Context) Float64(name string) (v float64)

Float64 returns the value of an argument.

func (*Context) Int

func (c *Context) Int(name string) (v int)

Int returns the value of an argument.

func (*Context) String

func (c *Context) String(name string) (v string)

String returns the value of an argument.

func (*Context) StringSlice

func (c *Context) StringSlice(name string) (v []string)

StringSlice returns the value of an argument.

type Exit

type Exit struct {
	Err        error
	StatusCode int
}

Exit is an Error type returning which will cause the process to exit with the specified code.

func (Exit) Error

func (e Exit) Error() string

func (Exit) IsError

func (e Exit) IsError() bool

type Float64Option

type Float64Option struct {
	Name       string
	Value      float64
	Usage      string
	EnvVar     string
	Var        *float64
	Optional   bool
	Local      bool
	Completion CompletionCallback
}

func (Float64Option) ApplyNamed

func (f Float64Option) ApplyNamed(set *flags.Set)

func (Float64Option) ApplyPositional

func (f Float64Option) ApplyPositional(set *flags.Set)

func (Float64Option) CompletionStrings

func (f Float64Option) CompletionStrings() []string

func (Float64Option) HelpString

func (f Float64Option) HelpString() string

type IntOption

type IntOption struct {
	Name       string
	Value      int
	Usage      string
	EnvVar     string
	Var        *int
	Optional   bool
	Local      bool
	Completion CompletionCallback
}

func (IntOption) ApplyNamed

func (f IntOption) ApplyNamed(set *flags.Set)

func (IntOption) ApplyPositional

func (f IntOption) ApplyPositional(set *flags.Set)

func (IntOption) CompletionStrings

func (f IntOption) CompletionStrings() []string

func (IntOption) HelpString

func (f IntOption) HelpString() string

type Option

type Option interface {
	HelpString() string
	CompletionStrings() []string
	// Apply Option settings to the given flag set
	ApplyNamed(*flags.Set)
	ApplyPositional(*flags.Set)
	// contains filtered or unexported methods
}

Option is a common interface related to parsing flags in cli. For more advanced flag parsing techniques, it is recomended that this interface be implemented.

type StringOption

type StringOption struct {
	Name       string
	Value      string
	ValueList  []string
	Usage      string
	EnvVar     string
	Hidden     bool
	Var        *string
	Optional   bool
	Local      bool
	Completion CompletionCallback
	Validation ValidationCallback
}

func (StringOption) ApplyNamed

func (f StringOption) ApplyNamed(set *flags.Set)

func (StringOption) ApplyPositional

func (f StringOption) ApplyPositional(set *flags.Set)

func (StringOption) CompletionStrings

func (f StringOption) CompletionStrings() []string

func (StringOption) HelpString

func (f StringOption) HelpString() string

type StringSlice

type StringSlice []string

func (*StringSlice) Explicit

func (f *StringSlice) Explicit() bool

func (*StringSlice) Set

func (f *StringSlice) Set(value string) error

func (*StringSlice) String

func (f *StringSlice) String() string

func (*StringSlice) Value

func (f *StringSlice) Value() []string

type StringSliceOption

type StringSliceOption struct {
	Name       string
	Value      *StringSlice
	Usage      string
	EnvVar     string
	Hidden     bool
	Optional   bool
	Local      bool
	Completion CompletionCallback
	Validation ValidationCallback
}

StringSliceOption is an option type that represents a list of strings. Multiple occurrences of this option will be accumulated.

func (StringSliceOption) ApplyNamed

func (f StringSliceOption) ApplyNamed(set *flags.Set)

func (StringSliceOption) ApplyPositional

func (f StringSliceOption) ApplyPositional(set *flags.Set)

func (StringSliceOption) CompletionStrings

func (f StringSliceOption) CompletionStrings() []string

func (StringSliceOption) HelpString

func (f StringSliceOption) HelpString() string

func (StringSliceOption) String

func (f StringSliceOption) String() string

type ValidationCallback

type ValidationCallback func(*Context, Option) error