Documentation ¶
Overview ¶
Package arg parses command line arguments using the fields from a struct.
For example,
var args struct { Iter int Debug bool } arg.MustParse(&args)
defines two command line arguments, which can be set using any of
./example --iter=1 --debug // debug is a boolean flag so its value is set to true ./example -iter 1 // debug defaults to its zero value (false) ./example --debug=true // iter defaults to its zero value (zero)
The fastest way to see how to use go-arg is to read the examples below.
Fields can be bool, string, any float type, or any signed or unsigned integer type. They can also be slices of any of the above, or slices of pointers to any of the above.
Tags can be specified using the `arg` and `help` tag names:
var args struct { Input string `arg:"positional"` Log string `arg:"positional,required"` Debug bool `arg:"-d" help:"turn on debug mode"` RealMode bool `arg:"--real" Wr io.Writer `arg:"-"` }
Any tag string that starts with a single hyphen is the short form for an argument (e.g. `./example -d`), and any tag string that starts with two hyphens is the long form for the argument (instead of the field name).
Other valid tag strings are `positional` and `required`.
Fields can be excluded from processing with `arg:"-"`.
Index ¶
- Variables
- func Parse(dest ...interface{}) error
- func Register(dest ...interface{})
- type Config
- type Described
- type Epilogued
- type Parser
- func (p *Parser) Fail(msg string)
- func (p *Parser) FailSubcommand(msg string, subcommand ...string) error
- func (p *Parser) MustParse(args []string)
- func (p *Parser) Parse(args []string) error
- func (p *Parser) Subcommand() interface{}
- func (p *Parser) SubcommandNames() []string
- func (p *Parser) WriteHelp(w io.Writer)
- func (p *Parser) WriteHelpForSubcommand(w io.Writer, subcommand ...string) error
- func (p *Parser) WriteUsage(w io.Writer)
- func (p *Parser) WriteUsageForSubcommand(w io.Writer, subcommand ...string) error
- type Versioned
Constants ¶
This section is empty.
Variables ¶
var ErrHelp = errors.New("help requested by user")
ErrHelp indicates that the builtin -h or --help were provided
var ErrVersion = errors.New("version requested by user")
ErrVersion indicates that the builtin --version was provided
Functions ¶
Types ¶
type Config ¶
type Config struct { // Program is the name of the program used in the help text Program string // IgnoreEnv instructs the library not to read environment variables IgnoreEnv bool // IgnoreDefault instructs the library not to reset the variables to the // default values, including pointers to sub commands IgnoreDefault bool // StrictSubcommands intructs the library not to allow global commands after // subcommand StrictSubcommands bool // Exit is called to terminate the process with an error code (defaults to os.Exit) Exit func(int) // Out is where help text, usage text, and failure messages are printed (defaults to os.Stdout) Out io.Writer }
Config represents configuration options for an argument parser
type Described ¶
type Described interface { // Description returns the string that will be printed on a line by itself // at the top of the help message. Description() string }
Described is the interface that the destination struct should implement to make a description string appear at the top of the help message.
type Epilogued ¶
type Epilogued interface { // Epilogue returns the string that will be printed on a line by itself // at the end of the help message. Epilogue() string }
Epilogued is the interface that the destination struct should implement to add an epilogue string at the bottom of the help message.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser represents a set of command line options with destination values
func MustParse ¶
func MustParse(dest ...interface{}) *Parser
MustParse processes command line arguments and exits upon failure
func (*Parser) FailSubcommand ¶
FailSubcommand prints usage information for a specified subcommand to stderr, then exits with non-zero status. To write usage information for a top-level subcommand, provide just the name of that subcommand. To write usage information for a subcommand that is nested under another subcommand, provide a sequence of subcommand names starting with the top-level subcommand and so on down the tree.
func (*Parser) Parse ¶
Parse processes the given command line option, storing the results in the field of the structs from which NewParser was constructed
func (*Parser) Subcommand ¶
func (p *Parser) Subcommand() interface{}
Subcommand returns the user struct for the subcommand selected by the command line arguments most recently processed by the parser. The return value is always a pointer to a struct. If no subcommand was specified then it returns the top-level arguments struct. If no command line arguments have been processed by this parser then it returns nil.
func (*Parser) SubcommandNames ¶
SubcommandNames returns the sequence of subcommands specified by the user. If no subcommands were given then it returns an empty slice.
func (*Parser) WriteHelp ¶
WriteHelp writes the usage string followed by the full help string for each option
func (*Parser) WriteHelpForSubcommand ¶
WriteHelpForSubcommand writes the usage string followed by the full help string for a specified subcommand. To write help for a top-level subcommand, provide just the name of that subcommand. To write help for a subcommand that is nested under another subcommand, provide a sequence of subcommand names starting with the top-level subcommand and so on down the tree.
func (*Parser) WriteUsage ¶
WriteUsage writes usage information to the given writer
func (*Parser) WriteUsageForSubcommand ¶
WriteUsageForSubcommand writes the usage information for a specified subcommand. To write usage information for a top-level subcommand, provide just the name of that subcommand. To write usage information for a subcommand that is nested under another subcommand, provide a sequence of subcommand names starting with the top-level subcommand and so on down the tree.
type Versioned ¶
type Versioned interface { // Version returns the version string that will be printed on a line by itself // at the top of the help message. Version() string }
Versioned is the interface that the destination struct should implement to make a version string appear at the top of the help message.