flag

README

Flag

Flag is a simple but powerful commandline flag parsing library for Go.

Documentation

Documentation can be found at Godoc

Supported features

• bool
  • -f, -f=false, -f=true, there is no -f true and -f false to avoid conflicting with positional flag and non-flag values
• string,number
  • -f a.go -n 100
• slice:
  • -f a.go -f b.go -f c.go
• hint flag as value
  • -- to hint next argument is value: rm -- -a.go, rm -- -a.go -b.go will throws error for -b.go is invalid flag
  • --* to hint latter all arguments are value: rm -- -a.go -b.go -c.go
• useful tricks:
  • -f a.go, -f=a.go, --file=a.go
  • -zcf=a.go, -zcf a.go
  • -I/usr/include: only works for -[a-zA-Z][^a-zA-Z].+
• catch non-flag arguments:
  • rm -rf a.go b.go c.go, catchs [a.go, b.go, c.go]
• positional flag:
  • cp -f src.go dst.go, catchs SOURCE=a.go DESTINATION=dst.go
  • This is implemented as a special case of non-flag arguments, positional flags will be applied first, and remain values
• value apply/checking
  • default value
  • environment value
  • value list for user selecting
• multiple flag names for one flag
• subcommand.

Definition via structure field tag

• names: flag/command names, comma-speparated, default uses camelCase of field name(with a - prefix for flag)

  • - to skip this field
  • @ to indicate that this is a positional flag
  • support multiple name and formats: eg: `-f, --file, -file'

• arglist: argument list for command or argument name for flag

  • for positional flag, this will also be used as it's display name if defined, otherwise field name is used.
  • command example: eg: [OPTION]... SOURCE DESTINATION, or [FLAG]... FILE [ARG}...
  • flag example: eg: 'FILE', 'DESTINATION'

• version: version message for command

• usage: short description

• desc: long description

• env: environment name for flag, if user doesn't passed this flag, environment value will be used

• default: default value for flag, if user doesn't passed this flag and environment value not defined, it will be used

• args: used to catching non-flag arguments, it's type must be []string

• special cases

  • Enable, there must be a Enable field inside command to indicate whether user are using this command.
  • Args: this field will be used to store non-flag arguments if args tag is not defined
  • Metadata: structure could implement this interface to override settings defined by tags

    type Metadata interface {
        // the key is comma-separated flag name to find command/flag,
        // each component represents a level, "" represents root command
        Metadata() map[string]Flag
    }
  

Example

Flags

package flag

import "fmt"

type Tar struct {
	GZ          bool     `names:"-z, --gz" usage:"gzip format"`
	BZ          bool     `names:"-j, --bz" usage:"bzip2 format"`
	XZ          bool     `names:"-J, --xz" usage:"xz format"`
	Create      bool     `names:"-c" usage:"create tar file"`
	Extract     bool     `names:"-x" usage:"extract tar file"`
	File        string   `names:"-f" usage:"output file for create or input file for extract"`
	Directory   string   `names:"-C" usage:"extract directory"`
	SourceFiles []string `args:"true"`
}

func (t *Tar) Metadata() map[string]Flag {
	const (
		usage   = "tar is a tool for manipulate tape archives."
		version = `
			version: v1.0.0
			commit: 10adf10dc10
			date:   2017-01-01 10:00:01
		`
		desc = `
		tar creates and manipulates streaming archive files.  This implementation can extract
		from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images and can create tar, pax,
		cpio, ar, and shar archives.
		`
	)
	return map[string]Flag{
		"": {
			Usage:   usage,
			Version: version,
			Desc:    desc,
		},
		"--gz": {
			Desc: "use gzip format",
		},
	}
}

func ExampleFlagSet_ParseStruct() {
	var tar Tar

	NewFlagSet(Flag{}).ParseStruct(&tar, "tar", "-zcf", "a.tgz", "a.go", "b.go")
	fmt.Println(tar.GZ)
	fmt.Println(tar.Create)
	fmt.Println(tar.File)
	fmt.Println(tar.SourceFiles)

	// Output:
	// true
	// true
	// a.tgz
	// [a.go b.go]
}

Help message

tar is a tool for manipulate tape archives.

Usage:
      flag.test [FLAG]...

Version:
      version: v1.0.0
      commit: 10adf10dc10
      date:   2017-01-01 10:00:01

Description:
      tar creates and manipulates streaming archive files.  This implementation can extract
      from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images and can create tar, pax,
      cpio, ar, and shar archives.

Flags:
      -z, --gz     gzip format (bool)
            use gzip format
      -j, --bz     bzip2 format (bool)
      -J, --xz     xz format (bool)
      -c           create tar file (bool)
      -x           extract tar file (bool)
      -f           output file for create or input file for extract (string)
      -C           extract directory (string)

FlagSet

type GoCmd struct {
	Build struct {
		Enable  bool
		Already bool   `names:"-a" important:"1" desc:"force rebuilding of packages that are already up-to-date."`
		Race    bool   `important:"1" desc:"enable data race detection.\nSupported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64."`
		Output  string `names:"-o" arglist:"output" important:"1" desc:"only allowed when compiling a single package"`

		LdFlags  string   `names:"-ldflags" arglist:"'flag list'" desc:"arguments to pass on each go tool link invocation."`
		Packages []string `args:"true"`
	} `usage:"compile packages and dependencies"`
	Clean struct {
		Enable bool
	} `usage:"remove object files"`
	Doc struct {
		Enable bool
	} `usage:"show documentation for package or symbol"`
	Env struct {
		Enable bool
	} `usage:"print Go environment information"`
	Bug struct {
		Enable bool
	} `usage:"start a bug report"`
	Fix struct {
		Enable bool
	} `usage:"run go tool fix on packages"`
	Fmt struct {
		Enable bool
	} `usage:"run gofmt on package sources"`
}

func (*GoCmd) Metadata() map[string]Flag {
	return map[string]Flag{
		"": {
			Usage:   "Go is a tool for managing Go source code.",
			Arglist: "command [argument]",
		},
		"build": {
			Arglist: "[-o output] [-i] [build flags] [packages]",
			Desc: `
		Build compiles the packages named by the import paths,
		along with their dependencies, but it does not install the results.
		...
		The build flags are shared by the build, clean, get, install, list, run,
		and test commands:
			`,
		},
	}
}

func TestSubset(t *testing.T) {
	var g GoCmd

	set := NewFlagSet(Flag{})
	set.StructFlags(&g)
	set.Help(false)
	fmt.Println()
	build, _ := set.FindSubset("build")
	build.Help(false)
}

##Help Message

Go is a tool for managing Go source code.

Usage:
      flag.test command [argument]

Sets:
      build        compile packages and dependencies
      clean        remove object files
      doc          show documentation for package or symbol
      env          print Go environment information
      bug          start a bug report
      fix          run go tool fix on packages
      fmt          run gofmt on package sources

compile packages and dependencies

Usage:
      build [-o output] [-i] [build flags] [packages]

Description:
      Build compiles the packages named by the import paths,
      along with their dependencies, but it does not install the results.
      ...
      The build flags are shared by the build, clean, get, install, list, run,
      and test commands:

Flags:
      -a                  
            force rebuilding of packages that are already up-to-date.
      -race               
            enable data race detection.
            Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64.
      -o output           
            only allowed when compiling a single package

      -ldflags 'flag list'
            arguments to pass on each go tool link invocation.

LICENSE

MIT.

Documentation

Index

• Variables
• func Help()
• func ParseStruct(val interface{}, args ...string) error
• type ErrorHandling
• type Flag
• type FlagSet
  • func NewFlagSet(flag Flag) *FlagSet
  • func (f *FlagSet) ErrHandling(ehs ...ErrorHandling) *FlagSet
  • func (f *FlagSet) FindFlag(children string) (*Flag, error)
  • func (f *FlagSet) FindSubset(children string) (*FlagSet, error)
  • func (f *FlagSet) Flag(flag Flag) error
  • func (f *FlagSet) Help()
  • func (f *FlagSet) NeedHelpFlag(need bool) *FlagSet
  • func (f *FlagSet) Parse(args ...string) error
  • func (f *FlagSet) ParseStruct(val interface{}, args ...string) error
  • func (f *FlagSet) Reset()
  • func (f *FlagSet) String() string
  • func (f *FlagSet) StructFlags(val interface{}, parent ...*FlagSet) error
  • func (f *FlagSet) Subset(flag Flag) (*FlagSet, error)
  • func (f *FlagSet) UpdateMeta(children string, meta Flag) error
• type Metadata
• type NoFlag

Examples

• FlagSet.ParseStruct

Variables

var (
	// Commandline is the default FlagSet instance.
	Commandline = NewFlagSet(Flag{})
)

Functions

func Help

func Help()

Help is the short way of Commandline.Help

func ParseStruct

func ParseStruct(val interface{}, args ...string) error

ParseStruct is short way of Commandline.ParseStruct

Types

type ErrorHandling

type ErrorHandling uint8

ErrorHandling is the error handling way when error occurred when register/scan/resolve.

ErrorHandling can be set of basic handling way, the way sequence is ErrPanic, ErrPrint, ErrExit.

const (
	// ErrPanic panic goroutine with the error
	ErrPanic ErrorHandling = 1 << iota
	// ErrPrint print the error to stdout
	ErrPrint
	// ErrExit exit process
	ErrExit

	// DefaultErrorHandling includes ErrPrint and ErrExit
	DefaultErrorHandling = ErrPrint | ErrExit
)

type Flag

type Flag struct {
	// Common fields used for Flag and FlagSet
	Names   string // names, split by ','
	Arglist string // arguments list
	Usage   string // short usage message
	Desc    string // long description, can be multiple lines

	Ptr interface{} // value pointer

	// For Flag
	Default interface{} // default value
	Selects interface{} // select value
	Env     string      // environment name
	ValSep  string      // environment value separator

	// For FlagSet
	Version string // version, can be multiple lines

	ArgsPtr      *[]string // non-flag arguments pointer
	ArgsAnywhere bool      // non-flag args must appears at anywhere, otherwise, it must appears at command line last.
	// contains filtered or unexported fields
}

Flag represents the state of a flag

type FlagSet

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

FlagSet is a set of flags and other subsets.

func NewFlagSet

func NewFlagSet(flag Flag) *FlagSet

NewFlagSet create a new flagset

func (*FlagSet) ErrHandling

func (f *FlagSet) ErrHandling(ehs ...ErrorHandling) *FlagSet

ErrHandling change the way of error handling

func (*FlagSet) FindFlag

func (f *FlagSet) FindFlag(children string) (*Flag, error)

FindFlag search flag by the children identifier, children is set subset/flag names split by ','.

func (*FlagSet) FindSubset

func (f *FlagSet) FindSubset(children string) (*FlagSet, error)

FindSubset search flagset by the children identifier, children is subset names split by ','.

func (*FlagSet) Flag

func (f *FlagSet) Flag(flag Flag) error

Flag add a flag to current flagset, it should not duplicate with parent/current/children levels' flag or flagset.

func (*FlagSet) Help

func (f *FlagSet) Help()

Help print help message to stdout

func (*FlagSet) NeedHelpFlag

func (f *FlagSet) NeedHelpFlag(need bool) *FlagSet

NeedHelpFlag toggle help flags auto-defining. By default, if there is no help flag, it will be defined when Parse is called.

func (*FlagSet) Parse

func (f *FlagSet) Parse(args ...string) error

Parse parse arguments, if empty, os.Args will be used.

func (*FlagSet) ParseStruct

func (f *FlagSet) ParseStruct(val interface{}, args ...string) error

ParseStruct is the combination of StructFlags and Parse

Example

package main

import "fmt"

type Tar struct {
	GZ          bool     `names:"-z, --gz" usage:"gzip format"`
	BZ          bool     `names:"-j, --bz" usage:"bzip2 format"`
	XZ          bool     `names:"-J, --xz" usage:"xz format"`
	Create      bool     `names:"-c" usage:"create tar file"`
	Extract     bool     `names:"-x" usage:"extract tar file"`
	File        string   `names:"-f" usage:"output file for create or input file for extract"`
	Directory   string   `names:"-C" usage:"extract directory"`
	SourceFiles []string `args:"true"`
}

func (t *Tar) Metadata() map[string]Flag {
	const (
		usage   = "tar is a tool for manipulate tape archives."
		version = `
			version: v1.0.0
			commit: 10adf10dc10
			date:   2017-01-01 10:00:01
		`
		desc = `
		tar creates and manipulates streaming archive files.  This implementation can extract
		from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images and can create tar, pax,
		cpio, ar, and shar archives.
		`
	)
	return map[string]Flag{
		"": {
			Usage:   usage,
			Version: version,
			Desc:    desc,
		},
		"--gz": {
			Desc: "use gzip format",
		},
	}
}

func main() {
	var tar Tar

	NewFlagSet(Flag{}).ParseStruct(&tar, "tar", "-zcf", "a.tgz", "a.go", "b.go")
	fmt.Println(tar.GZ)
	fmt.Println(tar.Create)
	fmt.Println(tar.File)
	fmt.Println(tar.SourceFiles)

}

type GoCmd struct {
	Build struct {
		Enable  bool
		Already bool   `names:"-a" important:"1" desc:"force rebuilding of packages that are already up-to-date."`
		Race    bool   `important:"1" desc:"enable data race detection.\nSupported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64."`
		Output  string `names:"-o" arglist:"output" important:"1" desc:"only allowed when compiling a single package"`

		LdFlags  string   `names:"-ldflags" arglist:"'flag list'" desc:"rguments to pass on each go tool link invocation."`
		Packages []string `args:"true"`
	} `usage:"compile packages and dependencies"`
	Clean struct {
		Enable bool
	} `usage:"remove object files"`
	Doc struct {
		Enable bool
	} `usage:"show documentation for package or symbol"`
	Env struct {
		Enable bool
	} `usage:"print Go environment information"`
	Bug struct {
		Enable bool
	} `usage:"start a bug report"`
	Fix struct {
		Enable bool
	} `usage:"run go tool fix on packages"`
	Fmt struct {
		Enable bool
	} `usage:"run gofmt on package sources"`
}

func (*GoCmd) Metadata() map[string]Flag {
	return map[string]Flag{
		"": {
			Usage:   "Go is a tool for managing Go source code.",
			Arglist: "command [argument]",
		},
		"build": {
			Arglist: "[-o output] [-i] [build flags] [packages]",
			Desc: `
		Build compiles the packages named by the import paths,
		along with their dependencies, but it does not install the results.
		...
		The build flags are shared by the build, clean, get, install, list, run,
		and test commands:
			`,
		},
	}
}

Output:

true
true
a.tgz
[a.go b.go]

func (*FlagSet) Reset

func (f *FlagSet) Reset()

Reset reset values of each registered flags.

func (*FlagSet) String

func (f *FlagSet) String() string

String return help message

func (*FlagSet) StructFlags

func (f *FlagSet) StructFlags(val interface{}, parent ...*FlagSet) error

StructFlags parse the structure pointer and add exported fields to flagset. if parent is not nil, it will checking duplicate flags with parent.

func (*FlagSet) Subset

func (f *FlagSet) Subset(flag Flag) (*FlagSet, error)

Subset add a flagset to current flagset and return the subset

func (*FlagSet) UpdateMeta

func (f *FlagSet) UpdateMeta(children string, meta Flag) error

UpdateMeta update flag metadata by the children identifier, only Desc, Arglist, Usage and Version will be updated. The children identifier will be split by ',', if children is empty, it update itself.

E.g., "tool, cover, -html": Flag{Usage:"display coverage in html"}

type Metadata

type Metadata interface {
	// Metadata return the metadata map to be updated.
	// The return value is a map of children and metadata.
	Metadata() map[string]Flag
}

Metadata can be implemented by structure to update flag metadata.

type NoFlag

type NoFlag interface {
	// NoFlag method identify the field should not be parsed
	NoFlag()
}

NoFlag can be implemented by structure or field to prevent from parsing