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:"-"`.
Example ¶
This example demonstrates basic usage
// These are the args you would pass in on the command line os.Args = []string{"./example", "--foo=hello", "--bar"} var args struct { Foo string Bar bool } MustParse(&args) fmt.Println(args.Foo, args.Bar)
Output:
Example (DefaultValues) ¶
This example demonstrates arguments that have default values
// These are the args you would pass in on the command line os.Args = []string{"--help"} var args struct { Foo string Bar bool } args.Foo = "default value" MustParse(&args) fmt.Println(args.Foo, args.Bar)
Output:
Example (MultipleMixed) ¶
This eample demonstrates multiple value arguments that can be mixed with other arguments.
os.Args = []string{"./example", "-c", "cmd1", "db1", "-f", "file1", "db2", "-c", "cmd2", "-f", "file2", "-f", "file3", "db3", "-c", "cmd3"} var args struct { Commands []string `arg:"-c,separate"` Files []string `arg:"-f,separate"` Databases []string `arg:"positional"` } MustParse(&args) fmt.Println("Commands:", args.Commands) fmt.Println("Files", args.Files) fmt.Println("Databases", args.Databases)
Output:
Example (MultipleValues) ¶
This example demonstrates arguments that have multiple values
// The args you would pass in on the command line os.Args = []string{"--help"} var args struct { Database string IDs []int64 } MustParse(&args) fmt.Printf("Fetching the following IDs from %s: %q", args.Database, args.IDs)
Output:
Example (PositionalArguments) ¶
This example demonstrates positional arguments
// These are the args you would pass in on the command line os.Args = []string{"./example", "in", "out1", "out2", "out3"} var args struct { Input string `arg:"positional"` Output []string `arg:"positional"` } MustParse(&args) fmt.Println("Input:", args.Input) fmt.Println("Output:", args.Output)
Output:
Example (RequiredArguments) ¶
This example demonstrates arguments that are required
// These are the args you would pass in on the command line os.Args = []string{"--foo=1", "--bar"} var args struct { Foo string `arg:"required"` Bar bool } MustParse(&args)
Output:
Example (UsageString) ¶
This example shows the usage string generated by go-arg
// These are the args you would pass in on the command line os.Args = []string{"--help"} var args struct { Input string `arg:"positional"` Output []string `arg:"positional"` Verbose bool `arg:"-v,help:verbosity level"` Dataset string `arg:"help:dataset to use"` Optimize int `arg:"-O,help:optimization level"` } MustParse(&args)
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrHelp = errors.New("help requested by user")
ErrHelp indicates that -h or --help were provided
var ErrVersion = errors.New("version requested by user")
ErrVersion indicates that --version was provided
Functions ¶
Types ¶
type Config ¶
type Config struct {
Program string // Program is the name of the program used in the help text
}
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 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) Parse ¶
Parse processes the given command line option, storing the results in the field of the structs from which NewParser was constructed
func (*Parser) WriteHelp ¶
WriteHelp writes the usage string followed by the full help string for each option
func (*Parser) WriteUsage ¶
WriteUsage writes usage information to the given writer
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.