Back to godoc.org
github.com/alexflint/go-arg

Package arg

v1.3.0
Latest Go to latest
Published: Jan 24, 2020 | License: BSD-2-Clause | Module: github.com/alexflint/go-arg

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

Code:

os.Args = split("./example --foo=hello --bar")

var args struct {
	Foo string
	Bar bool
}
MustParse(&args)
fmt.Println(args.Foo, args.Bar)
hello true
Example (DefaultValues)

This example demonstrates arguments that have default values

Code:

os.Args = split("./example")

var args struct {
	Foo string `default:"abc"`
}
MustParse(&args)
fmt.Println(args.Foo)
abc
Example (ErrorText)

This example shows the error string generated by go-arg when an invalid option is provided

Code:

os.Args = split("./example --optimize INVALID")

var args struct {
	Input    string   `arg:"positional"`
	Output   []string `arg:"positional"`
	Verbose  bool     `arg:"-v" help:"verbosity level"`
	Dataset  string   `help:"dataset to use"`
	Optimize int      `arg:"-O,help:optimization level"`
}

osExit = func(int) {}
stderr = os.Stdout

MustParse(&args)
Usage: example [--verbose] [--dataset DATASET] [--optimize OPTIMIZE] INPUT [OUTPUT [OUTPUT ...]]
error: error processing --optimize: strconv.ParseInt: parsing "INVALID": invalid syntax
Example (ErrorTextForSubcommand)

This example shows the error string generated by go-arg when an invalid option is provided

Code:

os.Args = split("./example get --count INVALID")

type getCmd struct {
	Count int
}

var args struct {
	Get *getCmd `arg:"subcommand"`
}

osExit = func(int) {}
stderr = os.Stdout

MustParse(&args)
Usage: example get [--count COUNT]
error: error processing --count: strconv.ParseInt: parsing "INVALID": invalid syntax
Example (HelpPlaceholder)

This example shows the usage string generated by go-arg with customized placeholders

Code:

os.Args = split("./example --help")

var args struct {
	Input    string   `arg:"positional" 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"`
}

osExit = func(int) {}

MustParse(&args)
Example (HelpText)

This example shows the usage string generated by go-arg

Code:

os.Args = split("./example --help")

var args struct {
	Input    string   `arg:"positional"`
	Output   []string `arg:"positional"`
	Verbose  bool     `arg:"-v" help:"verbosity level"`
	Dataset  string   `help:"dataset to use"`
	Optimize int      `arg:"-O,help:optimization level"`
}

osExit = func(int) {}

MustParse(&args)
Usage: example [--verbose] [--dataset DATASET] [--optimize OPTIMIZE] INPUT [OUTPUT [OUTPUT ...]]

Positional arguments:
  INPUT
  OUTPUT

Options:
  --verbose, -v          verbosity level
  --dataset DATASET      dataset to use
  --optimize OPTIMIZE, -O OPTIMIZE
                         optimization level
  --help, -h             display this help and exit
Example (HelpTextForSubcommand)

This example shows the usage string generated by go-arg when using subcommands

Code:

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"`
}

osExit = func(int) {}

MustParse(&args)
Usage: example get ITEM

Positional arguments:
  ITEM                   item to fetch

Options:
  --help, -h             display this help and exit
Example (HelpTextWithSubcommand)

This example shows the usage string generated by go-arg when using subcommands

Code:

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"`
}

osExit = func(int) {}

MustParse(&args)
Usage: example [--verbose] <command> [<args>]

Options:
  --verbose
  --help, -h             display this help and exit

Commands:
  get                    fetch an item and print it
  list                   list available items
Example (MultipleMixed)

This eample demonstrates multiple value arguments that can be mixed with other arguments.

Code:

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)
Commands: [cmd1 cmd2 cmd3]
Files: [file1 file2 file3]
Databases: [db1 db2 db3]
Example (MultipleValues)

This example demonstrates arguments that have multiple values

Code:

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)
Fetching the following IDs from localhost: [1 2 3]
Example (PositionalArguments)

This example demonstrates positional arguments

Code:

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)
In: in
Out: [out1 out2 out3]
Example (RequiredArguments)

This example demonstrates arguments that are required

Code:

os.Args = split("./example --foo=abc --bar")

var args struct {
	Foo string `arg:"required"`
	Bar bool
}
MustParse(&args)
fmt.Println(args.Foo, args.Bar)
abc true
Example (Subcommand)

This example demonstrates use of subcommands

Code:

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
}

osExit = func(int) {}
stderr = 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)
}
commit requested with message "what-this-commit-is-about"

Index

Examples

Package Files

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

func Parse

func Parse(dest ...interface{}) error

Parse processes command line arguments and stores them in dest

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 NewParser

func NewParser(config Config, dests ...interface{}) (*Parser, error)

NewParser constructs a parser from a list of destination structs

func (*Parser) Fail

func (p *Parser) Fail(msg string)

Fail prints usage information to stderr and exits with non-zero status

func (*Parser) Parse

func (p *Parser) Parse(args []string) error

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

func (p *Parser) SubcommandNames() []string

SubcommandNames returns the sequence of subcommands specified by the user. If no subcommands were given then it returns an empty slice.

func (*Parser) WriteHelp

func (p *Parser) WriteHelp(w io.Writer)

WriteHelp writes the usage string followed by the full help string for each option

func (*Parser) WriteUsage

func (p *Parser) WriteUsage(w io.Writer)

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.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier