flagex

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2020 License: MIT Imports: 7 Imported by: 0

README

Description

flagex is a command line parser with (optional) pacman-like style parsing.

It works with string values as its intermediate type. Reflect-based helpers are in the reflag package, which works, but has errorproofing left to do.

Status

Functionality I had in mind is in. Additional helpers might be added. Not 100% on the API yet, but any further changes should be minor.

Example


	// Define a sub.
	svpar := New()
	svpar.Req("addr", "a", "Listen address.", "HOSTNAME|IP", "0.0.0.0")
	svpar.Opt("tlsmode", "t", "specify TLS mode", "v1|v2|v3", "v3")

	// Define root.
	flags := New()
	flags.Sub("srvparams", "s", "Server parameters.", svpar)
	flags.Req("config", "c", "Specify config file.", "filename", "settings.json")
	flags.Switch("verbose", "v", "Verbose output.")

	if err := flags.Parse(os.Args[1:]); err != nil {
		// Use flags:
		// flags.Parsed()
		// flags.ParseMap()
		// flags.Print()
		// ...
	}

	// Example command line:
	//
	// Same effect:
	// --verbose --config mysettings.json --srvparams --tlsmode v3 -a 127.0.0.1
	// -v -c mysettings.json -st v3 --addr 127.0.0.1

	// flags.Print() yields:
	//
	//	-s   --srvparams           Server parameters.     
	//		-a                    --addr <HOSTNAME|IP>   Listen address.    
	//		-t                    --tlsmode <v1|v2|v3>   specify TLS mode   
	//	-c   --config <filename>   Specify config file.   
	//	-v   --verbose             Verbose output.

License

MIT.

Documentation

Overview

Package flagex implements a command line parser. Not thread-safe.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrFlagex is the base flagex error.
	ErrFlagex = errorex.New("flagex")
	// ErrNoArgs is returned when Parse is called with empty arguments.
	ErrNoArgs = ErrFlagex.Wrap("no arguments")
	// ErrInvalid is returned when an invalid flag key is specified.
	ErrInvalid = ErrFlagex.WrapFormat("invalid key")
	// ErrNotFound is returned when a non existent key is requested.
	ErrNotFound = ErrFlagex.WrapFormat("key '%s' not found")
	// ErrDuplicate is returned when a flag with a duplicate key is being
	// registered.
	ErrDuplicate = ErrFlagex.WrapFormat("duplicate key '%s'")
	// ErrDupShort is returned when a flag with a duplicate shortkey is being
	// registered.
	ErrDupShort = ErrFlagex.WrapFormat("duplicate shortkey '%s'")
	// ErrExclusive is returned when a more than one flag from an exclusive set
	// is parsed.
	ErrExclusive = ErrFlagex.WrapFormat("'%s' is exclusive to '%s'")
	// ErrRequired is returned when a required flag was not parsed.
	ErrRequired = ErrFlagex.WrapFormat("required key '%s' not specified")
	// ErrReqVal is returned when no value was passed to a key that requires
	// one.
	ErrReqVal = ErrFlagex.WrapFormat("arg '%s' requires a param.")
	// ErrSwitch is returned when a switch was passed a param.
	ErrSwitch = ErrFlagex.WrapFormat("switch '%s' takes no params")
	// ErrSub is returned when a sub switch was parsed with no args following
	// it.
	ErrSub = ErrFlagex.WrapFormat("sub '%s' invoken with no params")
	// ErrNotSub is returned when a non-sub switch is combined with other
	// commands.
	ErrNotSub = ErrFlagex.WrapFormat("cannot combine key '%s', not a sub.")
)

Functions

This section is empty.

Types

type Flag 

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

Flag represents flag defined in Flags.

func (*Flag) Default 

func (f *Flag) Default() string

Default is returned by Value if no value was parsed for this Flag.

func (*Flag) Excl 

func (f *Flag) Excl() bool

Excl returns if this flag is exclusive in Flags.

func (*Flag) Help 

func (f *Flag) Help() string

Help returns Flag help text.

func (*Flag) Key 

func (f *Flag) Key() string

Key returns Flag key.

func (*Flag) Kind 

func (f *Flag) Kind() FlagKind

Kind returns Flag kind.

func (*Flag) ParamHelp 

func (f *Flag) ParamHelp() string

ParamHelp returns Flag param help text.

func (*Flag) Parsed 

func (f *Flag) Parsed() bool

Parsed returns if this Flag was parsed.

func (*Flag) ParsedVal 

func (f *Flag) ParsedVal() bool

ParsedVal returns if Flag as well as a parameter to it value was parsed.

func (*Flag) SetDefault 

func (f *Flag) SetDefault(defval string)

SetDefault sets flag's default value.

func (*Flag) SetHelp 

func (f *Flag) SetHelp(help string)

SetHelp sets flag's help text.

func (*Flag) SetParamHelp 

func (f *Flag) SetParamHelp(help string)

SetParamHelp sets flag's param help text.

func (*Flag) Shortkey 

func (f *Flag) Shortkey() string

Shortkey returns Flag shortkey.

func (*Flag) Sub 

func (f *Flag) Sub() *Flags

Sub returns flags sub flags, if any.

func (*Flag) Value 

func (f *Flag) Value() string

Value returns current Flag value.

type FlagKind 

type FlagKind byte

FlagKind specifies Flag kind. 

const (
	// KindOptional marks a flag as optional as well as its params.
	KindOptional FlagKind = iota
	// KindRequired marks a flag as required as well as is its params.
	KindRequired
	// KindSwitch marks a flag as optional that takes no params.
	// Flags with sub flags take no flags and are marked as KindSwitch.
	KindSwitch
	// KindSub marks a flag as a Flags subcategory prefix.
	KindSub
)

func (FlagKind) String 

func (fk FlagKind) String() string

String implements Stringer interface on FlagKind.

type Flags 

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

Flags holds a set of unique flags.

func New 

func New() *Flags

New creates a new Flags instance.

func (*Flags) Define added in v0.2.0 

func (f *Flags) Define(key, shortkey, help, paramhelp, defval string, typ FlagKind) (err error)

Define defines a flag under specified key and optional longkey with specified help and default value defval. key and shortkey must be unique in Flags, shortkey is optional. If a non-nil error is returned flag was not defined.

func (*Flags) DefineOptional added in v0.2.0 

func (f *Flags) DefineOptional(key, shortkey, help, paramhelp, defval string) (err error)

DefineOptional defines an optional flag with a required param.

func (*Flags) DefineRequired added in v0.2.0 

func (f *Flags) DefineRequired(key, shortkey, help, paramhelp, defval string) (err error)

DefineRequired defines a required flag with a required param.

func (*Flags) DefineSub added in v0.2.0 

func (f *Flags) DefineSub(key, shortkey, help string, sub *Flags) error

DefineSub defines child Flags under specified key and optional shortkey which must be unique in these Flags. When invoken rest of params are passed to it. help defines the flag help. If a non-nil error is returned flag was not defined.

func (*Flags) DefineSwitch added in v0.2.0 

func (f *Flags) DefineSwitch(key, shortkey, help string) (err error)

DefineSwitch defines an optional switch without a param.

func (*Flags) GetKey added in v0.2.0 

func (f *Flags) GetKey(key string) (flag *Flag, truth bool)

GetKey returns Flag if under specified key and a truth if it exists.

func (*Flags) GetShort added in v0.2.0 

func (f *Flags) GetShort(shortkey string) (flag *Flag, truth bool)

GetShort returns Flag under specified shortkey and a truth if it exists.

func (*Flags) GetValue added in v0.2.0 

func (f *Flags) GetValue(key string) string

GetValue will return current value of a key, if found. Returns an empty string otherwise. Check before if key was parsed with Parsed().

func (*Flags) Parse 

func (f *Flags) Parse(args []string) error

Parse parses specified args.

func (*Flags) ParseMap 

func (f *Flags) ParseMap() map[interface{}]interface{}

ParseMap returns a map of parsed Flag key:value pairs. Sub will return a map, Flags may return a string if parsed or nil if not parsed. ParseMap returns whichever args were parsed at last Parse. ParseMap is as valid as what Parse returned.

func (*Flags) Parsed 

func (f *Flags) Parsed(keys ...string) bool

Parsed returns if flags were parsed if no keys are specified. If one or more keys are specified, returns if all of the specified keys were specified and parsed.

func (*Flags) SetExclusive added in v0.2.0 

func (f *Flags) SetExclusive(keys ...string) error

SetExclusive sets specified keys as mutually exclusive in Flags. If more than one key from exclusive group are parsed, parse will error. Keys must already be defined. Subsequent calls redefine exclusivity.

func (*Flags) String added in v0.1.1 

func (f *Flags) String() string

String returns a printable string of Flags.

Source Files

View all Source files

Directories

Path Synopsis
Package reflag provides reflect based helpers for flagex.
 Package reflag provides reflect based helpers for flagex.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.