tagflag

README

tagflag

See the thorough package documentation on GoDoc. I know you want to see this in the README, but just go to the GoDoc.

Similar projects

• https://github.com/jaffee/commandeer
• https://github.com/octago/sflags

Documentation

Overview

Package tagflag uses reflection to derive flags and positional arguments to a program, and parses and sets them from a slice of arguments.

For example:

var opts struct {
    Mmap           bool           `help:"memory-map torrent data"`
    TestPeer       []*net.TCPAddr `help:"addresses of some starting peers"`
    tagflag.StartPos              // Marks beginning of positional arguments.
    Torrent        []string       `arity:"+" help:"torrent file path or magnet uri"`
}
tagflag.Parse(&opts)

Supported tags include:

help: a line of text to show after the option
arity: defaults to 1. the number of arguments a field requires, or ? for one
       optional argument, + for one or more, or * for zero or more.

MarshalArgs is called on fields that implement ArgsMarshaler. A number of arguments matching the arity of the field are passed if possible.

Slices will collect successive values, within the provided arity constraints.

A few helpful types have builtin marshallers, for example Bytes, *net.TCPAddr, *url.URL, time.Duration, and net.IP.

Flags are strictly passed with the form -K or -K=V. No space between -K and the value is allowed. This allows positional arguments to be mixed in with flags, and prevents any confusion due to some flags occasionally not taking values. A `--` will terminate flag parsing, and treat all further arguments as positional.

A builtin help and usage printer are provided, and activated when passing -h or -help.

Flag and positional argument names are automatically munged to fit the standard scheme within tagflag.

Index

• Variables
• func Description(desc string) parseOpt
• func NoDefaultHelp() parseOpt
• func Parent(parent *Parser) parseOpt
• func ParseErr(cmd interface{}, args []string, opts ...parseOpt) (err error)
• func ParseIntermixed(enabled bool) parseOpt
• func Program(name string) parseOpt
• func Unmarshal(arg string, v interface{}) error
• type Bytes
  • func (me Bytes) Int64() int64
  • func (me *Bytes) Marshal(s string) (err error)
  • func (*Bytes) RequiresExplicitValue() bool
  • func (me Bytes) String() string
  • func (me *Bytes) UnmarshalText(text []byte) error
• type ExcessArgs
• type Marshaler
• type Parser
  • func Parse(cmd interface{}, opts ...parseOpt) *Parser
  • func ParseArgs(cmd interface{}, args []string, opts ...parseOpt) *Parser
• type StartPos

Variables

var ErrDefaultHelp = errors.New("help flag")

Default help flag was provided, and should be handled.

var ErrFieldsAfterExcessArgs = fmt.Errorf("field(s) after %T", ExcessArgs{})

The error returned if there are fields in a struct after ExcessArgs.

Functions

func Description

func Description(desc string) parseOpt

Provides a description for the program to be shown in the usage message.

func NoDefaultHelp

func NoDefaultHelp() parseOpt

Don't perform default behaviour if -h or -help are passed.

func Parent

func Parent(parent *Parser) parseOpt

func ParseErr

func ParseErr(cmd interface{}, args []string, opts ...parseOpt) (err error)

Parses given arguments, returning any error.

func ParseIntermixed

func ParseIntermixed(enabled bool) parseOpt

func Program

func Program(name string) parseOpt

func Unmarshal

func Unmarshal(arg string, v interface{}) error

Types

type Bytes

type Bytes int64

A nice builtin type that will marshal human readable byte quantities to int64. For example 100GB. See https://godoc.org/github.com/dustin/go-humanize.

func (Bytes) Int64

func (me Bytes) Int64() int64

func (*Bytes) Marshal

func (me *Bytes) Marshal(s string) (err error)

func (*Bytes) RequiresExplicitValue

func (*Bytes) RequiresExplicitValue() bool

func (Bytes) String

func (me Bytes) String() string

func (*Bytes) UnmarshalText

func (me *Bytes) UnmarshalText(text []byte) error

type ExcessArgs

type ExcessArgs []string

This should be added to the end of a struct to soak up any arguments that didn't fit sooner.

type Marshaler

type Marshaler interface {
	Marshal(in string) error
	// Must have and ignore a pointer receiver.
	RequiresExplicitValue() bool
}

TODO: Perhaps this should embed encoding.TextUnmarshaler instead.

type Parser

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

func Parse

func Parse(cmd interface{}, opts ...parseOpt) *Parser

Parses the command-line arguments, exiting the process appropriately on errors or if usage is printed.

func ParseArgs

func ParseArgs(cmd interface{}, args []string, opts ...parseOpt) *Parser

Like Parse, but operates on the given args instead.

type StartPos

type StartPos struct{}

Struct fields after this one are considered positional arguments.