Documentation ¶
Overview ¶
Package fisk provides command line interfaces like this:
$ chat usage: chat [<flags>] <command> [<flags>] [<args> ...] Flags: --debug enable debug mode --help Show help. --server=127.0.0.1 server address Commands: help <command> Show help for a command. post [<flags>] <channel> Post a message to a channel. register <nick> <name> Register a new user. $ chat help post usage: chat [<flags>] post [<flags>] <channel> [<text>] Post a message to a channel. Flags: --image=IMAGE image to post Args: <channel> channel to post to [<text>] text to post $ chat post --image=~/Downloads/owls.jpg pics
From code like this:
package main import "github.com/choria-io/fisk" var ( debug = fisk.Flag("debug", "enable debug mode").Default("false").Bool() serverIP = fisk.Flag("server", "server address").Default("127.0.0.1").IP() register = fisk.Command("register", "Register a new user.") registerNick = register.Arg("nick", "nickname for user").Required().String() registerName = register.Arg("name", "name of user").Required().String() post = fisk.Command("post", "Post a message to a channel.") postImage = post.Flag("image", "image to post").ExistingFile() postChannel = post.Arg("channel", "channel to post to").Required().String() postText = post.Arg("text", "text to post").String() ) func main() { switch fisk.Parse() { // Register user case "register": println(*registerNick) // Post message case "post": if *postImage != nil { } if *postText != "" { } } }
Index ¶
- Variables
- func Errorf(format string, args ...interface{})
- func ExpandArgsFromFile(filename string) (out []string, err error)
- func FatalIfError(err error, format string, args ...interface{})
- func FatalUsage(format string, args ...interface{})
- func FatalUsageContext(context *ParseContext, format string, args ...interface{})
- func Fatalf(format string, args ...interface{})
- func MustParse(command string, err error) string
- func Parse() string
- func ParseDuration(d string) (time.Duration, error)
- func Usage()
- type Action
- type Application
- func (a *Application) Action(action Action) *Application
- func (a *Application) Author(author string) *Application
- func (a *Application) Cheat(cheat string, help string) *Application
- func (a *Application) CheatFile(fs fs.ReadFileFS, cheat string, file string) *Application
- func (c *Application) CmdCompletion(context *ParseContext) []string
- func (a *Application) Command(name, help string) *CmdClause
- func (a *Application) Commandf(name string, format string, arg ...interface{}) *CmdClause
- func (a *Application) DefaultEnvars() *Application
- func (a *Application) ErrorUsageTemplate(template string) *Application
- func (a *Application) ErrorWriter(w io.Writer) *Application
- func (a *Application) Errorf(format string, args ...interface{})
- func (a *Application) ExternalPluginCommand(command string, model json.RawMessage, name string, help string) (*CmdClause, error)
- func (a *Application) FatalIfError(err error, format string, args ...interface{})
- func (a *Application) FatalUsage(format string, args ...interface{})
- func (a *Application) FatalUsageContext(context *ParseContext, format string, args ...interface{})
- func (a *Application) Fatalf(format string, args ...interface{})
- func (c *Application) FlagCompletion(flagName string, flagValue string) (choices []string, flagMatch bool, optionMatch bool)
- func (a *Application) Interspersed(interspersed bool) *Application
- func (a *Application) Model() *ApplicationModel
- func (a *Application) MustParseWithUsage(args []string) (command string)
- func (a *Application) Parse(args []string) (command string, err error)
- func (a *Application) ParseContext(args []string) (*ParseContext, error)
- func (a *Application) PreAction(action Action) *Application
- func (a *Application) Terminate(terminate func(int)) *Application
- func (a *Application) Usage(args []string)
- func (a *Application) UsageForContext(context *ParseContext) error
- func (a *Application) UsageForContextWithTemplate(context *ParseContext, indent int, tmpl string) error
- func (a *Application) UsageFuncs(funcs template.FuncMap) *Application
- func (a *Application) UsageTemplate(template string) *Application
- func (a *Application) UsageWriter(w io.Writer) *Application
- func (a *Application) Validate(validator ApplicationValidator) *Application
- func (a *Application) Version(version string) *Application
- func (a *Application) WithCheats(tags ...string) *Application
- func (a *Application) Writer(w io.Writer) *Application
- type ApplicationModel
- type ApplicationValidator
- type ArgClause
- func (a *ArgClause) Action(action Action) *ArgClause
- func (p *ArgClause) Bool() (target *bool)
- func (p *ArgClause) BoolList() (target *[]bool)
- func (p *ArgClause) BoolListVar(target *[]bool)
- func (p *ArgClause) BoolVar(target *bool)
- func (p *ArgClause) Bytes() (target *units.Base2Bytes)
- func (p *ArgClause) BytesVar(target *units.Base2Bytes)
- func (p *ArgClause) Counter() (target *int)
- func (p *ArgClause) CounterVar(target *int)
- func (a *ArgClause) Default(values ...string) *ArgClause
- func (p *ArgClause) Duration() (target *time.Duration)
- func (p *ArgClause) DurationList() (target *[]time.Duration)
- func (p *ArgClause) DurationListVar(target *[]time.Duration)
- func (p *ArgClause) DurationVar(target *time.Duration)
- func (p *ArgClause) Enum(options ...string) (target *string)
- func (p *ArgClause) EnumVar(target *string, options ...string)
- func (p *ArgClause) Enums(options ...string) (target *[]string)
- func (p *ArgClause) EnumsVar(target *[]string, options ...string)
- func (a *ArgClause) Envar(name string) *ArgClause
- func (p *ArgClause) ExistingDir() (target *string)
- func (p *ArgClause) ExistingDirVar(target *string)
- func (p *ArgClause) ExistingDirs() (target *[]string)
- func (p *ArgClause) ExistingDirsVar(target *[]string)
- func (p *ArgClause) ExistingFile() (target *string)
- func (p *ArgClause) ExistingFileOrDir() (target *string)
- func (p *ArgClause) ExistingFileOrDirVar(target *string)
- func (p *ArgClause) ExistingFileVar(target *string)
- func (p *ArgClause) ExistingFiles() (target *[]string)
- func (p *ArgClause) ExistingFilesOrDirs() (target *[]string)
- func (p *ArgClause) ExistingFilesOrDirsVar(target *[]string)
- func (p *ArgClause) ExistingFilesVar(target *[]string)
- func (p *ArgClause) File() (target **os.File)
- func (p *ArgClause) FileVar(target **os.File)
- func (p *ArgClause) Float() (target *float64)
- func (p *ArgClause) Float32() (target *float32)
- func (p *ArgClause) Float32List() (target *[]float32)
- func (p *ArgClause) Float32ListVar(target *[]float32)
- func (p *ArgClause) Float32Var(target *float32)
- func (p *ArgClause) Float64() (target *float64)
- func (p *ArgClause) Float64List() (target *[]float64)
- func (p *ArgClause) Float64ListVar(target *[]float64)
- func (p *ArgClause) Float64Var(target *float64)
- func (p *ArgClause) FloatVar(target *float64)
- func (e *ArgClause) GetEnvarValue() string
- func (e *ArgClause) GetSplitEnvarValue() []string
- func (e *ArgClause) HasEnvarValue() bool
- func (a *ArgClause) Help(help string) *ArgClause
- func (p *ArgClause) HexBytes() (target *[]byte)
- func (p *ArgClause) HexBytesList() (target *[][]byte)
- func (p *ArgClause) HexBytesListVar(target *[][]byte)
- func (p *ArgClause) HexBytesVar(target *[]byte)
- func (a *ArgClause) Hidden() *ArgClause
- func (a *ArgClause) HintAction(action HintAction) *ArgClause
- func (a *ArgClause) HintOptions(options ...string) *ArgClause
- func (p *ArgClause) IP() (target *net.IP)
- func (p *ArgClause) IPList() (target *[]net.IP)
- func (p *ArgClause) IPListVar(target *[]net.IP)
- func (p *ArgClause) IPVar(target *net.IP)
- func (p *ArgClause) Int() (target *int)
- func (p *ArgClause) Int16() (target *int16)
- func (p *ArgClause) Int16List() (target *[]int16)
- func (p *ArgClause) Int16ListVar(target *[]int16)
- func (p *ArgClause) Int16Var(target *int16)
- func (p *ArgClause) Int32() (target *int32)
- func (p *ArgClause) Int32List() (target *[]int32)
- func (p *ArgClause) Int32ListVar(target *[]int32)
- func (p *ArgClause) Int32Var(target *int32)
- func (p *ArgClause) Int64() (target *int64)
- func (p *ArgClause) Int64List() (target *[]int64)
- func (p *ArgClause) Int64ListVar(target *[]int64)
- func (p *ArgClause) Int64Var(target *int64)
- func (p *ArgClause) Int8() (target *int8)
- func (p *ArgClause) Int8List() (target *[]int8)
- func (p *ArgClause) Int8ListVar(target *[]int8)
- func (p *ArgClause) Int8Var(target *int8)
- func (p *ArgClause) IntVar(target *int)
- func (p *ArgClause) Ints() (target *[]int)
- func (p *ArgClause) IntsVar(target *[]int)
- func (a *ArgClause) Model() *ArgModel
- func (a *ArgClause) NoEnvar() *ArgClause
- func (p *ArgClause) OpenFile(flag int, perm os.FileMode) (target **os.File)
- func (p *ArgClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)
- func (a *ArgClause) PlaceHolder(value string) *ArgClause
- func (a *ArgClause) PreAction(action Action) *ArgClause
- func (p *ArgClause) Regexp() (target **regexp.Regexp)
- func (p *ArgClause) RegexpList() (target *[]*regexp.Regexp)
- func (p *ArgClause) RegexpListVar(target *[]*regexp.Regexp)
- func (p *ArgClause) RegexpVar(target **regexp.Regexp)
- func (a *ArgClause) Required() *ArgClause
- func (p *ArgClause) ResolvedIP() (target *net.IP)
- func (p *ArgClause) ResolvedIPList() (target *[]net.IP)
- func (p *ArgClause) ResolvedIPListVar(target *[]net.IP)
- func (p *ArgClause) ResolvedIPVar(target *net.IP)
- func (p *ArgClause) SetText(text Text)
- func (p *ArgClause) SetValue(value Value)
- func (p *ArgClause) String() (target *string)
- func (p *ArgClause) StringMap() (target *map[string]string)
- func (p *ArgClause) StringMapVar(target *map[string]string)
- func (p *ArgClause) StringVar(target *string)
- func (p *ArgClause) Strings() (target *[]string)
- func (p *ArgClause) StringsVar(target *[]string)
- func (p *ArgClause) TCP() (target **net.TCPAddr)
- func (p *ArgClause) TCPList() (target *[]*net.TCPAddr)
- func (p *ArgClause) TCPListVar(target *[]*net.TCPAddr)
- func (p *ArgClause) TCPVar(target **net.TCPAddr)
- func (p *ArgClause) URL() (target **url.URL)
- func (p *ArgClause) URLList() (target *[]*url.URL)
- func (p *ArgClause) URLListVar(target *[]*url.URL)
- func (p *ArgClause) URLVar(target **url.URL)
- func (p *ArgClause) Uint() (target *uint)
- func (p *ArgClause) Uint16() (target *uint16)
- func (p *ArgClause) Uint16List() (target *[]uint16)
- func (p *ArgClause) Uint16ListVar(target *[]uint16)
- func (p *ArgClause) Uint16Var(target *uint16)
- func (p *ArgClause) Uint32() (target *uint32)
- func (p *ArgClause) Uint32List() (target *[]uint32)
- func (p *ArgClause) Uint32ListVar(target *[]uint32)
- func (p *ArgClause) Uint32Var(target *uint32)
- func (p *ArgClause) Uint64() (target *uint64)
- func (p *ArgClause) Uint64List() (target *[]uint64)
- func (p *ArgClause) Uint64ListVar(target *[]uint64)
- func (p *ArgClause) Uint64Var(target *uint64)
- func (p *ArgClause) Uint8() (target *uint8)
- func (p *ArgClause) Uint8List() (target *[]uint8)
- func (p *ArgClause) Uint8ListVar(target *[]uint8)
- func (p *ArgClause) Uint8Var(target *uint8)
- func (p *ArgClause) UintVar(target *uint)
- func (p *ArgClause) Uints() (target *[]uint)
- func (p *ArgClause) UintsVar(target *[]uint)
- func (p *ArgClause) UnNegatableBool() (target *bool)
- func (p *ArgClause) UnNegatableBoolList() (target *[]bool)
- func (p *ArgClause) UnNegatableBoolListVar(target *[]bool)
- func (p *ArgClause) UnNegatableBoolVar(target *bool)
- func (a *ArgClause) Validator(validator OptionValidator) *ArgClause
- type ArgGroupModel
- type ArgModel
- type BoolFlag
- type CmdClause
- func (c *CmdClause) Action(action Action) *CmdClause
- func (c *CmdClause) Alias(name string) *CmdClause
- func (c *CmdClause) Cheat(cheat string, help string) *CmdClause
- func (c *CmdClause) CheatFile(fs fs.ReadFileFS, cheat string, file string) *CmdClause
- func (c *CmdClause) CmdCompletion(context *ParseContext) []string
- func (c *CmdClause) Command(name, help string) *CmdClause
- func (c *CmdClause) Commandf(name string, format string, a ...interface{}) *CmdClause
- func (c *CmdClause) Default() *CmdClause
- func (c *CmdClause) FlagCompletion(flagName string, flagValue string) (choices []string, flagMatch bool, optionMatch bool)
- func (c *CmdClause) FullCommand() string
- func (c *CmdClause) Help(help string) *CmdClause
- func (c *CmdClause) HelpLong(help string) *CmdClause
- func (c *CmdClause) Hidden() *CmdClause
- func (c *CmdClause) Model() *CmdModel
- func (c *CmdClause) PreAction(action Action) *CmdClause
- func (c *CmdClause) Validate(validator CmdClauseValidator) *CmdClause
- type CmdClauseValidator
- type CmdGroupModel
- type CmdModel
- type FlagClause
- func (f *FlagClause) Action(action Action) *FlagClause
- func (f *FlagClause) Bool() (target *bool)
- func (p *FlagClause) BoolList() (target *[]bool)
- func (p *FlagClause) BoolListVar(target *[]bool)
- func (p *FlagClause) BoolVar(target *bool)
- func (p *FlagClause) Bytes() (target *units.Base2Bytes)
- func (p *FlagClause) BytesVar(target *units.Base2Bytes)
- func (p *FlagClause) Counter() (target *int)
- func (p *FlagClause) CounterVar(target *int)
- func (f *FlagClause) Default(values ...string) *FlagClause
- func (p *FlagClause) Duration() (target *time.Duration)
- func (p *FlagClause) DurationList() (target *[]time.Duration)
- func (p *FlagClause) DurationListVar(target *[]time.Duration)
- func (p *FlagClause) DurationVar(target *time.Duration)
- func (a *FlagClause) Enum(options ...string) (target *string)
- func (a *FlagClause) EnumVar(target *string, options ...string)
- func (p *FlagClause) Enums(options ...string) (target *[]string)
- func (p *FlagClause) EnumsVar(target *[]string, options ...string)
- func (f *FlagClause) Envar(name string) *FlagClause
- func (p *FlagClause) ExistingDir() (target *string)
- func (p *FlagClause) ExistingDirVar(target *string)
- func (p *FlagClause) ExistingDirs() (target *[]string)
- func (p *FlagClause) ExistingDirsVar(target *[]string)
- func (p *FlagClause) ExistingFile() (target *string)
- func (p *FlagClause) ExistingFileOrDir() (target *string)
- func (p *FlagClause) ExistingFileOrDirVar(target *string)
- func (p *FlagClause) ExistingFileVar(target *string)
- func (p *FlagClause) ExistingFiles() (target *[]string)
- func (p *FlagClause) ExistingFilesOrDirs() (target *[]string)
- func (p *FlagClause) ExistingFilesOrDirsVar(target *[]string)
- func (p *FlagClause) ExistingFilesVar(target *[]string)
- func (p *FlagClause) File() (target **os.File)
- func (p *FlagClause) FileVar(target **os.File)
- func (p *FlagClause) Float() (target *float64)
- func (p *FlagClause) Float32() (target *float32)
- func (p *FlagClause) Float32List() (target *[]float32)
- func (p *FlagClause) Float32ListVar(target *[]float32)
- func (p *FlagClause) Float32Var(target *float32)
- func (p *FlagClause) Float64() (target *float64)
- func (p *FlagClause) Float64List() (target *[]float64)
- func (p *FlagClause) Float64ListVar(target *[]float64)
- func (p *FlagClause) Float64Var(target *float64)
- func (p *FlagClause) FloatVar(target *float64)
- func (e *FlagClause) GetEnvarValue() string
- func (e *FlagClause) GetSplitEnvarValue() []string
- func (e *FlagClause) HasEnvarValue() bool
- func (f *FlagClause) Help(help string) *FlagClause
- func (p *FlagClause) HexBytes() (target *[]byte)
- func (p *FlagClause) HexBytesList() (target *[][]byte)
- func (p *FlagClause) HexBytesListVar(target *[][]byte)
- func (p *FlagClause) HexBytesVar(target *[]byte)
- func (f *FlagClause) Hidden() *FlagClause
- func (a *FlagClause) HintAction(action HintAction) *FlagClause
- func (a *FlagClause) HintOptions(options ...string) *FlagClause
- func (p *FlagClause) IP() (target *net.IP)
- func (p *FlagClause) IPList() (target *[]net.IP)
- func (p *FlagClause) IPListVar(target *[]net.IP)
- func (p *FlagClause) IPVar(target *net.IP)
- func (p *FlagClause) Int() (target *int)
- func (p *FlagClause) Int16() (target *int16)
- func (p *FlagClause) Int16List() (target *[]int16)
- func (p *FlagClause) Int16ListVar(target *[]int16)
- func (p *FlagClause) Int16Var(target *int16)
- func (p *FlagClause) Int32() (target *int32)
- func (p *FlagClause) Int32List() (target *[]int32)
- func (p *FlagClause) Int32ListVar(target *[]int32)
- func (p *FlagClause) Int32Var(target *int32)
- func (p *FlagClause) Int64() (target *int64)
- func (p *FlagClause) Int64List() (target *[]int64)
- func (p *FlagClause) Int64ListVar(target *[]int64)
- func (p *FlagClause) Int64Var(target *int64)
- func (p *FlagClause) Int8() (target *int8)
- func (p *FlagClause) Int8List() (target *[]int8)
- func (p *FlagClause) Int8ListVar(target *[]int8)
- func (p *FlagClause) Int8Var(target *int8)
- func (p *FlagClause) IntVar(target *int)
- func (p *FlagClause) Ints() (target *[]int)
- func (p *FlagClause) IntsVar(target *[]int)
- func (f *FlagClause) IsSetByUser(setByUser *bool) *FlagClause
- func (f *FlagClause) Model() *FlagModel
- func (f *FlagClause) NoEnvar() *FlagClause
- func (p *FlagClause) OpenFile(flag int, perm os.FileMode) (target **os.File)
- func (p *FlagClause) OpenFileVar(target **os.File, flag int, perm os.FileMode)
- func (f *FlagClause) OverrideDefaultFromEnvar(envar string) *FlagClause
- func (f *FlagClause) PlaceHolder(placeholder string) *FlagClause
- func (f *FlagClause) PreAction(action Action) *FlagClause
- func (p *FlagClause) Regexp() (target **regexp.Regexp)
- func (p *FlagClause) RegexpList() (target *[]*regexp.Regexp)
- func (p *FlagClause) RegexpListVar(target *[]*regexp.Regexp)
- func (p *FlagClause) RegexpVar(target **regexp.Regexp)
- func (f *FlagClause) Required() *FlagClause
- func (p *FlagClause) ResolvedIP() (target *net.IP)
- func (p *FlagClause) ResolvedIPList() (target *[]net.IP)
- func (p *FlagClause) ResolvedIPListVar(target *[]net.IP)
- func (p *FlagClause) ResolvedIPVar(target *net.IP)
- func (p *FlagClause) SetText(text Text)
- func (p *FlagClause) SetValue(value Value)
- func (f *FlagClause) Short(name rune) *FlagClause
- func (p *FlagClause) String() (target *string)
- func (p *FlagClause) StringMap() (target *map[string]string)
- func (p *FlagClause) StringMapVar(target *map[string]string)
- func (p *FlagClause) StringVar(target *string)
- func (p *FlagClause) Strings() (target *[]string)
- func (p *FlagClause) StringsVar(target *[]string)
- func (p *FlagClause) TCP() (target **net.TCPAddr)
- func (p *FlagClause) TCPList() (target *[]*net.TCPAddr)
- func (p *FlagClause) TCPListVar(target *[]*net.TCPAddr)
- func (p *FlagClause) TCPVar(target **net.TCPAddr)
- func (p *FlagClause) URL() (target **url.URL)
- func (p *FlagClause) URLList() (target *[]*url.URL)
- func (p *FlagClause) URLListVar(target *[]*url.URL)
- func (p *FlagClause) URLVar(target **url.URL)
- func (p *FlagClause) Uint() (target *uint)
- func (p *FlagClause) Uint16() (target *uint16)
- func (p *FlagClause) Uint16List() (target *[]uint16)
- func (p *FlagClause) Uint16ListVar(target *[]uint16)
- func (p *FlagClause) Uint16Var(target *uint16)
- func (p *FlagClause) Uint32() (target *uint32)
- func (p *FlagClause) Uint32List() (target *[]uint32)
- func (p *FlagClause) Uint32ListVar(target *[]uint32)
- func (p *FlagClause) Uint32Var(target *uint32)
- func (p *FlagClause) Uint64() (target *uint64)
- func (p *FlagClause) Uint64List() (target *[]uint64)
- func (p *FlagClause) Uint64ListVar(target *[]uint64)
- func (p *FlagClause) Uint64Var(target *uint64)
- func (p *FlagClause) Uint8() (target *uint8)
- func (p *FlagClause) Uint8List() (target *[]uint8)
- func (p *FlagClause) Uint8ListVar(target *[]uint8)
- func (p *FlagClause) Uint8Var(target *uint8)
- func (p *FlagClause) UintVar(target *uint)
- func (p *FlagClause) Uints() (target *[]uint)
- func (p *FlagClause) UintsVar(target *[]uint)
- func (p *FlagClause) UnNegatableBool() (target *bool)
- func (p *FlagClause) UnNegatableBoolList() (target *[]bool)
- func (p *FlagClause) UnNegatableBoolListVar(target *[]bool)
- func (p *FlagClause) UnNegatableBoolVar(target *bool)
- func (f *FlagClause) Validator(validator OptionValidator) *FlagClause
- type FlagGroupModel
- type FlagModel
- type Getter
- type HintAction
- type OptionValidator
- type ParseContext
- type ParseElement
- type Settings
- type Text
- type Token
- type TokenType
- type Value
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnknownLongFlag indicates an unknown long form flag was passed ErrUnknownLongFlag = errors.New("unknown long flag") // ErrUnknownShortFlag indicates an unknown short form flag was passed ErrUnknownShortFlag = errors.New("unknown short flag") // ErrExpectedFlagArgument indicates a flag requiring an argument did not have one supplied ErrExpectedFlagArgument = errors.New("expected argument for flag") // ErrCommandNotSpecified indicates a command was expected ErrCommandNotSpecified = fmt.Errorf("command not specified") // ErrSubCommandRequired indicates that a command was invoked, but it required a sub command ErrSubCommandRequired = errors.New("must select a subcommand") // ErrRequiredArgument indicates a required argument was not given ErrRequiredArgument = errors.New("required argument") // ErrRequiredFlag indicates a required flag was not given ErrRequiredFlag = errors.New("required flag") // ErrExpectedKnownCommand indicates that an unknown command argument was encountered ErrExpectedKnownCommand = errors.New("expected command") // ErrFlagCannotRepeat indicates a flag cannot be passed multiple times to fill an array ErrFlagCannotRepeat = errors.New("cannot be repeated") // ErrUnexpectedArgument indicates an unexpected argument was encountered ErrUnexpectedArgument = errors.New("unexpected argument") )
var ( // CommandLine is the default fisk parser. CommandLine = New(filepath.Base(os.Args[0]), "") // HelpFlag global help flag. Exposed for user customisation. HelpFlag = CommandLine.HelpFlag // HelpCommand Top-level help command. Exposed for user customisation. May be nil. HelpCommand = CommandLine.HelpCommand // VersionFlag global version flag. Exposed for user customisation. May be nil. VersionFlag = CommandLine.VersionFlag // EnableFileExpansion whether to file expansion with '@' is enabled. EnableFileExpansion = true )
var BashCompletionTemplate = `` /* 340-byte string literal not displayed */
var CompactMainUsageTemplate = `` /* 1467-byte string literal not displayed */
CompactMainUsageTemplate formats commands and subcommands in a two column layout to make for a cleaners and more readable usage text. In this format, sections are rendered as follows. Global flags are also separate from local flags in this template. Global flags will be shown at the top level and local flags will be shown when showing help for a subcommand.
usage: <command> [<flags>] <command> [<arg> ...]
Help text ¶
Commands|Subcommands:
command1 Help text for command 1 command2 Help text for command 2 command2 Help text for command 3
Flags:
-h, --help Show context-sensitive help
var CompactUsageTemplate = `` /* 1369-byte string literal not displayed */
CompactUsageTemplate is a usage template with compactly formatted commands.
var KingpinDefaultUsageTemplate = `` /* 1299-byte string literal not displayed */
KingpinDefaultUsageTemplate is the default usage template as used by kingpin
var LongHelpTemplate = `` /* 1033-byte string literal not displayed */
LongHelpTemplate is a usage template for --help-long
var ManPageTemplate = `` /* 1161-byte string literal not displayed */
ManPageTemplate renders usage in unix man format
var SeparateOptionalFlagsUsageTemplate = `` /* 1452-byte string literal not displayed */
SeparateOptionalFlagsUsageTemplate is a usage template where command's optional flags are listed separately
var ShorterMainUsageTemplate = `` /* 1582-byte string literal not displayed */
ShorterMainUsageTemplate is similar to KingpinDefaultUsageTemplate except in the main app usage output it does not expand full help text for every single sub command all the way to the deepest leve, it also does not show global flags in the top app.
Additionally, it supports the new HelpLong on sub commands so one can either rely on it always printing just the first line of sub command help or only putting short help in the main help and long help in long - the long will only be shown when it's rendering usage for that command when it's the command the user is executing (select).
This yields a friendlier welcome to new users with the details should they do help on any sub command
var (
TokenEOLMarker = Token{-1, TokenEOL, ""}
)
var ZshCompletionTemplate = `` /* 350-byte string literal not displayed */
Functions ¶
func Errorf ¶
func Errorf(format string, args ...interface{})
Errorf prints an error message to stderr.
func ExpandArgsFromFile ¶
ExpandArgsFromFile expand arguments from a file. Lines starting with # will be treated as comments.
func FatalIfError ¶
FatalIfError prints an error and exits if err is not nil. The error is printed with the given prefix.
func FatalUsage ¶
func FatalUsage(format string, args ...interface{})
FatalUsage prints an error message followed by usage information, then exits with a non-zero status.
func FatalUsageContext ¶
func FatalUsageContext(context *ParseContext, format string, args ...interface{})
FatalUsageContext writes a printf formatted error message to stderr, then usage information for the given ParseContext, before exiting.
func Fatalf ¶
func Fatalf(format string, args ...interface{})
Fatalf prints an error message to stderr and exits.
func Parse ¶
func Parse() string
Parse and return the selected command. Will call the termination handler if an error is encountered.
func ParseDuration ¶ added in v0.1.3
ParseDuration parse durations with additional units over those from standard go parser.
In addition to normal go parser time units it also supports these.
The reason these are not in go standard lib is due to precision around how many days in a month and about leap years and leap seconds. This function does nothing to try and correct for those.
* "w", "W" - a week based on 7 days of exactly 24 hours * "d", "D" - a day based on 24 hours * "M" - a month made of 30 days of 24 hours * "y", "Y" - a year made of 365 days of 24 hours each
Valid duration strings can be -1y1d1µs
Types ¶
type Action ¶
type Action func(*ParseContext) error
Action callback executed at various stages after all values are populated. The application, commands, arguments and flags all have corresponding actions.
type Application ¶
type Application struct { Name string Help string // Help flag. Exposed for user customisation. HelpFlag *FlagClause // Help command. Exposed for user customisation. May be nil. HelpCommand *CmdClause // Version flag. Exposed for user customisation. May be nil. VersionFlag *FlagClause // Cheat command. Exposed for user customisation. May be nil. CheatCommand *CmdClause // contains filtered or unexported fields }
An Application contains the definitions of flags, arguments and commands for an application.
func Newf ¶ added in v0.1.1
func Newf(name string, format string, a ...interface{}) *Application
Newf creates a new application with printf parsing of the help
func UsageTemplate ¶
func UsageTemplate(template string) *Application
UsageTemplate Set global usage template to use (defaults to ShorterMainUsageTemplate).
func Version ¶
func Version(version string) *Application
Version adds a flag for displaying the application version number.
func (*Application) Action ¶
func (a *Application) Action(action Action) *Application
Action callback to call when all values are populated and parsing is complete, but before any command, flag or argument actions.
All Action() callbacks are called in the order they are encountered on the command line.
func (*Application) Author ¶
func (a *Application) Author(author string) *Application
Author sets the author output by some help templates.
func (*Application) Cheat ¶ added in v0.1.1
func (a *Application) Cheat(cheat string, help string) *Application
Cheat sets the cheat help text to associate with this application, the cheat is the name it will be surfaced as in help, if empty its the name of the application.
func (*Application) CheatFile ¶ added in v0.1.1
func (a *Application) CheatFile(fs fs.ReadFileFS, cheat string, file string) *Application
CheatFile reads a file from fs and use its contents to call Cheat(). Read errors are fatal.
func (*Application) CmdCompletion ¶
func (c *Application) CmdCompletion(context *ParseContext) []string
CmdCompletion returns completion options for arguments, if that's where parsing left off, or commands if there aren't any unsatisfied args.
func (*Application) Command ¶
func (a *Application) Command(name, help string) *CmdClause
Command adds a new top-level command.
func (*Application) Commandf ¶ added in v0.1.1
func (a *Application) Commandf(name string, format string, arg ...interface{}) *CmdClause
Commandf adds a new top-level command with printf parsing of help
func (*Application) DefaultEnvars ¶
func (a *Application) DefaultEnvars() *Application
DefaultEnvars configures all flags (that do not already have an associated envar) to use a default environment variable in the form "<app>_<flag>".
For example, if the application is named "foo" and a flag is named "bar- waz" the environment variable: "FOO_BAR_WAZ".
func (*Application) ErrorUsageTemplate ¶ added in v0.2.0
func (a *Application) ErrorUsageTemplate(template string) *Application
ErrorUsageTemplate specifies the text template to use when displaying usage information after an ErrSubCommandRequired ErrExpectedKnownCommand. The default is compactWithoutFlagsOrArgs.
func (*Application) ErrorWriter ¶
func (a *Application) ErrorWriter(w io.Writer) *Application
ErrorWriter sets the io.Writer to use for errors.
func (*Application) Errorf ¶
func (a *Application) Errorf(format string, args ...interface{})
Errorf prints an error message to w in the format "<appname>: error: <message>".
func (*Application) ExternalPluginCommand ¶ added in v0.5.0
func (a *Application) ExternalPluginCommand(command string, model json.RawMessage, name string, help string) (*CmdClause, error)
ExternalPluginCommand extends the application using a plugin and a model describing the application, when name or help is not an empty string it will override that from the plugin
func (*Application) FatalIfError ¶
func (a *Application) FatalIfError(err error, format string, args ...interface{})
FatalIfError prints an error and exits if err is not nil. The error is printed with the given formatted string, if any.
func (*Application) FatalUsage ¶
func (a *Application) FatalUsage(format string, args ...interface{})
FatalUsage prints an error message followed by usage information, then exits with a non-zero status.
func (*Application) FatalUsageContext ¶
func (a *Application) FatalUsageContext(context *ParseContext, format string, args ...interface{})
FatalUsageContext writes a printf formatted error message to w, then usage information for the given ParseContext, before exiting.
func (*Application) Fatalf ¶
func (a *Application) Fatalf(format string, args ...interface{})
Fatalf writes a formatted error to w then terminates with exit status 1.
func (*Application) FlagCompletion ¶
func (*Application) Interspersed ¶
func (a *Application) Interspersed(interspersed bool) *Application
Interspersed control if flags can be interspersed with positional arguments
true (the default) means that they can, false means that all the flags must appear before the first positional arguments.
func (*Application) Model ¶
func (a *Application) Model() *ApplicationModel
func (*Application) MustParseWithUsage ¶ added in v0.1.4
func (a *Application) MustParseWithUsage(args []string) (command string)
MustParseWithUsage parses args using Parse() and shows usage on certain errors
When a parent command with no action is called a compact usage will be shown listing the subcommands available without any flags or arguments allowing a user to quickly evaluate the next command to use, this is to assist in discovering the layout and design of a CLI tool.
When a various argument of flag errors are encountered an error is shown followed by the full help for that command showing available arguments and flags.
All other errors just shows the error.
func (*Application) Parse ¶
func (a *Application) Parse(args []string) (command string, err error)
Parse parses command-line arguments. It returns the selected command and an error. The selected command will be a space separated subcommand, if subcommands have been configured.
This will populate all flag and argument values, call all callbacks, and so on.
func (*Application) ParseContext ¶
func (a *Application) ParseContext(args []string) (*ParseContext, error)
ParseContext parses the given command line and returns the fully populated ParseContext.
func (*Application) PreAction ¶
func (a *Application) PreAction(action Action) *Application
PreAction action called after parsing completes but before validation and execution.
func (*Application) Terminate ¶
func (a *Application) Terminate(terminate func(int)) *Application
Terminate specifies the termination handler. Defaults to os.Exit(status). If nil is passed, a no-op function will be used.
func (*Application) Usage ¶
func (a *Application) Usage(args []string)
Usage writes application usage to w. It parses args to determine appropriate help context, such as which command to show help for.
func (*Application) UsageForContext ¶
func (a *Application) UsageForContext(context *ParseContext) error
UsageForContext displays usage information from a ParseContext (obtained from Application.ParseContext() or Action(f) callbacks).
func (*Application) UsageForContextWithTemplate ¶
func (a *Application) UsageForContextWithTemplate(context *ParseContext, indent int, tmpl string) error
UsageForContextWithTemplate is the base usage function. You generally don't need to use this.
func (*Application) UsageFuncs ¶ added in v0.1.0
func (a *Application) UsageFuncs(funcs template.FuncMap) *Application
UsageFuncs adds extra functions that can be used in the usage template.
func (*Application) UsageTemplate ¶
func (a *Application) UsageTemplate(template string) *Application
UsageTemplate specifies the text template to use when displaying usage information. The default is UsageTemplate.
func (*Application) UsageWriter ¶
func (a *Application) UsageWriter(w io.Writer) *Application
UsageWriter sets the io.Writer to use for errors.
func (*Application) Validate ¶
func (a *Application) Validate(validator ApplicationValidator) *Application
Validate sets a validation function to run when parsing.
func (*Application) Version ¶
func (a *Application) Version(version string) *Application
Version adds a --version flag for displaying the application version.
func (*Application) WithCheats ¶ added in v0.1.1
func (a *Application) WithCheats(tags ...string) *Application
WithCheats enables support for rendering cheat compatible output, tags can be supplied which would be set when saving cheat files
See https://github.com/cheat/cheat for information about this format
func (*Application) Writer ¶
func (a *Application) Writer(w io.Writer) *Application
Writer specifies the writer to use for usage and errors. Defaults to os.Stderr. DEPRECATED: See ErrorWriter and UsageWriter.
type ApplicationModel ¶
type ApplicationModel struct { Name string `json:"name"` Help string `json:"help"` Cheat string `json:"cheat,omitempty"` Version string `json:"version,omitempty"` Author string `json:"author,omitempty"` Cheats map[string]string `json:"cheats,omitempty"` CheatTags []string `json:"cheat_tags,omitempty"` *ArgGroupModel *CmdGroupModel *FlagGroupModel }
type ApplicationValidator ¶
type ApplicationValidator func(*Application) error
ApplicationValidator can be used to validate entire application during parsing
type ArgClause ¶
type ArgClause struct {
// contains filtered or unexported fields
}
func (*ArgClause) Bool ¶
func (p *ArgClause) Bool() (target *bool)
Bool parses the next command-line value as bool.
func (*ArgClause) BoolList ¶
func (p *ArgClause) BoolList() (target *[]bool)
BoolList accumulates bool values into a slice.
func (*ArgClause) BoolListVar ¶
func (p *ArgClause) BoolListVar(target *[]bool)
func (*ArgClause) Bytes ¶
func (p *ArgClause) Bytes() (target *units.Base2Bytes)
Bytes parses numeric byte units. eg. 1.5KB
func (*ArgClause) BytesVar ¶
func (p *ArgClause) BytesVar(target *units.Base2Bytes)
BytesVar parses numeric byte units. eg. 1.5KB
func (*ArgClause) Counter ¶
func (p *ArgClause) Counter() (target *int)
A Counter increments a number each time it is encountered.
func (*ArgClause) CounterVar ¶
func (p *ArgClause) CounterVar(target *int)
func (*ArgClause) Default ¶
Default values for this argument. They *must* be parseable by the value of the argument.
func (*ArgClause) DurationList ¶
DurationList accumulates time.Duration values into a slice.
func (*ArgClause) DurationListVar ¶
func (*ArgClause) DurationVar ¶
Duration sets the parser to a time.Duration parser.
func (*ArgClause) Envar ¶
Envar overrides the default value(s) for a flag from an environment variable, if it is set. Several default values can be provided by using new lines to separate them.
func (*ArgClause) ExistingDir ¶
func (p *ArgClause) ExistingDir() (target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*ArgClause) ExistingDirVar ¶
func (p *ArgClause) ExistingDirVar(target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*ArgClause) ExistingDirs ¶
func (p *ArgClause) ExistingDirs() (target *[]string)
ExistingDirs accumulates string values into a slice.
func (*ArgClause) ExistingDirsVar ¶
func (p *ArgClause) ExistingDirsVar(target *[]string)
func (*ArgClause) ExistingFile ¶
func (p *ArgClause) ExistingFile() (target *string)
ExistingFile sets the parser to one that requires and returns an existing file.
func (*ArgClause) ExistingFileOrDir ¶
func (p *ArgClause) ExistingFileOrDir() (target *string)
ExistingFileOrDir sets the parser to one that requires and returns an existing file OR directory.
func (*ArgClause) ExistingFileOrDirVar ¶
func (p *ArgClause) ExistingFileOrDirVar(target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*ArgClause) ExistingFileVar ¶
func (p *ArgClause) ExistingFileVar(target *string)
ExistingFile sets the parser to one that requires and returns an existing file.
func (*ArgClause) ExistingFiles ¶
func (p *ArgClause) ExistingFiles() (target *[]string)
ExistingFiles accumulates string values into a slice.
func (*ArgClause) ExistingFilesOrDirs ¶
func (p *ArgClause) ExistingFilesOrDirs() (target *[]string)
ExistingFilesOrDirs accumulates string values into a slice.
func (*ArgClause) ExistingFilesOrDirsVar ¶
func (p *ArgClause) ExistingFilesOrDirsVar(target *[]string)
func (*ArgClause) ExistingFilesVar ¶
func (p *ArgClause) ExistingFilesVar(target *[]string)
func (*ArgClause) Float ¶
func (p *ArgClause) Float() (target *float64)
Float sets the parser to a float64 parser.
func (*ArgClause) Float32 ¶
func (p *ArgClause) Float32() (target *float32)
Float32 parses the next command-line value as float32.
func (*ArgClause) Float32List ¶
func (p *ArgClause) Float32List() (target *[]float32)
Float32List accumulates float32 values into a slice.
func (*ArgClause) Float32ListVar ¶
func (p *ArgClause) Float32ListVar(target *[]float32)
func (*ArgClause) Float32Var ¶
func (p *ArgClause) Float32Var(target *float32)
func (*ArgClause) Float64 ¶
func (p *ArgClause) Float64() (target *float64)
Float64 parses the next command-line value as float64.
func (*ArgClause) Float64List ¶
func (p *ArgClause) Float64List() (target *[]float64)
Float64List accumulates float64 values into a slice.
func (*ArgClause) Float64ListVar ¶
func (p *ArgClause) Float64ListVar(target *[]float64)
func (*ArgClause) Float64Var ¶
func (p *ArgClause) Float64Var(target *float64)
func (*ArgClause) FloatVar ¶
func (p *ArgClause) FloatVar(target *float64)
Float sets the parser to a float64 parser.
func (*ArgClause) GetEnvarValue ¶
func (e *ArgClause) GetEnvarValue() string
func (*ArgClause) GetSplitEnvarValue ¶
func (e *ArgClause) GetSplitEnvarValue() []string
func (*ArgClause) HasEnvarValue ¶
func (e *ArgClause) HasEnvarValue() bool
func (*ArgClause) HexBytesList ¶
func (p *ArgClause) HexBytesList() (target *[][]byte)
HexBytesList accumulates []byte values into a slice.
func (*ArgClause) HexBytesListVar ¶
func (p *ArgClause) HexBytesListVar(target *[][]byte)
func (*ArgClause) HexBytesVar ¶
func (p *ArgClause) HexBytesVar(target *[]byte)
func (*ArgClause) Hidden ¶ added in v0.1.0
Hidden hides the argument from usage but still allows it to be used.
func (*ArgClause) HintAction ¶
func (a *ArgClause) HintAction(action HintAction) *ArgClause
HintAction registers a HintAction (function) for the arg to provide completions
func (*ArgClause) HintOptions ¶
HintOptions registers any number of options for the flag to provide completions
func (*ArgClause) Int ¶
func (p *ArgClause) Int() (target *int)
Int parses the next command-line value as int.
func (*ArgClause) Int16 ¶
func (p *ArgClause) Int16() (target *int16)
Int16 parses the next command-line value as int16.
func (*ArgClause) Int16List ¶
func (p *ArgClause) Int16List() (target *[]int16)
Int16List accumulates int16 values into a slice.
func (*ArgClause) Int16ListVar ¶
func (p *ArgClause) Int16ListVar(target *[]int16)
func (*ArgClause) Int32 ¶
func (p *ArgClause) Int32() (target *int32)
Int32 parses the next command-line value as int32.
func (*ArgClause) Int32List ¶
func (p *ArgClause) Int32List() (target *[]int32)
Int32List accumulates int32 values into a slice.
func (*ArgClause) Int32ListVar ¶
func (p *ArgClause) Int32ListVar(target *[]int32)
func (*ArgClause) Int64 ¶
func (p *ArgClause) Int64() (target *int64)
Int64 parses the next command-line value as int64.
func (*ArgClause) Int64List ¶
func (p *ArgClause) Int64List() (target *[]int64)
Int64List accumulates int64 values into a slice.
func (*ArgClause) Int64ListVar ¶
func (p *ArgClause) Int64ListVar(target *[]int64)
func (*ArgClause) Int8 ¶
func (p *ArgClause) Int8() (target *int8)
Int8 parses the next command-line value as int8.
func (*ArgClause) Int8List ¶
func (p *ArgClause) Int8List() (target *[]int8)
Int8List accumulates int8 values into a slice.
func (*ArgClause) Int8ListVar ¶
func (p *ArgClause) Int8ListVar(target *[]int8)
func (*ArgClause) Ints ¶
func (p *ArgClause) Ints() (target *[]int)
Ints accumulates int values into a slice.
func (*ArgClause) NoEnvar ¶
NoEnvar forces environment variable defaults to be disabled for this flag. Most useful in conjunction with app.DefaultEnvars().
func (*ArgClause) OpenFileVar ¶
OpenFileVar calls os.OpenFile(flag, perm)
func (*ArgClause) PlaceHolder ¶ added in v0.1.0
PlaceHolder sets the place-holder string used for arg values in the help. The default behavior is to use the arg name between < > brackets.
func (*ArgClause) RegexpList ¶
RegexpList accumulates *regexp.Regexp values into a slice.
func (*ArgClause) RegexpListVar ¶
func (*ArgClause) Required ¶
Required arguments must be input by the user. They can not have a Default() value provided.
func (*ArgClause) ResolvedIP ¶
Resolve a hostname or IP to an IP.
func (*ArgClause) ResolvedIPList ¶
ResolvedIPList accumulates net.IP values into a slice.
func (*ArgClause) ResolvedIPListVar ¶
func (*ArgClause) ResolvedIPVar ¶
func (*ArgClause) String ¶
func (p *ArgClause) String() (target *string)
String parses the next command-line value as string.
func (*ArgClause) StringMapVar ¶
StringMap provides key=value parsing into a map.
func (*ArgClause) Strings ¶
func (p *ArgClause) Strings() (target *[]string)
Strings accumulates string values into a slice.
func (*ArgClause) StringsVar ¶
func (p *ArgClause) StringsVar(target *[]string)
func (*ArgClause) TCPListVar ¶
func (*ArgClause) URLListVar ¶
URLListVar provides a parsed list of url.URL values.
func (*ArgClause) Uint ¶
func (p *ArgClause) Uint() (target *uint)
Uint parses the next command-line value as uint.
func (*ArgClause) Uint16 ¶
func (p *ArgClause) Uint16() (target *uint16)
Uint16 parses the next command-line value as uint16.
func (*ArgClause) Uint16List ¶
func (p *ArgClause) Uint16List() (target *[]uint16)
Uint16List accumulates uint16 values into a slice.
func (*ArgClause) Uint16ListVar ¶
func (p *ArgClause) Uint16ListVar(target *[]uint16)
func (*ArgClause) Uint32 ¶
func (p *ArgClause) Uint32() (target *uint32)
Uint32 parses the next command-line value as uint32.
func (*ArgClause) Uint32List ¶
func (p *ArgClause) Uint32List() (target *[]uint32)
Uint32List accumulates uint32 values into a slice.
func (*ArgClause) Uint32ListVar ¶
func (p *ArgClause) Uint32ListVar(target *[]uint32)
func (*ArgClause) Uint64 ¶
func (p *ArgClause) Uint64() (target *uint64)
Uint64 parses the next command-line value as uint64.
func (*ArgClause) Uint64List ¶
func (p *ArgClause) Uint64List() (target *[]uint64)
Uint64List accumulates uint64 values into a slice.
func (*ArgClause) Uint64ListVar ¶
func (p *ArgClause) Uint64ListVar(target *[]uint64)
func (*ArgClause) Uint8 ¶
func (p *ArgClause) Uint8() (target *uint8)
Uint8 parses the next command-line value as uint8.
func (*ArgClause) Uint8List ¶
func (p *ArgClause) Uint8List() (target *[]uint8)
Uint8List accumulates uint8 values into a slice.
func (*ArgClause) Uint8ListVar ¶
func (p *ArgClause) Uint8ListVar(target *[]uint8)
func (*ArgClause) Uints ¶
func (p *ArgClause) Uints() (target *[]uint)
Uints accumulates uint values into a slice.
func (*ArgClause) UnNegatableBool ¶ added in v0.1.2
func (p *ArgClause) UnNegatableBool() (target *bool)
UnNegatableBool parses the next command-line value as bool.
func (*ArgClause) UnNegatableBoolList ¶ added in v0.1.2
func (p *ArgClause) UnNegatableBoolList() (target *[]bool)
UnNegatableBoolList accumulates bool values into a slice.
func (*ArgClause) UnNegatableBoolListVar ¶ added in v0.1.2
func (p *ArgClause) UnNegatableBoolListVar(target *[]bool)
func (*ArgClause) UnNegatableBoolVar ¶ added in v0.1.2
func (p *ArgClause) UnNegatableBoolVar(target *bool)
func (*ArgClause) Validator ¶ added in v0.6.0
func (a *ArgClause) Validator(validator OptionValidator) *ArgClause
type ArgGroupModel ¶
type ArgGroupModel struct {
Args []*ArgModel `json:"args,omitempty"`
}
func (*ArgGroupModel) ArgSummary ¶
func (a *ArgGroupModel) ArgSummary() string
type ArgModel ¶
type ArgModel struct { Name string `json:"name"` Help string `json:"help"` Default []string `json:"default,omitempty"` Envar string `json:"envar,omitempty"` PlaceHolder string `json:"place_holder,omitempty"` Required bool `json:"required,omitempty"` Hidden bool `json:"hidden,omitempty"` Value Value `json:"-"` // used by plugin model Cumulative bool `json:"cumulative"` }
func (*ArgModel) HelpWithEnvar ¶ added in v0.1.0
func (*ArgModel) IsCumulative ¶ added in v0.5.0
type BoolFlag ¶ added in v0.1.2
type BoolFlag interface { // BoolFlagIsNegatable Specify if the flag is negatable (ie. supports both --no-<name> and --name). BoolFlagIsNegatable() bool }
BoolFlag is an optional interface to specify that a flag is a boolean flag.
type CmdClause ¶
type CmdClause struct {
// contains filtered or unexported fields
}
A CmdClause is a single top-level command. It encapsulates a set of flags and either subcommands or positional arguments.
func (*CmdClause) Cheat ¶ added in v0.1.1
Cheat sets the cheat help text to associate with this command, the cheat is the name it will be surfaced as in help, if empty it's the name of the command.
func (*CmdClause) CheatFile ¶ added in v0.1.1
CheatFile reads a file from fs and use its contents to call Cheat(). Read errors are fatal.
func (*CmdClause) CmdCompletion ¶
func (c *CmdClause) CmdCompletion(context *ParseContext) []string
CmdCompletion returns completion options for arguments, if that's where parsing left off, or commands if there aren't any unsatisfied args.
func (*CmdClause) Commandf ¶ added in v0.1.1
Commandf adds a new sub-command with printf parsing of help
func (*CmdClause) FlagCompletion ¶
func (*CmdClause) FullCommand ¶
func (*CmdClause) HelpLong ¶ added in v0.1.0
HelpLong adds a long help text, which can be used in usage templates. For example, to use a longer help text in the command-specific help than in the apps root help.
func (*CmdClause) Validate ¶
func (c *CmdClause) Validate(validator CmdClauseValidator) *CmdClause
Validate sets a validation function to run when parsing.
type CmdClauseValidator ¶
type CmdGroupModel ¶
type CmdGroupModel struct {
Commands []*CmdModel `json:"commands,omitempty"`
}
func (*CmdGroupModel) FlattenedCommands ¶
func (c *CmdGroupModel) FlattenedCommands() (out []*CmdModel)
type CmdModel ¶
type CmdModel struct { Name string `json:"name"` Aliases []string `json:"aliases,omitempty"` Help string `json:"help"` HelpLong string `json:"help_long,omitempty"` FullCommand string `json:"-"` Depth int `json:"-"` Hidden bool `json:"hidden,omitempty"` Default bool `json:"default,omitempty"` *FlagGroupModel *ArgGroupModel *CmdGroupModel }
type FlagClause ¶
type FlagClause struct {
// contains filtered or unexported fields
}
FlagClause is a fluid interface used to build flags.
func (*FlagClause) Action ¶
func (f *FlagClause) Action(action Action) *FlagClause
Dispatch to the given function after the flag is parsed and validated.
func (*FlagClause) Bool ¶
func (f *FlagClause) Bool() (target *bool)
Bool makes this flag a boolean flag.
func (*FlagClause) BoolList ¶
func (p *FlagClause) BoolList() (target *[]bool)
BoolList accumulates bool values into a slice.
func (*FlagClause) BoolListVar ¶
func (p *FlagClause) BoolListVar(target *[]bool)
func (*FlagClause) Bytes ¶
func (p *FlagClause) Bytes() (target *units.Base2Bytes)
Bytes parses numeric byte units. eg. 1.5KB
func (*FlagClause) BytesVar ¶
func (p *FlagClause) BytesVar(target *units.Base2Bytes)
BytesVar parses numeric byte units. eg. 1.5KB
func (*FlagClause) Counter ¶
func (p *FlagClause) Counter() (target *int)
A Counter increments a number each time it is encountered.
func (*FlagClause) CounterVar ¶
func (p *FlagClause) CounterVar(target *int)
func (*FlagClause) Default ¶
func (f *FlagClause) Default(values ...string) *FlagClause
Default values for this flag. They *must* be parseable by the value of the flag.
func (*FlagClause) DurationList ¶
DurationList accumulates time.Duration values into a slice.
func (*FlagClause) DurationListVar ¶
func (*FlagClause) DurationVar ¶
Duration sets the parser to a time.Duration parser.
func (*FlagClause) Enum ¶
func (a *FlagClause) Enum(options ...string) (target *string)
func (*FlagClause) EnumVar ¶
func (a *FlagClause) EnumVar(target *string, options ...string)
func (*FlagClause) Envar ¶
func (f *FlagClause) Envar(name string) *FlagClause
Envar overrides the default value(s) for a flag from an environment variable, if it is set. Several default values can be provided by using new lines to separate them.
func (*FlagClause) ExistingDir ¶
func (p *FlagClause) ExistingDir() (target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*FlagClause) ExistingDirVar ¶
func (p *FlagClause) ExistingDirVar(target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*FlagClause) ExistingDirs ¶
func (p *FlagClause) ExistingDirs() (target *[]string)
ExistingDirs accumulates string values into a slice.
func (*FlagClause) ExistingDirsVar ¶
func (p *FlagClause) ExistingDirsVar(target *[]string)
func (*FlagClause) ExistingFile ¶
func (p *FlagClause) ExistingFile() (target *string)
ExistingFile sets the parser to one that requires and returns an existing file.
func (*FlagClause) ExistingFileOrDir ¶
func (p *FlagClause) ExistingFileOrDir() (target *string)
ExistingFileOrDir sets the parser to one that requires and returns an existing file OR directory.
func (*FlagClause) ExistingFileOrDirVar ¶
func (p *FlagClause) ExistingFileOrDirVar(target *string)
ExistingDir sets the parser to one that requires and returns an existing directory.
func (*FlagClause) ExistingFileVar ¶
func (p *FlagClause) ExistingFileVar(target *string)
ExistingFile sets the parser to one that requires and returns an existing file.
func (*FlagClause) ExistingFiles ¶
func (p *FlagClause) ExistingFiles() (target *[]string)
ExistingFiles accumulates string values into a slice.
func (*FlagClause) ExistingFilesOrDirs ¶
func (p *FlagClause) ExistingFilesOrDirs() (target *[]string)
ExistingFilesOrDirs accumulates string values into a slice.
func (*FlagClause) ExistingFilesOrDirsVar ¶
func (p *FlagClause) ExistingFilesOrDirsVar(target *[]string)
func (*FlagClause) ExistingFilesVar ¶
func (p *FlagClause) ExistingFilesVar(target *[]string)
func (*FlagClause) Float ¶
func (p *FlagClause) Float() (target *float64)
Float sets the parser to a float64 parser.
func (*FlagClause) Float32 ¶
func (p *FlagClause) Float32() (target *float32)
Float32 parses the next command-line value as float32.
func (*FlagClause) Float32List ¶
func (p *FlagClause) Float32List() (target *[]float32)
Float32List accumulates float32 values into a slice.
func (*FlagClause) Float32ListVar ¶
func (p *FlagClause) Float32ListVar(target *[]float32)
func (*FlagClause) Float32Var ¶
func (p *FlagClause) Float32Var(target *float32)
func (*FlagClause) Float64 ¶
func (p *FlagClause) Float64() (target *float64)
Float64 parses the next command-line value as float64.
func (*FlagClause) Float64List ¶
func (p *FlagClause) Float64List() (target *[]float64)
Float64List accumulates float64 values into a slice.
func (*FlagClause) Float64ListVar ¶
func (p *FlagClause) Float64ListVar(target *[]float64)
func (*FlagClause) Float64Var ¶
func (p *FlagClause) Float64Var(target *float64)
func (*FlagClause) FloatVar ¶
func (p *FlagClause) FloatVar(target *float64)
Float sets the parser to a float64 parser.
func (*FlagClause) GetEnvarValue ¶
func (e *FlagClause) GetEnvarValue() string
func (*FlagClause) GetSplitEnvarValue ¶
func (e *FlagClause) GetSplitEnvarValue() []string
func (*FlagClause) HasEnvarValue ¶
func (e *FlagClause) HasEnvarValue() bool
func (*FlagClause) Help ¶ added in v0.1.0
func (f *FlagClause) Help(help string) *FlagClause
Help sets the help message.
func (*FlagClause) HexBytes ¶
func (p *FlagClause) HexBytes() (target *[]byte)
Bytes as a hex string.
func (*FlagClause) HexBytesList ¶
func (p *FlagClause) HexBytesList() (target *[][]byte)
HexBytesList accumulates []byte values into a slice.
func (*FlagClause) HexBytesListVar ¶
func (p *FlagClause) HexBytesListVar(target *[][]byte)
func (*FlagClause) HexBytesVar ¶
func (p *FlagClause) HexBytesVar(target *[]byte)
func (*FlagClause) Hidden ¶
func (f *FlagClause) Hidden() *FlagClause
Hidden hides a flag from usage but still allows it to be used.
func (*FlagClause) HintAction ¶
func (a *FlagClause) HintAction(action HintAction) *FlagClause
HintAction registers a HintAction (function) for the flag to provide completions
func (*FlagClause) HintOptions ¶
func (a *FlagClause) HintOptions(options ...string) *FlagClause
HintOptions registers any number of options for the flag to provide completions
func (*FlagClause) Int ¶
func (p *FlagClause) Int() (target *int)
Int parses the next command-line value as int.
func (*FlagClause) Int16 ¶
func (p *FlagClause) Int16() (target *int16)
Int16 parses the next command-line value as int16.
func (*FlagClause) Int16List ¶
func (p *FlagClause) Int16List() (target *[]int16)
Int16List accumulates int16 values into a slice.
func (*FlagClause) Int16ListVar ¶
func (p *FlagClause) Int16ListVar(target *[]int16)
func (*FlagClause) Int32 ¶
func (p *FlagClause) Int32() (target *int32)
Int32 parses the next command-line value as int32.
func (*FlagClause) Int32List ¶
func (p *FlagClause) Int32List() (target *[]int32)
Int32List accumulates int32 values into a slice.
func (*FlagClause) Int32ListVar ¶
func (p *FlagClause) Int32ListVar(target *[]int32)
func (*FlagClause) Int64 ¶
func (p *FlagClause) Int64() (target *int64)
Int64 parses the next command-line value as int64.
func (*FlagClause) Int64List ¶
func (p *FlagClause) Int64List() (target *[]int64)
Int64List accumulates int64 values into a slice.
func (*FlagClause) Int64ListVar ¶
func (p *FlagClause) Int64ListVar(target *[]int64)
func (*FlagClause) Int8 ¶
func (p *FlagClause) Int8() (target *int8)
Int8 parses the next command-line value as int8.
func (*FlagClause) Int8List ¶
func (p *FlagClause) Int8List() (target *[]int8)
Int8List accumulates int8 values into a slice.
func (*FlagClause) Int8ListVar ¶
func (p *FlagClause) Int8ListVar(target *[]int8)
func (*FlagClause) Ints ¶
func (p *FlagClause) Ints() (target *[]int)
Ints accumulates int values into a slice.
func (*FlagClause) IsSetByUser ¶ added in v0.1.0
func (f *FlagClause) IsSetByUser(setByUser *bool) *FlagClause
IsSetByUser let to know if the flag was set by the user
func (*FlagClause) Model ¶
func (f *FlagClause) Model() *FlagModel
func (*FlagClause) NoEnvar ¶
func (f *FlagClause) NoEnvar() *FlagClause
NoEnvar forces environment variable defaults to be disabled for this flag. Most useful in conjunction with app.DefaultEnvars().
func (*FlagClause) OpenFileVar ¶
OpenFileVar calls os.OpenFile(flag, perm)
func (*FlagClause) OverrideDefaultFromEnvar ¶
func (f *FlagClause) OverrideDefaultFromEnvar(envar string) *FlagClause
DEPRECATED: Use Envar(name) instead.
func (*FlagClause) PlaceHolder ¶
func (f *FlagClause) PlaceHolder(placeholder string) *FlagClause
PlaceHolder sets the place-holder string used for flag values in the help. The default behavior is to use the value provided by Default() if provided, then fall back on the capitalized flag name.
func (*FlagClause) PreAction ¶
func (f *FlagClause) PreAction(action Action) *FlagClause
func (*FlagClause) RegexpList ¶
RegexpList accumulates *regexp.Regexp values into a slice.
func (*FlagClause) RegexpListVar ¶
func (*FlagClause) Required ¶
func (f *FlagClause) Required() *FlagClause
Required makes the flag required. You can not provide a Default() value to a Required() flag.
func (*FlagClause) ResolvedIP ¶
Resolve a hostname or IP to an IP.
func (*FlagClause) ResolvedIPList ¶
ResolvedIPList accumulates net.IP values into a slice.
func (*FlagClause) ResolvedIPListVar ¶
func (*FlagClause) ResolvedIPVar ¶
func (*FlagClause) Short ¶
func (f *FlagClause) Short(name rune) *FlagClause
Short sets the short flag name.
func (*FlagClause) String ¶
func (p *FlagClause) String() (target *string)
String parses the next command-line value as string.
func (*FlagClause) StringMapVar ¶
StringMap provides key=value parsing into a map.
func (*FlagClause) Strings ¶
func (p *FlagClause) Strings() (target *[]string)
Strings accumulates string values into a slice.
func (*FlagClause) StringsVar ¶
func (p *FlagClause) StringsVar(target *[]string)
func (*FlagClause) TCPListVar ¶
func (*FlagClause) URLListVar ¶
URLListVar provides a parsed list of url.URL values.
func (*FlagClause) Uint ¶
func (p *FlagClause) Uint() (target *uint)
Uint parses the next command-line value as uint.
func (*FlagClause) Uint16 ¶
func (p *FlagClause) Uint16() (target *uint16)
Uint16 parses the next command-line value as uint16.
func (*FlagClause) Uint16List ¶
func (p *FlagClause) Uint16List() (target *[]uint16)
Uint16List accumulates uint16 values into a slice.
func (*FlagClause) Uint16ListVar ¶
func (p *FlagClause) Uint16ListVar(target *[]uint16)
func (*FlagClause) Uint32 ¶
func (p *FlagClause) Uint32() (target *uint32)
Uint32 parses the next command-line value as uint32.
func (*FlagClause) Uint32List ¶
func (p *FlagClause) Uint32List() (target *[]uint32)
Uint32List accumulates uint32 values into a slice.
func (*FlagClause) Uint32ListVar ¶
func (p *FlagClause) Uint32ListVar(target *[]uint32)
func (*FlagClause) Uint64 ¶
func (p *FlagClause) Uint64() (target *uint64)
Uint64 parses the next command-line value as uint64.
func (*FlagClause) Uint64List ¶
func (p *FlagClause) Uint64List() (target *[]uint64)
Uint64List accumulates uint64 values into a slice.
func (*FlagClause) Uint64ListVar ¶
func (p *FlagClause) Uint64ListVar(target *[]uint64)
func (*FlagClause) Uint8 ¶
func (p *FlagClause) Uint8() (target *uint8)
Uint8 parses the next command-line value as uint8.
func (*FlagClause) Uint8List ¶
func (p *FlagClause) Uint8List() (target *[]uint8)
Uint8List accumulates uint8 values into a slice.
func (*FlagClause) Uint8ListVar ¶
func (p *FlagClause) Uint8ListVar(target *[]uint8)
func (*FlagClause) Uints ¶
func (p *FlagClause) Uints() (target *[]uint)
Uints accumulates uint values into a slice.
func (*FlagClause) UnNegatableBool ¶ added in v0.1.2
func (p *FlagClause) UnNegatableBool() (target *bool)
UnNegatableBool parses the next command-line value as bool.
func (*FlagClause) UnNegatableBoolList ¶ added in v0.1.2
func (p *FlagClause) UnNegatableBoolList() (target *[]bool)
UnNegatableBoolList accumulates bool values into a slice.
func (*FlagClause) UnNegatableBoolListVar ¶ added in v0.1.2
func (p *FlagClause) UnNegatableBoolListVar(target *[]bool)
func (*FlagClause) UnNegatableBoolVar ¶ added in v0.1.2
func (p *FlagClause) UnNegatableBoolVar(target *bool)
func (*FlagClause) Validator ¶ added in v0.6.0
func (f *FlagClause) Validator(validator OptionValidator) *FlagClause
type FlagGroupModel ¶
type FlagGroupModel struct {
Flags []*FlagModel `json:"flags,omitempty"`
}
func (*FlagGroupModel) FlagSummary ¶
func (f *FlagGroupModel) FlagSummary() string
type FlagModel ¶
type FlagModel struct { Name string `json:"name"` Help string `json:"help"` Short rune `json:"short,omitempty"` Default []string `json:"default,omitempty"` Envar string `json:"envar,omitempty"` PlaceHolder string `json:"place_holder,omitempty"` Required bool `json:"required,omitempty"` Hidden bool `json:"hidden,omitempty"` // used by plugin model Boolean bool `json:"boolean"` Negatable bool `json:"negatable,omitempty"` Cumulative bool `json:"cumulative"` Value Value `json:"-"` }
func (*FlagModel) FormatPlaceHolder ¶
func (*FlagModel) HelpWithEnvar ¶ added in v0.1.0
func (*FlagModel) IsBoolFlag ¶
func (*FlagModel) IsCumulative ¶ added in v0.5.0
func (*FlagModel) IsNegatable ¶ added in v0.1.2
type Getter ¶
type Getter interface { Value Get() interface{} }
Getter is an interface that allows the contents of a Value to be retrieved. It wraps the Value interface, rather than being part of it, because it appeared after Go 1 and its compatibility rules. All Value types provided by this package satisfy the Getter interface.
type HintAction ¶
type HintAction func() []string
HintAction is a function type who is expected to return a slice of possible command line arguments.
type OptionValidator ¶ added in v0.6.0
OptionValidator can be used to validate individual flags or arguments during parsing
type ParseContext ¶
type ParseContext struct { SelectedCommand *CmdClause // Flags, arguments and commands encountered and collected during parse. Elements []*ParseElement // contains filtered or unexported fields }
ParseContext holds the current context of the parser. When passed to Action() callbacks Elements will be fully populated with *FlagClause, *ArgClause and *CmdClause values and their corresponding arguments (if any).
func (*ParseContext) EOL ¶
func (p *ParseContext) EOL() bool
func (*ParseContext) Error ¶
func (p *ParseContext) Error() bool
func (*ParseContext) HasTrailingArgs ¶
func (p *ParseContext) HasTrailingArgs() bool
HasTrailingArgs returns true if there are unparsed command-line arguments. This can occur if the parser can not match remaining arguments.
func (*ParseContext) Peek ¶
func (p *ParseContext) Peek() *Token
func (*ParseContext) Push ¶
func (p *ParseContext) Push(token *Token) *Token
func (*ParseContext) String ¶
func (p *ParseContext) String() string
type ParseElement ¶
type ParseElement struct { // Clause is either *CmdClause, *ArgClause or *FlagClause. Clause interface{} // Value is corresponding value for an ArgClause or FlagClause (if any). Value *string }
A union of possible elements in a parse stack.
type Text ¶ added in v0.1.0
type Text interface { encoding.TextMarshaler encoding.TextUnmarshaler }
Text is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)
type Value ¶
Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)
If a Value has an IsBoolFlag() bool method returning true, the command-line parser makes --name equivalent to -name=true rather than using the next command-line argument, and adds a --no-name counterpart for negating the flag.
Example ¶
This example ilustrates how to define custom parsers. HTTPHeader cumulatively parses each encountered --header flag into a http.Header struct.
package main import ( "fmt" "net/http" "strings" ) type HTTPHeaderValue http.Header func (h *HTTPHeaderValue) Set(value string) error { parts := strings.SplitN(value, ":", 2) if len(parts) != 2 { return fmt.Errorf("expected HEADER:VALUE got '%s'", value) } (*http.Header)(h).Add(parts[0], parts[1]) return nil } func (h *HTTPHeaderValue) Get() interface{} { return (http.Header)(*h) } func (h *HTTPHeaderValue) String() string { return "" } func HTTPHeader(s Settings) (target *http.Header) { target = new(http.Header) s.SetValue((*HTTPHeaderValue)(target)) return } // This example ilustrates how to define custom parsers. HTTPHeader // cumulatively parses each encountered --header flag into a http.Header struct. func main() { var ( curl = New("curl", "transfer a URL") headers = HTTPHeader(curl.Flag("headers", "Add HTTP headers to the request.").Short('H').PlaceHolder("HEADER:VALUE")) ) curl.Parse([]string{"-H Content-Type:application/octet-stream"}) for key, value := range *headers { fmt.Printf("%s = %s\n", key, value) } }
Output: