arg

README

Structured argument parsing for Go

Declare the command line arguments your program accepts by defining a struct.

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

$ ./example --foo=hello --bar
hello true

Required arguments

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

$ ./example
usage: example --foo FOO [--bar] 
error: --foo is required

Positional arguments

var args struct {
	Input   string   `arg:"positional"`
	Output  []string `arg:"positional"`
}
arg.MustParse(&args)
fmt.Println("Input:", args.Input)
fmt.Println("Output:", args.Output)

$ ./example src.txt x.out y.out z.out
Input: src.txt
Output: [x.out y.out z.out]

Usage strings

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"`
}
arg.MustParse(&args)

$ ./example -h
usage: [--verbose] [--dataset DATASET] [--optimize OPTIMIZE] [--help] 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               print this help message

Default values

var args struct {
	Foo string
	Bar bool
}
args.Foo = "default value"
arg.MustParse(&args)

Arguments with multiple values

var args struct {
	Database string
	IDs      []int64
}
arg.MustParse(&args)
fmt.Printf("Fetching the following IDs from %s: %q", args.Database, args.IDs)

./example -database foo -ids 1 2 3
Fetching the following IDs from foo: [1 2 3]

Installation

go get github.com/alexflint/go-arg

Documentation

https://godoc.org/github.com/alexflint/go-arg

Rationale

There are many command line argument parsing libraries for Go, including one in the standard library, so why build another?

The shortcomings of the flag library that ships in the standard library are well known. Positional arguments must preceed options, so ./prog x --foo=1 does what you expect but ./prog --foo=1 x does not. Arguments cannot have both long (--foo) and short (-f) forms.

Many third-party argument parsing libraries are geared for writing sophisticated command line interfaces. The excellent codegangsta/cli is perfect for working with multiple sub-commands and nested flags, but is probably overkill for a simple script with a handful of flags.

The main idea behind go-arg is that Go already has an excellent way to describe data structures using Go structs, so there is no need to develop more levels of abstraction on top of this. Instead of one API to specify which arguments your program accepts, and then another API to get the values of those arguments, why not replace both with a single struct?

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` package name:

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

The valid tag strings are `positional`, `required`, and `help`. Further, 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). Fields can be excluded from processing with `arg:"-"`.

Index

• Variables
• func MustParse(dest ...interface{})
• func Parse(dest ...interface{}) error
• type Parser
  • func NewParser(dests ...interface{}) (*Parser, error)
  • func (p *Parser) Fail(msg string)
  • func (p *Parser) Parse(args []string) error
  • func (p *Parser) WriteHelp(w io.Writer)
  • func (p *Parser) WriteUsage(w io.Writer)

Variables

var ErrHelp = errors.New("help requested by user")

ErrHelp indicates that -h or --help were provided

Functions

func MustParse

func MustParse(dest ...interface{})

MustParse processes command line arguments and exits upon failure

func Parse

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

Parse processes command line arguments and stores them in dest

Types

type Parser

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

Parser represents a set of command line options with destination values

func NewParser

func NewParser(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) 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