Documentation ¶
Overview ¶
Package cmdline provides a way to parse command line arguments.
Example (EnvOption) ¶
os.Setenv("PASSWORD", "secret") os.Setenv("VERBOSE", "true") var ( cli = NewParser() pass = cli.Option("-p, --password, $PASSWORD").String("") verbose = cli.Flag("-V, --verbose, $VERBOSE") ) fmt.Println(pass, verbose)
Output: secret true
Index ¶
- func ParseBool(v string) (bool, error)
- type Basic
- type Group
- type Item
- type NamedArg
- type Option
- func (opt *Option) Bool(def bool) bool
- func (opt *Option) BoolOpt() (bool, *Option)
- func (opt *Option) Doc(lines ...string)
- func (opt *Option) Duration(def string) time.Duration
- func (opt *Option) DurationOpt(def string) (time.Duration, *Option)
- func (opt *Option) Enum(def string, possible ...string) string
- func (opt *Option) EnumOpt(def string, possible ...string) (string, *Option)
- func (opt *Option) Float64(def float64) float64
- func (opt *Option) Float64Opt(def float64) (float64, *Option)
- func (opt *Option) Int(def int) int
- func (opt *Option) IntOpt(def int) (int, *Option)
- func (opt *Option) String(def string) string
- func (opt *Option) StringOpt(def string) (string, *Option)
- func (opt *Option) Uint(def uint64) uint64
- func (opt *Option) Uint16(def uint16) uint16
- func (opt *Option) Uint32(def uint32) uint32
- func (opt *Option) Uint8(def uint8) uint8
- func (opt *Option) UintOpt(def uint64) (uint64, *Option)
- func (opt *Option) Url(def string) *url.URL
- func (opt *Option) UrlOpt(def string) (*url.URL, *Option)
- type Parser
- func (me *Parser) Argn(n int) string
- func (me *Parser) Args() []string
- func (me *Parser) Error() error
- func (me *Parser) Flag(name string) bool
- func (me *Parser) Group(title, name string) *Group
- func (me *Parser) NamedArg(name string) *NamedArg
- func (me *Parser) Ok() bool
- func (me *Parser) Option(names string, doclines ...string) *Option
- func (me *Parser) Parse()
- func (me *Parser) Preface(lines ...string)
- func (me *Parser) SetShell(sh Shell)
- func (me *Parser) String() string
- func (me *Parser) Usage() *Usage
- type Shell
- type ShellOS
- func (me *ShellOS) Args() []string
- func (me *ShellOS) Exit(code int)
- func (me *ShellOS) Fatal(v ...interface{})
- func (me *ShellOS) Getenv(key string) string
- func (me *ShellOS) Getwd() (string, error)
- func (me *ShellOS) Stderr() io.Writer
- func (me *ShellOS) Stdin() io.Reader
- func (me *ShellOS) Stdout() io.Writer
- type Usage
- type WithExtraOptions
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseBool ¶ added in v0.11.0
ParseBool returns true if the string evaluates to a true expression. See example for possible values.
Example ¶
in := []string{ "1", "y", "yes", "Yes", "YES", "true", "True", "TRUE", "0", "n", "no", "No", "NO", "false", "False", "FALSE", "", } for _, v := range in { got, _ := ParseBool(v) fmt.Printf("%-5s %v\n", v, got) } _, err := ParseBool("other") fmt.Println(err)
Output: 1 true y true yes true Yes true YES true true true True true TRUE true 0 false n false no false No false NO false false false False false FALSE false false parse bool "other"
Types ¶
type Basic ¶ added in v0.6.0
type Basic struct { *Parser // contains filtered or unexported fields }
func NewBasicParser ¶ added in v0.6.0
func NewBasicParser() *Basic
NewBasicParser returns a parser including help options -h, --help.
Example ¶
os.Setenv("VERBOSE", "yes") var ( cli = NewBasicParser() uid = cli.Option("--uid", "Generated if not given").Int(0) password = cli.Option("-p, --password, $PASSWORD").String("") verbose = cli.Flag("-V, --verbose, $VERBOSE") role = cli.Option("-r, --role").Enum("guest", "guest", "admin", "nobody", ) url = cli.Option("--test-host").Url("tcp://example.com:123") dur = cli.Option("--pause").Duration("200ms") // parse and name non options username = cli.NamedArg("USERNAME").String("") note = cli.NamedArg("NOTE").String("") ) cli.Parse() // use options ... if !verbose { log.SetOutput(ioutil.Discard) } fmt.Fprintln(os.Stdout, uid, username, password, note, role, url, dur)
Output:
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
type NamedArg ¶ added in v0.9.0
type NamedArg struct {
// contains filtered or unexported fields
}
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option defines a command line option, ie. --username
func NewOption ¶
NewOption returns an option defined by a comma separated list of names and arguments to match against. Usually you would call Parser.Option(names) over this.
func (*Option) BoolOpt ¶
BoolOpt returns bool value from the arguments. The Option is returned for more configuration.
func (*Option) Duration ¶ added in v0.12.0
Example ¶
var ( cli = NewParser() u = cli.Option("-d, --duration").Duration("199µs") ) fmt.Println(u.Microseconds())
Output: 199
func (*Option) DurationOpt ¶ added in v0.12.0
func (*Option) Enum ¶ added in v0.10.0
Enum same as EnumOpt but does not return the Option
Example ¶
os.Args = []string{"mycmd"} // just for this test cli := NewParser() cli.Option("-a, --animal").Enum("snake", "snake", "bear", "goat") cli.Usage().WriteTo(os.Stdout)
Output: Usage: mycmd [OPTIONS] Options -a, --animal : "snake" [snake bear goat]
func (*Option) EnumOpt ¶ added in v0.10.0
Enum returns an enumerated string. It's ok to only have one.
func (*Option) Float64 ¶
Float64 returns float64 value from the arguments or the given default value.
func (*Option) Float64Opt ¶
Float64Opt returns float64 value from the arguments or the given default value.
func (*Option) StringOpt ¶
StringOpt returns string value from the arguments or the given default value.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser groups arguments for option parsing and usage.
Example (UsageHiddenPassword) ¶
cli := NewParser() cli.args = []string{"adduser"} _, opt := cli.Option("--uid").IntOpt(0) opt.Doc("If not given, one is generated") cli.Option("-p, --password", "minimum 8 chars", "hidden", ).String("secret") cli.Usage().WriteTo(os.Stdout)
Output: Usage: adduser [OPTIONS] Options --uid : 0 If not given, one is generated -p, --password : "********" minimum 8 chars
func NewParser ¶
func NewParser() *Parser
NewParser returns a parser using the DefaultShell
Example ¶
var ( cli = NewParser() uid = cli.Option("--uid", "Generated if not given").Int(0) password = cli.Option("-p, --password, $PASSWORD").String("") help = cli.Flag("-h, --help") // parse and name non options username = cli.NamedArg("USERNAME").String("") note = cli.NamedArg("NOTE").String("") ) switch { case help: cli.Usage().WriteTo(os.Stdout) os.Exit(0) case !cli.Ok(): fmt.Fprintln(os.Stderr, cli.Error()) fmt.Fprintln(os.Stderr, "Try --help for more information") os.Exit(1) } // use options ... fmt.Fprintln(os.Stdout, uid, username, password, note)
Output:
func (*Parser) Option ¶
Option returns a new option with the given names. Names should be a comma separated string, e.g.
-n, --dry-run
You can also include an environment variable to use as default value in the names, e.g.
-t, --token, $COGNITO_TOKEN
func (*Parser) Parse ¶ added in v0.6.0
func (me *Parser) Parse()
Parse checks parsing errors and exits on errors
func (*Parser) Usage ¶ added in v0.7.0
Usage returns the currently documented options for further documentation.
Example (OptionalNamedArguments) ¶
os.Args = []string{"mycmd"} // just for this test cli := NewBasicParser() cli.NamedArg("FILES...").Strings("file1", "file2") cli.Usage().WriteTo(os.Stdout)
Output: Usage: mycmd [OPTIONS] [FILES...] Options -h, --help
Example (RequiredNamedArguments) ¶
os.Args = []string{"mycmd", "-h"} // just for this test cli := NewBasicParser() cli.NamedArg("FILES...").Strings() cli.Usage().WriteTo(os.Stdout)
Output: Usage: mycmd [OPTIONS] FILES... Options -h, --help
type Shell ¶ added in v0.8.0
type Shell interface { Getenv(string) string Args() []string Getwd() (string, error) Stdin() io.Reader Stdout() io.Writer Stderr() io.Writer Exit(code int) Fatal(v ...interface{}) }
Shell defines a command line execution context.
var DefaultShell Shell = NewShellOS()
DefaultShell is used by all new parsers.
type ShellOS ¶ added in v0.8.0
type ShellOS struct {
// contains filtered or unexported fields
}
ShellOS uses package os
func NewShellOS ¶ added in v0.8.0
func NewShellOS() *ShellOS
NewShellOS returns a shell from the os values.
type Usage ¶ added in v0.7.0
type Usage struct { *Parser // contains filtered or unexported fields }
type Usage is for documenting the configured parser
func (*Usage) Example ¶ added in v0.7.0
Example adds an examples section. The examples are placed last after options and named arguments. Examples are plain text and not evaluated in any way.
func (*Usage) WriteOptionsTo ¶ added in v0.7.0
WriteOptionsTo writes the Options section to the given writer.
type WithExtraOptions ¶
type WithExtraOptions interface { // ExtraOptions is used to parse extra options for a grouped item ExtraOptions(*Parser) }