Involved Source Files 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:"-"`.parse.goreflect.gosequence.gosubcommand.gousage.go
Code Examples
{
os.Args = split("./example --foo=hello --bar")
var args struct {
Foo string
Bar bool
}
MustParse(&args)
fmt.Println(args.Foo, args.Bar)
}
{
os.Args = []string{}
var args struct {
Bool bool
Byte byte
Rune rune
Int int
Int8 int8
Int16 int16
Int32 int32
Int64 int64
Float32 float32
Float64 float64
String string
Duration time.Duration
URL url.URL
Email mail.Address
MAC net.HardwareAddr
}
MustParse(&args)
}
{
os.Args = split("./example")
var args struct {
Foo string `default:"abc"`
}
MustParse(&args)
fmt.Println(args.Foo)
}
{
os.Args = split("./example")
_ = os.Setenv("AUTH_KEY", "my_key")
defer os.Unsetenv("AUTH_KEY")
var args struct {
AuthKey string `arg:"--,env:AUTH_KEY"`
}
MustParse(&args)
fmt.Println(args.AuthKey)
}
{
os.Args = split("./example --=my_key")
var args struct {
AuthKey string `arg:"--,env:AUTH_KEY"`
}
err := Parse(&args)
fmt.Println(err)
}
{
os.Args = split("./example -=my_key")
var args struct {
AuthKey string `arg:"--,env:AUTH_KEY"`
}
err := Parse(&args)
fmt.Println(err)
}
{
os.Args = split("./example --optimize INVALID")
var args struct {
Input string `arg:"positional,required"`
Output []string `arg:"positional"`
Verbose bool `arg:"-v" help:"verbosity level"`
Dataset string `help:"dataset to use"`
Optimize int `arg:"-O,help:optimization level"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example get --count INVALID")
type getCmd struct {
Count int
}
var args struct {
Get *getCmd `arg:"subcommand"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example --help")
var args struct {
Input string `arg:"positional,required" placeholder:"SRC"`
Output []string `arg:"positional" placeholder:"DST"`
Optimize int `arg:"-O" help:"optimization level" placeholder:"LEVEL"`
MaxJobs int `arg:"-j" help:"maximum number of simultaneous jobs" placeholder:"N"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example --help")
var args struct {
Input string `arg:"positional,required"`
Output []string `arg:"positional"`
Verbose bool `arg:"-v" help:"verbosity level"`
Dataset string `help:"dataset to use"`
Optimize int `arg:"-O,--optim" help:"optimization level"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example get --help")
type getCmd struct {
Item string `arg:"positional,required" help:"item to fetch"`
}
type listCmd struct {
Format string `help:"output format"`
Limit int
}
var args struct {
Verbose bool
Get *getCmd `arg:"subcommand" help:"fetch an item and print it"`
List *listCmd `arg:"subcommand" help:"list available items"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example --help")
type getCmd struct {
Item string `arg:"positional" help:"item to fetch"`
}
type listCmd struct {
Format string `help:"output format"`
Limit int
}
var args struct {
Verbose bool
Get *getCmd `arg:"subcommand" help:"fetch an item and print it"`
List *listCmd `arg:"subcommand" help:"list available items"`
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
}
{
os.Args = split("./example --values one=two,three=four")
var args struct {
Values commaSeparated
}
MustParse(&args)
fmt.Println(args.Values.M)
}
{
os.Args = split("./example --userids john=123 mary=456")
var args struct {
UserIDs map[string]int
}
MustParse(&args)
fmt.Println(args.UserIDs)
}
{
os.Args = split("./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)
}
{
os.Args = split("./example --database localhost --ids 1 2 3")
var args struct {
Database string
IDs []int64
}
MustParse(&args)
fmt.Printf("Fetching the following IDs from %s: %v", args.Database, args.IDs)
}
{
os.Args = split("./example in out1 out2 out3")
var args struct {
Input string `arg:"positional"`
Output []string `arg:"positional"`
}
MustParse(&args)
fmt.Println("In:", args.Input)
fmt.Println("Out:", args.Output)
}
{
os.Args = split("./example --foo=abc --bar")
var args struct {
Foo string `arg:"required"`
Bar bool
}
MustParse(&args)
fmt.Println(args.Foo, args.Bar)
}
{
os.Args = split("./example commit -a -m what-this-commit-is-about")
type CheckoutCmd struct {
Branch string `arg:"positional"`
Track bool `arg:"-t"`
}
type CommitCmd struct {
All bool `arg:"-a"`
Message string `arg:"-m"`
}
type PushCmd struct {
Remote string `arg:"positional"`
Branch string `arg:"positional"`
SetUpstream bool `arg:"-u"`
}
var args struct {
Checkout *CheckoutCmd `arg:"subcommand:checkout"`
Commit *CommitCmd `arg:"subcommand:commit"`
Push *PushCmd `arg:"subcommand:push"`
Quiet bool `arg:"-q"` // this flag is global to all subcommands
}
mustParseExit = func(int) {}
mustParseOut = os.Stdout
MustParse(&args)
switch {
case args.Checkout != nil:
fmt.Printf("checkout requested for branch %s\n", args.Checkout.Branch)
case args.Commit != nil:
fmt.Printf("commit requested with message \"%s\"\n", args.Commit.Message)
case args.Push != nil:
fmt.Printf("push requested from %s to %s\n", args.Push.Branch, args.Push.Remote)
}
}
{
os.Args = split("./example get --help")
type getCmd struct {
Item string `arg:"positional" help:"item to fetch"`
}
type listCmd struct {
Format string `help:"output format"`
Limit int
}
var args struct {
Verbose bool
Get *getCmd `arg:"subcommand" help:"fetch an item and print it"`
List *listCmd `arg:"subcommand" help:"list available items"`
}
exit := func(int) {}
p, err := NewParser(Config{Exit: exit}, &args)
if err != nil {
fmt.Println(err)
os.Exit(1)
}
err = p.WriteHelpForSubcommand(os.Stdout, "list")
if err != nil {
fmt.Println(err)
os.Exit(1)
}
}
{
os.Args = split("./example get --help")
type mostNestedCmd struct {
Item string
}
type nestedCmd struct {
MostNested *mostNestedCmd `arg:"subcommand"`
}
type topLevelCmd struct {
Nested *nestedCmd `arg:"subcommand"`
}
var args struct {
TopLevel *topLevelCmd `arg:"subcommand"`
}
exit := func(int) {}
p, err := NewParser(Config{Exit: exit}, &args)
if err != nil {
fmt.Println(err)
os.Exit(1)
}
err = p.WriteHelpForSubcommand(os.Stdout, "toplevel", "nested", "mostnested")
if err != nil {
fmt.Println(err)
os.Exit(1)
}
}
Package-Level Type Names (total 5)
/* sort by: | */
Config represents configuration options for an argument parser EnvPrefix instructs the library to use a name prefix when reading environment variables. Exit is called to terminate the process with an error code (defaults to os.Exit) IgnoreDefault instructs the library not to reset the variables to the
default values, including pointers to sub commands IgnoreEnv instructs the library not to read environment variables Out is where help text, usage text, and failure messages are printed (defaults to os.Stdout) Program is the name of the program used in the help text StrictSubcommands intructs the library not to allow global commands after
subcommand
func NewParser(config Config, dests ...interface{}) (*Parser, error)
Epilogued is the interface that the destination struct should implement to
add an epilogue string at the bottom of the help message. Epilogue returns the string that will be printed on a line by itself
at the end of the help message.
Parser represents a set of command line options with destination values Fail prints usage information to p.Config.Out and exits with status code 2. FailSubcommand prints usage information for a specified subcommand to p.Config.Out,
then exits with status code 2. 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.(*Parser) MustParse(args []string) Parse processes the given command line option, storing the results in the fields
of the structs from which NewParser was constructed.
It returns ErrHelp if "--help" is one of the command line args and ErrVersion if
"--version" is one of the command line args (the latter only applies if the
destination struct passed to NewParser implements Versioned.)
To respond to --help and --version in the way that MustParse does, see examples
in the README under "Custom handling of --help and --version". 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. SubcommandNames returns the sequence of subcommands specified by the
user. If no subcommands were given then it returns an empty slice. WriteHelp writes the usage string followed by the full help string for each option 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. WriteUsage writes usage information to the given writer 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.
func MustParse(dest ...interface{}) *Parser
func NewParser(config Config, dests ...interface{}) (*Parser, error)
Versioned is the interface that the destination struct should implement to
make a version string appear at the top of the help message. Version returns the version string that will be printed on a line by itself
at the top of the help message.
Package-Level Functions (total 3)
MustParse processes command line arguments and exits upon failure
NewParser constructs a parser from a list of destination structs
Parse processes command line arguments and stores them in dest
Package-Level Variables (total 2)
ErrHelp indicates that the builtin -h or --help were provided
ErrVersion indicates that the builtin --version was provided
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
