go-arg: github.com/alexflint/go-arg Index | Examples | Files

package arg

import "github.com/alexflint/go-arg"

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:"-"`.

This example demonstrates basic usage

Code:

// These are the args you would pass in on the command line
os.Args = split("./example --foo=hello --bar")

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

Output:

hello true

This example demonstrates arguments that have default values

Code:

// These are the args you would pass in on the command line
os.Args = split("./example")

var args struct {
    Foo string
}
args.Foo = "default value"
MustParse(&args)
fmt.Println(args.Foo)

Output:

default value

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)

Output:

Commands: [cmd1 cmd2 cmd3]
Files: [file1 file2 file3]
Databases: [db1 db2 db3]

This example demonstrates arguments that have multiple values

Code:

// The args you would pass in on the command line
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)

Output:

Fetching the following IDs from localhost: [1 2 3]

This example demonstrates positional arguments

Code:

// These are the args you would pass in on the command line
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)

Output:

In: in
Out: [out1 out2 out3]

This example demonstrates arguments that are required

Code:

// These are the args you would pass in on the command line
os.Args = split("./example --foo=abc --bar")

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

Output:

abc true

This example shows the usage string generated by go-arg

Code:

// These are the args you would pass in on the command line
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"`
}

// This is only necessary when running inside golang's runnable example harness
osExit = func(int) {}

MustParse(&args)

Output:

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

Index

Examples

Package Files

doc.go parse.go usage.go

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 Uses

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

Parse processes command line arguments and stores them in dest

type Config Uses

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 Uses

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 Uses

type Parser struct {
    // contains filtered or unexported fields
}

Parser represents a set of command line options with destination values

func MustParse Uses

func MustParse(dest ...interface{}) *Parser

MustParse processes command line arguments and exits upon failure

func NewParser Uses

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

NewParser constructs a parser from a list of destination structs

func (*Parser) Fail Uses

func (p *Parser) Fail(msg string)

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

func (*Parser) Parse Uses

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) WriteHelp Uses

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

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

func (*Parser) WriteUsage Uses

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

WriteUsage writes usage information to the given writer

type Versioned Uses

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.

Package arg imports 10 packages (graph) and is imported by 90 packages. Updated 2019-05-03. Refresh now. Tools for package owners.