xflags

package
v0.0.0-...-796497b Latest Latest
Warning

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

 Go to latest Published: Aug 17, 2018 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package flaggy is a input flag parsing tool that supports subcommands positional values, and any-position flags without unnecessary complexeties.

Supported Flag Types

Strings and Ints 

-key=var
--key=var
--key var
-key var

Booleans (sets to true if flag is specified without value) 

--key
--key true
--key=false
-k false
-k=true
-k

All arguments after a double dash (--) are added as strings to the TrailingArguments slice.

Index

Constants

This section is empty.

Variables

View Source 
var DebugMode bool

DebugMode indicates that debug output should be enabled

View Source 
var DefaultHelpTemplate string

DefaultHelpTemplate is the help template that will be used for newly created subcommands and commands

View Source 
var TrailingArguments []string

TrailingArguments holds trailing arguments in the main parser after parsing has been run.

Functions

func AddPositionalValue 

func AddPositionalValue(assignmentVar *string, name string, relativePosition int, required bool, description string) error

AddPositionalValue adds a positional value to the main parser at the global context

func AttachSubcommand 

func AttachSubcommand(newSC *Subcommand, relativePosition int) error

AttachSubcommand adds a subcommand for parsing

func Bool 

func Bool(assignmentVar *bool, shortName string, longName string, description string) error

Bool adds a new bool flag

func BoolSlice 

func BoolSlice(assignmentVar *[]bool, shortName string, longName string, description string) error

BoolSlice adds a new slice of bools flag Specify the flag multiple times to fill the slice

func ByteSlice 

func ByteSlice(assignmentVar *[]byte, shortName string, longName string, description string) error

ByteSlice adds a new slice of bytes flag Specify the flag multiple times to fill the slice. Takes hex as input.

func Duration 

func Duration(assignmentVar *time.Duration, shortName string, longName string, description string) error

Duration adds a new time.Duration flag. Input format is described in time.ParseDuration(). Example values: 1h, 1h50m, 32s

func DurationSlice 

func DurationSlice(assignmentVar *[]time.Duration, shortName string, longName string, description string) error

DurationSlice adds a new time.Duration flag. Input format is described in time.ParseDuration(). Example values: 1h, 1h50m, 32s Specify the flag multiple times to fill the slice.

func Float32 

func Float32(assignmentVar *float32, shortName string, longName string, description string) error

Float32 adds a new float32 flag.

func Float32Slice 

func Float32Slice(assignmentVar *[]float32, shortName string, longName string, description string) error

Float32Slice adds a new float32 flag. Specify the flag multiple times to fill the slice.

func Float64 

func Float64(assignmentVar *float64, shortName string, longName string, description string) error

Float64 adds a new float64 flag.

func Float64Slice 

func Float64Slice(assignmentVar *[]float64, shortName string, longName string, description string) error

Float64Slice adds a new float64 flag. Specify the flag multiple times to fill the slice.

func HardwareAddr 

func HardwareAddr(assignmentVar *net.HardwareAddr, shortName string, longName string, description string) error

HardwareAddr adds a new net.HardwareAddr flag.

func HardwareAddrSlice 

func HardwareAddrSlice(assignmentVar *[]net.HardwareAddr, shortName string, longName string, description string) error

HardwareAddrSlice adds a new net.HardwareAddr slice flag. Specify the flag multiple times to fill the slice.

func IP 

func IP(assignmentVar *net.IP, shortName string, longName string, description string) error

IP adds a new net.IP flag.

func IPMask 

func IPMask(assignmentVar *net.IPMask, shortName string, longName string, description string) error

IPMask adds a new net.IPMask flag. IPv4 Only.

func IPMaskSlice 

func IPMaskSlice(assignmentVar *[]net.IPMask, shortName string, longName string, description string) error

IPMaskSlice adds a new net.HardwareAddr slice flag. IPv4 only. Specify the flag multiple times to fill the slice.

func IPSlice 

func IPSlice(assignmentVar *[]net.IP, shortName string, longName string, description string) error

IPSlice adds a new int8 slice flag. Specify the flag multiple times to fill the slice.

func Int 

func Int(assignmentVar *int, shortName string, longName string, description string) error

Int adds a new int flag

func Int16 

func Int16(assignmentVar *int16, shortName string, longName string, description string) error

Int16 adds a new int16 flag

func Int16Slice 

func Int16Slice(assignmentVar *[]int16, shortName string, longName string, description string) error

Int16Slice adds a new int16 slice flag. Specify the flag multiple times to fill the slice.

func Int32 

func Int32(assignmentVar *int32, shortName string, longName string, description string) error

Int32 adds a new int32 flag

func Int32Slice 

func Int32Slice(assignmentVar *[]int32, shortName string, longName string, description string) error

Int32Slice adds a new int32 slice flag. Specify the flag multiple times to fill the slice.

func Int64 

func Int64(assignmentVar *int64, shortName string, longName string, description string) error

Int64 adds a new int64 flag

func Int64Slice 

func Int64Slice(assignmentVar *[]int64, shortName string, longName string, description string) error

Int64Slice adds a new int64 slice flag. Specify the flag multiple times to fill the slice.

func Int8 

func Int8(assignmentVar *int8, shortName string, longName string, description string) error

Int8 adds a new int8 flag

func Int8Slice 

func Int8Slice(assignmentVar *[]int8, shortName string, longName string, description string) error

Int8Slice adds a new int8 slice flag. Specify the flag multiple times to fill the slice.

func IntSlice 

func IntSlice(assignmentVar *[]int, shortName string, longName string, description string) error

IntSlice adds a new int slice flag. Specify the flag multiple times to fill the slice.

func Parse 

func Parse() error

Parse parses flags as requested in the default package parser

func ParseArgs 

func ParseArgs(args []string) error

ParseArgs parses the passed args as if they were the arguments to the running binary. Targets the default main parser for the package.

func ResetParser 

func ResetParser()

ResetParser resets the main default parser to a fresh instance. Normally used in tests.

func SetDescription 

func SetDescription(description string)

SetDescription sets the description of the default package command parser

func SetName 

func SetName(name string)

SetName sets the name of the default package command parser

func SetVersion 

func SetVersion(version string)

SetVersion sets the version of the default package command parser

func ShowHelp 

func ShowHelp(message string)

ShowHelp shows parser help

func ShowHelpAndExit 

func ShowHelpAndExit(message string)

ShowHelpAndExit shows parser help and exits with status code 2

func String 

func String(assignmentVar *string, shortName string, longName string, description string) error

String adds a new string flag

func StringSlice 

func StringSlice(assignmentVar *[]string, shortName string, longName string, description string) error

StringSlice adds a new slice of strings flag Specify the flag multiple times to fill the slice

func UInt 

func UInt(assignmentVar *uint, shortName string, longName string, description string) error

UInt adds a new uint flag

func UInt16 

func UInt16(assignmentVar *uint16, shortName string, longName string, description string) error

UInt16 adds a new uint16 flag

func UInt16Slice 

func UInt16Slice(assignmentVar *[]uint16, shortName string, longName string, description string) error

UInt16Slice adds a new uint16 slice flag. Specify the flag multiple times to fill the slice.

func UInt32 

func UInt32(assignmentVar *uint32, shortName string, longName string, description string) error

UInt32 adds a new uint32 flag

func UInt32Slice 

func UInt32Slice(assignmentVar *[]uint32, shortName string, longName string, description string) error

UInt32Slice adds a new uint32 slice flag. Specify the flag multiple times to fill the slice.

func UInt64 

func UInt64(assignmentVar *uint64, shortName string, longName string, description string) error

UInt64 adds a new uint64 flag

func UInt64Slice 

func UInt64Slice(assignmentVar *[]uint64, shortName string, longName string, description string) error

UInt64Slice adds a new uint64 slice flag. Specify the flag multiple times to fill the slice.

func UInt8 

func UInt8(assignmentVar *uint8, shortName string, longName string, description string) error

UInt8 adds a new uint8 flag

func UInt8Slice 

func UInt8Slice(assignmentVar *[]uint8, shortName string, longName string, description string) error

UInt8Slice adds a new uint8 slice flag. Specify the flag multiple times to fill the slice.

func UIntSlice 

func UIntSlice(assignmentVar *[]uint, shortName string, longName string, description string) error

UIntSlice adds a new uint slice flag. Specify the flag multiple times to fill the slice.

Types

type ArgumentParser 

type ArgumentParser interface {
	SetValueForKey(key string, value string) (bool, error)
}

ArgumentParser represements a parser or subcommand

type Flag 

type Flag struct {
	ShortName   string
	LongName    string
	Description string

	Hidden        bool // indicates this flag should be hidden from help and suggestions
	AssignmentVar interface{}
	// contains filtered or unexported fields
}

Flag holds the base methods for all flag types

func (*Flag) HasName 

func (f *Flag) HasName(name string) bool

HasName indicates that this flag's short or long name matches the supplied name string

type Help 

type Help struct {
	Subcommands    []HelpSubcommand
	Positionals    []HelpPositional
	Flags          []HelpFlag
	UsageString    string
	CommandName    string
	PrependMessage string
	AppendMessage  string
	Message        string
	Description    string
}

Help represents the values needed to render a Help page

func (*Help) ExtractValues 

func (h *Help) ExtractValues(sc *Subcommand, message string)

ExtractValues extracts Help template values from a subcommand

type HelpFlag 

type HelpFlag struct {
	ShortName    string
	LongName     string
	Description  string
	DefaultValue string
}

HelpFlag is used to template string flag Help output

type HelpPositional 

type HelpPositional struct {
	Name         string
	Description  string
	Required     bool
	Position     int
	DefaultValue string
}

HelpPositional is used to template positional Help output

type HelpSubcommand 

type HelpSubcommand struct {
	ShortName   string
	LongName    string
	Description string
	Position    int
}

HelpSubcommand is used to template subcommand Help output

type Parser 

type Parser struct {
	Subcommand
	Version              string   // the optional version of the paser.
	ShowHelpWithHFlag    bool     // display help when -h or --help passed
	ShowVersionWithVFlag bool     // display the version when -v or --version passed
	ShowHelpOnUnexpected bool     // display help when an unexpected flag is passed
	TrailingArguments    []string // everything after a -- is placed here
	// contains filtered or unexported fields
}

Parser represents the set of vars and subcommands we are expecting from our input args, and the parser than handles them all.

func NewParser 

func NewParser(name string) *Parser

NewParser creates a new ArgumentParser ready to parse inputs

func (*Parser) Parse 

func (p *Parser) Parse() error

Parse calculates all flags and subcommands

func (*Parser) ParseArgs 

func (p *Parser) ParseArgs(args []string) error

ParseArgs parses as if the passed args were the os.Args, but without the binary at the 0 position in the array. An error is returned if there is a low level issue converting flags to their proper type. No error is returned for invalid arguments or missing require subcommands.

func (*Parser) ShowVersionAndExit 

func (p *Parser) ShowVersionAndExit()

ShowVersionAndExit shows the version of this parser

type PositionalValue 

type PositionalValue struct {
	Name          string // used in documentation only
	Description   string
	AssignmentVar *string // the var that will get this variable
	Position      int     // the position, not including switches, of this variable
	Required      bool    // this subcommand must always be specified
	Found         bool    // was this positional found during parsing?
	Hidden        bool    // indicates this positional value should be hidden from help
}

PositionalValue represents a value which is determined by its position relative to where a subcommand was detected.

type Subcommand 

type Subcommand struct {
	Name                  string
	ShortName             string
	Description           string
	Position              int // the position of this subcommand, not including flags
	Subcommands           []*Subcommand
	Flags                 []*Flag
	PositionalFlags       []*PositionalValue
	AdditionalHelpPrepend string             // additional prepended message when Help is displayed
	AdditionalHelpAppend  string             // additional appended message when Help is displayed
	Used                  bool               // indicates this subcommand was found and parsed
	HelpTemplate          *template.Template // template for Help output
	Hidden                bool               // indicates this subcommand should be hidden from help
}

Subcommand represents a subcommand which contains a set of child subcommands along with a set of flags relevant to it. Parsing runs until a subcommand is detected by matching its name and position. Once a matching subcommand is found, the next set of parsing occurs within that matched subcommand.

func NewSubcommand 

func NewSubcommand(name string) *Subcommand

NewSubcommand creates a new subcommand that can have flags or PositionalFlags added to it. The position starts with 1, not 0

func (*Subcommand) AddPositionalValue 

func (sc *Subcommand) AddPositionalValue(assignmentVar *string, name string, relativePosition int, required bool, description string) error

AddPositionalValue adds a positional value to the subcommand. the relativePosition starts at 1 and is relative to the subcommand it belongs to

func (*Subcommand) AttachSubcommand 

func (sc *Subcommand) AttachSubcommand(newSC *Subcommand, relativePosition int) error

AttachSubcommand adds a possible subcommand to the Parser.

func (*Subcommand) Bool 

func (sc *Subcommand) Bool(assignmentVar *bool, shortName string, longName string, description string) error

Bool adds a new bool flag

func (*Subcommand) BoolSlice 

func (sc *Subcommand) BoolSlice(assignmentVar *[]bool, shortName string, longName string, description string) error

BoolSlice adds a new slice of bools flag Specify the flag multiple times to fill the slice

func (*Subcommand) ByteSlice 

func (sc *Subcommand) ByteSlice(assignmentVar *[]byte, shortName string, longName string, description string) error

ByteSlice adds a new slice of bytes flag Specify the flag multiple times to fill the slice. Takes hex as input.

func (*Subcommand) Duration 

func (sc *Subcommand) Duration(assignmentVar *time.Duration, shortName string, longName string, description string) error

Duration adds a new time.Duration flag. Input format is described in time.ParseDuration(). Example values: 1h, 1h50m, 32s

func (*Subcommand) DurationSlice 

func (sc *Subcommand) DurationSlice(assignmentVar *[]time.Duration, shortName string, longName string, description string) error

DurationSlice adds a new time.Duration flag. Input format is described in time.ParseDuration(). Example values: 1h, 1h50m, 32s Specify the flag multiple times to fill the slice.

func (*Subcommand) FlagExists 

func (sc *Subcommand) FlagExists(name string) bool

FlagExists lets you know if the flag name exists as either a short or long name in the (sub)command

func (*Subcommand) Float32 

func (sc *Subcommand) Float32(assignmentVar *float32, shortName string, longName string, description string) error

Float32 adds a new float32 flag.

func (*Subcommand) Float32Slice 

func (sc *Subcommand) Float32Slice(assignmentVar *[]float32, shortName string, longName string, description string) error

Float32Slice adds a new float32 flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) Float64 

func (sc *Subcommand) Float64(assignmentVar *float64, shortName string, longName string, description string) error

Float64 adds a new float64 flag.

func (*Subcommand) Float64Slice 

func (sc *Subcommand) Float64Slice(assignmentVar *[]float64, shortName string, longName string, description string) error

Float64Slice adds a new float64 flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) HardwareAddr 

func (sc *Subcommand) HardwareAddr(assignmentVar *net.HardwareAddr, shortName string, longName string, description string) error

HardwareAddr adds a new net.HardwareAddr flag.

func (*Subcommand) HardwareAddrSlice 

func (sc *Subcommand) HardwareAddrSlice(assignmentVar *[]net.HardwareAddr, shortName string, longName string, description string) error

HardwareAddrSlice adds a new net.HardwareAddr slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) IP 

func (sc *Subcommand) IP(assignmentVar *net.IP, shortName string, longName string, description string) error

IP adds a new net.IP flag.

func (*Subcommand) IPMask 

func (sc *Subcommand) IPMask(assignmentVar *net.IPMask, shortName string, longName string, description string) error

IPMask adds a new net.IPMask flag. IPv4 Only.

func (*Subcommand) IPMaskSlice 

func (sc *Subcommand) IPMaskSlice(assignmentVar *[]net.IPMask, shortName string, longName string, description string) error

IPMaskSlice adds a new net.HardwareAddr slice flag. IPv4 only. Specify the flag multiple times to fill the slice.

func (*Subcommand) IPSlice 

func (sc *Subcommand) IPSlice(assignmentVar *[]net.IP, shortName string, longName string, description string) error

IPSlice adds a new int8 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) Int 

func (sc *Subcommand) Int(assignmentVar *int, shortName string, longName string, description string) error

Int adds a new int flag

func (*Subcommand) Int16 

func (sc *Subcommand) Int16(assignmentVar *int16, shortName string, longName string, description string) error

Int16 adds a new int16 flag

func (*Subcommand) Int16Slice 

func (sc *Subcommand) Int16Slice(assignmentVar *[]int16, shortName string, longName string, description string) error

Int16Slice adds a new int16 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) Int32 

func (sc *Subcommand) Int32(assignmentVar *int32, shortName string, longName string, description string) error

Int32 adds a new int32 flag

func (*Subcommand) Int32Slice 

func (sc *Subcommand) Int32Slice(assignmentVar *[]int32, shortName string, longName string, description string) error

Int32Slice adds a new int32 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) Int64Slice 

func (sc *Subcommand) Int64Slice(assignmentVar *[]int64, shortName string, longName string, description string) error

Int64Slice adds a new int64 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) Int8 

func (sc *Subcommand) Int8(assignmentVar *int8, shortName string, longName string, description string) error

Int8 adds a new int8 flag

func (*Subcommand) Int8Slice 

func (sc *Subcommand) Int8Slice(assignmentVar *[]int8, shortName string, longName string, description string) error

Int8Slice adds a new int8 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) IntSlice 

func (sc *Subcommand) IntSlice(assignmentVar *[]int, shortName string, longName string, description string) error

IntSlice adds a new int slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) SetHelpTemplate 

func (sc *Subcommand) SetHelpTemplate(tmpl string) error

SetHelpTemplate sets the go template this parser will use when rendering Help.

func (*Subcommand) SetValueForKey 

func (sc *Subcommand) SetValueForKey(key string, value string) (bool, error)

SetValueForKey sets the value for the specified key. If setting a bool value, then send "true" or "false" as strings. The returned bool indicates that a value was set.

func (*Subcommand) ShowHelp 

func (sc *Subcommand) ShowHelp()

ShowHelp shows Help without an error message

func (*Subcommand) ShowHelpWithMessage 

func (sc *Subcommand) ShowHelpWithMessage(message string)

ShowHelpWithMessage shows the Help for this parser with an optional string error message as a header. The supplied subcommand will be the context of Help displayed to the user.

func (*Subcommand) String 

func (sc *Subcommand) String(assignmentVar *string, shortName string, longName string, description string) error

String adds a new string flag

func (*Subcommand) StringSlice 

func (sc *Subcommand) StringSlice(assignmentVar *[]string, shortName string, longName string, description string) error

StringSlice adds a new slice of strings flag Specify the flag multiple times to fill the slice

func (*Subcommand) UInt 

func (sc *Subcommand) UInt(assignmentVar *uint, shortName string, longName string, description string) error

UInt adds a new uint flag

func (*Subcommand) UInt16 

func (sc *Subcommand) UInt16(assignmentVar *uint16, shortName string, longName string, description string) error

UInt16 adds a new uint16 flag

func (*Subcommand) UInt16Slice 

func (sc *Subcommand) UInt16Slice(assignmentVar *[]uint16, shortName string, longName string, description string) error

UInt16Slice adds a new uint16 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) UInt32 

func (sc *Subcommand) UInt32(assignmentVar *uint32, shortName string, longName string, description string) error

UInt32 adds a new uint32 flag

func (*Subcommand) UInt32Slice 

func (sc *Subcommand) UInt32Slice(assignmentVar *[]uint32, shortName string, longName string, description string) error

UInt32Slice adds a new uint32 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) UInt64 

func (sc *Subcommand) UInt64(assignmentVar *uint64, shortName string, longName string, description string) error

UInt64 adds a new uint64 flag

func (*Subcommand) UInt64Slice 

func (sc *Subcommand) UInt64Slice(assignmentVar *[]uint64, shortName string, longName string, description string) error

UInt64Slice adds a new uint64 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) UInt8 

func (sc *Subcommand) UInt8(assignmentVar *uint8, shortName string, longName string, description string) error

UInt8 adds a new uint8 flag

func (*Subcommand) UInt8Slice 

func (sc *Subcommand) UInt8Slice(assignmentVar *[]uint8, shortName string, longName string, description string) error

UInt8Slice adds a new uint8 slice flag. Specify the flag multiple times to fill the slice.

func (*Subcommand) UIntSlice 

func (sc *Subcommand) UIntSlice(assignmentVar *[]uint, shortName string, longName string, description string) error

UIntSlice adds a new uint slice flag. Specify the flag multiple times to fill the slice.

Source Files

View all Source files

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.