mauflag

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Dec 22, 2018 License: GPL-3.0 Imports: 5 Imported by: 27

README

mauflag

Build Status License

An extendable argument parser for Golang. Mostly follows the GNU Program Argument Syntax Conventions.

Use go get maunium.net/go/mauflag to get this package

Basic usage

A flag can have as many long or short keys as you like. Short keys are prefixed with one dash (-) whilst long keys are prefixed with two (--)

To create a flag, you must first call the Make() method in a flagset. Calling flagset methods as package functions uses the default flagset which takes input arguments from os.Args

After creating a flag, you can call the functions it has as you like. After configuring the flag, you can call one of the type functions to set the flag type and get a pointer to the value.

Examples

Here's a basic string flag that can be set using -s or --my-string-flag

var myStringFlag = flag.Make().ShortKey("s").LongKey("my-string-flag").Default("a string").String()

The following input arguments would set the value of the flag to foo

  • -s, foo
  • -s=foo
  • -sfoo
  • --my-string-flag, foo
  • --my-string-flag=foo
Chaining

Short boolean flags can be chained. The last flag of a chain doesn't necessarily have to be a boolean flag. For example, if we had the following flags defined

var boolA = flag.Make().ShortKey("a").Bool()
var boolB = flag.Make().ShortKey("b").Bool()
var boolC = flag.Make().ShortKey("c").Bool()
var stringD = flag.Make().ShortKey("d").String()

We could set the values of all the boolean flags to true with one input argument: -abc. We could also add the d flag to the end like so: -abcd, foo. Any of the other ways to set short flags also work (-abcd=foo, -abcdfoo).

However, if you put d as the first flag (-dabc) the value of the d flag will be abc and none of the boolean flags would change.

Godoc

More docs, including all values supported by default, can be found from godoc.org/maunium.net/go/mauflag

Custom values

All value containers must implement the Value interface. It contains two functions:

  • Set(string) which is called whenever the parser finds a value associated with the flag.
  • Name() which should return a human-readable name for the type of the value. If the value container contains multiple actual values, Name() should return the name of a single object (e.g. integer if the value container contains multiple integers)

After creating a value container you can use it by calling the Custom method of a Flag and giving an instance of the value container. The parser will then call the Set method each time it encounters a value associated with the flag.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Arg 

func Arg(i int) string

Arg returns the string at the given index from the list Args() returns If the index does not exist, Arg will return an empty string.

func Args 

func Args() []string

Args returns the arguments that weren't associated with any flag

func CheckHelpFlag 

func CheckHelpFlag() bool

CheckHelpFlag checks if the help flag is set and prints the help page if needed. Return value tells whether or not the help page was printed

func NArg 

func NArg() int

NArg returns the number of arguments not associated with any flags

func Parse 

func Parse() error

Parse the command line arguments into mauflag form

func PrintHelp 

func PrintHelp()

PrintHelp prints the help page

func SetHelpTitles 

func SetHelpTitles(firstLine, basicUsage string)

SetHelpTitles sets the first line (program name and basic explanation) and basic usage specification

Types

type Flag 

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

Flag represents a single flag

func Make 

func Make() *Flag

Make creates and registers a flag

func MakeFull 

func MakeFull(short, long, usage, defVal string) *Flag

MakeFull creates and registers a flag with the given short and long keys, usage string and default value

func MakeHelpFlag 

func MakeHelpFlag() (*bool, *Flag)

MakeHelpFlag creates the -h, --help flag

func MakeKey 

func MakeKey(short, long string) *Flag

MakeKey creates and registers a flag with the given short and long keys

func (*Flag) Bool 

func (flag *Flag) Bool() *bool

Bool sets the type of this flag to a boolean and returns a pointer to the value

func (*Flag) Byte 

func (flag *Flag) Byte() *byte

Byte sets the type of this flag to a byte (unsigned 8-bit integer) and returns a pointer to the value

func (*Flag) Custom 

func (flag *Flag) Custom(val Value)

Custom sets a custom object that implemets Value as the value of this flag

func (*Flag) Default 

func (flag *Flag) Default(defaul string) *Flag

Default sets the default value of this Flag The value given is passed to the Value container of this flag using `Set()`

func (*Flag) Float32 

func (flag *Flag) Float32() *float32

Float32 sets the type of this flag to an 32-bit float and returns a pointer to the value

func (*Flag) Float64 

func (flag *Flag) Float64() *float64

Float64 sets the type of this flag to an 64-bit float and returns a pointer to the value

func (*Flag) Int 

func (flag *Flag) Int() *int

Int sets the type of this flag to a signed default-length integer and returns a pointer to the value

func (*Flag) Int16 

func (flag *Flag) Int16() *int16

Int16 sets the type of this flag to a signed 16-bit integer and returns a pointer to the value

func (*Flag) Int32 

func (flag *Flag) Int32() *int32

Int32 sets the type of this flag to a signed 32-bit integer and returns a pointer to the value

func (*Flag) Int64 

func (flag *Flag) Int64() *int64

Int64 sets the type of this flag to a signed 64-bit integer and returns a pointer to the value

func (*Flag) Int64Array 

func (flag *Flag) Int64Array() *[]int64

Int64Array sets the type of this flag to a signed 64-bit integer array and returns a pointer to the value

func (*Flag) Int8 

func (flag *Flag) Int8() *int8

Int8 sets the type of this flag to a signed 8-bit integer and returns a pointer to the value

func (*Flag) IntArray 

func (flag *Flag) IntArray() *[]int

IntArray sets the type of this flag to a signed default-length integer array and returns a pointer to the value

func (*Flag) Key 

func (flag *Flag) Key(short, long string) *Flag

Key adds a long and a short key to this Flag

func (*Flag) LongKey 

func (flag *Flag) LongKey(key string) *Flag

LongKey adds a long key to this Flag

func (*Flag) Rune 

func (flag *Flag) Rune() *rune

Rune sets the type of this flag to a rune (signed 32-bit integer) and returns a pointer to the value

func (*Flag) ShortKey 

func (flag *Flag) ShortKey(key string) *Flag

ShortKey adds a short key to this Flag

func (*Flag) String 

func (flag *Flag) String() *string

String sets the type of this flag to a string and returns a pointer to the value

func (*Flag) StringArray 

func (flag *Flag) StringArray() *[]string

StringArray sets the type of this flag to a string array and returns a pointer to the value

func (*Flag) StringMap 

func (flag *Flag) StringMap() *map[string]string

StringMap sets the type of this flag to a string-string map and returns a pointer to the value

func (*Flag) Uint 

func (flag *Flag) Uint() *uint

Uint sets the type of this flag to an unsigned default-length integer and returns a pointer to the value

func (*Flag) Uint16 

func (flag *Flag) Uint16() *uint16

Uint16 sets the type of this flag to an unsigned 16-bit integer and returns a pointer to the value

func (*Flag) Uint32 

func (flag *Flag) Uint32() *uint32

Uint32 sets the type of this flag to an unsigned 32-bit integer and returns a pointer to the value

func (*Flag) Uint64 

func (flag *Flag) Uint64() *uint64

Uint64 sets the type of this flag to an unsigned 64-bit integer and returns a pointer to the value

func (*Flag) Uint8 

func (flag *Flag) Uint8() *uint8

Uint8 sets the type of this flag to an unsigned 8-bit integer and returns a pointer to the value

func (*Flag) Usage 

func (flag *Flag) Usage(usage string) *Flag

Usage sets the usage of this Flag

func (*Flag) UsageCategory 

func (flag *Flag) UsageCategory(category string) *Flag

UsageCategory sets the category of this flag (e.g. Application or Help)

func (*Flag) ValueName 

func (flag *Flag) ValueName(valname string) *Flag

ValueName sets the value name in the usage page

type Set 

type Set struct {
	// The list of strings used as input
	InputArgs []string
	// Whether or not to ignore all flags after the user has entered two dashes with no flag key ("--")
	// If enabled, all arguments after two dashes with no flag key will go into the args array (@see Args())
	DoubleLineEscape bool
	// Whether or not to exit the program when there's an error
	// If enabled, the error message will be printed to `stderr` after which `os.Exit(1)` will be called.
	ExitOnError bool
	// contains filtered or unexported fields
}

Set is a set of flags with certain input arguments

func DefaultSet 

func DefaultSet() *Set

DefaultSet returns the default flagset which takes its arguments from os.Args

func New 

func New(args []string) *Set

New creates a new flagset

func (*Set) Arg 

func (fs *Set) Arg(i int) string

Arg returns the string at the given index from the list Args() returns If the index does not exist, Arg will return an empty string.

func (*Set) Args 

func (fs *Set) Args() []string

Args returns the arguments that weren't associated with any flag

func (*Set) CheckHelpFlag 

func (fs *Set) CheckHelpFlag() bool

CheckHelpFlag checks if the help flag is set and prints the help page if needed. Return value tells whether or not the help page was printed

func (*Set) Make 

func (fs *Set) Make() *Flag

Make creates and registers a flag

func (*Set) MakeFull 

func (fs *Set) MakeFull(short, long, usage, defVal string) *Flag

MakeFull creates and registers a flag with the given short and long keys, usage string and default value

func (*Set) MakeHelpFlag 

func (fs *Set) MakeHelpFlag() (*bool, *Flag)

MakeHelpFlag creates the -h, --help flag

func (*Set) MakeKey 

func (fs *Set) MakeKey(short, long string) *Flag

MakeKey creates and registers a flag with the given short and long keys

func (*Set) NArg 

func (fs *Set) NArg() int

NArg returns the number of arguments not associated with any flags

func (*Set) Parse 

func (fs *Set) Parse() error

Parse the input arguments in this flagset into mauflag form Before this function is called all the flags will have either the type default or the given default value

func (*Set) PrintHelp 

func (fs *Set) PrintHelp()

PrintHelp prints the help page

func (*Set) SetHelpTitles 

func (fs *Set) SetHelpTitles(firstLine, basicUsage string)

SetHelpTitles sets the first line (program name and basic explanation) and basic usage specification

type Value 

type Value interface {
	// Set or add the data in the given string to this value
	Set(string) error
	// Name should return the type name of this value or (if this value is an array,
	// a map or something of that sort) the type name of one object in this value
	Name() string
}

Value represents the value a flag has

Source Files

View all Source files

Directories

Path Synopsis

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.