getopt

type CounterType ¶ added in v0.0.13

type CounterType interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

CounterType describes all numeric types supported by the CounterVar type.

type CounterVar ¶ added in v0.0.13

type CounterVar[T CounterType] struct {
	// contains filtered or unexported fields
}

CounterVar is a boolean flag.Value which increments a signed or unsigned integer of type T every time it appears at the command line.

This type of flag is often used for describing log verbosity, where '-vvv' would be interpreted as setting the log level to 3.

To initialize a CounterVar, see Counter.

func Counter[T CounterType](value *T) *CounterVar[T]

package main

import (
	"flag"
	"fmt"

	"github.com/brandon1024/cmder/getopt"
)

func main() {
	var verbose uint

	fs := getopt.NewPosixFlagSet("counter", flag.ContinueOnError)
	fs.Var(getopt.Counter(&verbose), "v", "increase verbosity")

	if err := fs.Parse([]string{"-vvv"}); err != nil {
		panic(err)
	}

	fmt.Printf("verbosity: %d\n", verbose)
}

Output:
verbosity: 3

func (c *CounterVar[T]) Get() any

func (c *CounterVar[T]) IsBoolFlag() bool

func (c *CounterVar[T]) Set(value string) error

func (c *CounterVar[T]) String() string

type HiddenFlag ¶

type HiddenFlag interface {
	flag.Value
	IsHiddenFlag() bool
}

HiddenFlag is a flag.Value that should be hidden from PosixFlagSet.PrintDefaults output.

type HiddenVar ¶ added in v0.0.13

type HiddenVar struct {
	flag.Value
}

HiddenVar is a flag.Value that is hidden from PosixFlagSet.PrintDefaults output.

func (h *HiddenVar) IsHiddenFlag() bool

func (h *HiddenVar) String() string

type MapVar ¶

type MapVar map[string]string

MapVar is a flag.Value for flags that accept map values. MapVar also implements flag.Getter.

MapVar parses flag values which are key=value pairs. Multiple key=value pairs may be comma separated (e.g. key1=value1,key2=value2). Keys should be alphanumeric. Values can contain commas and whitespace if enclosed in double quotes.

key1=value1
key1=value1,key2=value2
"key1=value, 1","key2=value, 2"
key1=v=1,key2=v=2

package main

import (
	"flag"
	"fmt"
	"maps"
	"slices"

	"github.com/brandon1024/cmder/getopt"
)

func main() {
	fs := flag.NewFlagSet("map", flag.ContinueOnError)

	// option 1: use MapVar directly
	variables := getopt.MapVar{}
	fs.Var(&variables, "variable", "specify runtime variables")

	// option 2: wrap an existing map with Map
	arg := map[string]string{}
	fs.Var(getopt.Map(arg), "arg", "specify runtime args")

	args := []string{
		"--variable", "key1=value1",
		"--variable", "key2=value2,key3=value3",
		`--arg="hello= HI, WORLD "`,
	}

	if err := fs.Parse(args); err != nil {
		panic(err)
	}

	for _, k := range slices.Sorted(maps.Keys(variables)) {
		fmt.Printf("%s: '%s'\n", k, variables[k])
	}
	for _, k := range slices.Sorted(maps.Keys(arg)) {
		fmt.Printf("%s: '%s'\n", k, arg[k])
	}
}

Output:
key1: 'value1'
key2: 'value2'
key3: 'value3'
hello: ' HI, WORLD '

func Map(m map[string]string) MapVar

func (m MapVar) Get() any

func (m MapVar) Set(value string) error

func (m MapVar) String() string

type PosixFlagSet ¶

type PosixFlagSet struct {
	*flag.FlagSet
	// contains filtered or unexported fields
}

PosixFlagSet a wrapper over the standard flag.FlagSet that parses arguments with getopt-style (GNU/POSIX) semantics with short and long options.

Usage ¶

Start by initializing a new PosixFlagSet.

fs := getopt.NewPosixFlagSet("hello", flag.ContinueOnError)

You may also wrap an existing standard flag.FlagSet if you prefer.

fs := flag.NewFlagSet("hello", flag.ContinueOnError)
gfs := &getopt.PosixFlagSet{FlagSet: fs}

Add flags to your PosixFlagSet with [PosixFlagSet.StringVar], [PosixFlagSet.BoolVar], [PosixFlagSet.IntVar], etc.

var (
	output string
	all    bool
	count  int
)

fs.StringVar(&output, "output", "-", "output file location")
fs.BoolVar(&all, "a", false, "show all")
fs.IntVar(&count, "c", 0, "limit results to count")
fs.IntVar(&count, "count", 0, "limit results to count")

The example above declares a long string flag '--output', a short '-a' bool flag, and aliased flags '-c' / '--count'.

After all flags are defined, call PosixFlagSet.Parse to parse the flags.

err := fs.Parse(os.Args[1:])

One parsed, any remaining (unparsed) arguments can be accessed with PosixFlagSet.Arg or PosixFlagSet.Args.

Syntax ¶

PosixFlagSet distinguishes between long and short flags. A long flag is any flag whose name contains more than a single character, while a short flag has a name with a single character.

-a          // short boolean flag
--all       // long boolean flag
--all=false // disabled long boolean flag
-c 12       // short integer flag
-c12        // short integer flag with immediate value
--count 12  // long integer value
--count=12  // long integer value with immediate value

Short boolean flags may be combined into a single argument, and short flags accepting arguments may be "stuck" to the value:

-ac12       // equivalent to '-a -c 12'

Flag parsing stops just before the first non-flag argument ("-" is a non-flag argument) or after the terminator "--".

Flags which accept a number ([PosixFlagSet.Int], [PosixFlagSet.Uint], [PosixFlagSet.Float64], etc) will parse their arguments with strconv. For integers, binary/octal/decimal/hexadecimal numbers are accepted (see strconv.ParseInt and strconv.ParseUint). For floats, anything parseable by strconv.ParseFloat is accepted.

--count 12
--count 0xC
--count 0o14
--count 0b1100
--count 1.2E1

Boolean flags with an immediate value may be anything parseable by strconv.ParseBool.

--all=false
--all=FALSE
--all=f
--all=0

Duration flags accept any input valid for time.ParseDuration.

--since=3m2s

func NewPosixFlagSet(name string, e flag.ErrorHandling) *PosixFlagSet

func (f *PosixFlagSet) Arg(i int) string

func (f *PosixFlagSet) Args() []string

func (f *PosixFlagSet) NArg() int

func (f *PosixFlagSet) Parse(arguments []string) error

func (f *PosixFlagSet) Parsed() bool

func (f *PosixFlagSet) PrintDefaults()

type StringsVar ¶ added in v0.0.5

type StringsVar []string

StringsVar is a flag.Value for flags that accept one or more string values. StringsVar also implements flag.Getter.

StringsVar collects string arguments into a slice. Multiple string values may be comma separated (e.g. value1,value2). Values containing commas may be enclosed in double quotes.

value
value1,value2
"value, 1","value, 2"

package main

import (
	"flag"
	"fmt"

	"github.com/brandon1024/cmder/getopt"
)

func main() {
	fs := flag.NewFlagSet("stringsvar", flag.ContinueOnError)

	// option 1: use StringsVar directly
	var hosts getopt.StringsVar
	fs.Var(&hosts, "broker", "connect to a broker")

	// option 2: wrap an existing slice with Strings
	var args []string
	fs.Var(getopt.Strings(&args), "a", "provide args")

	// option 3: wrap an existing slice by pointer casting
	var patterns []string
	fs.Var((*getopt.StringsVar)(&patterns), "p", "provide patterns")

	fs.Parse([]string{
		"--broker", "tls://broker-1.domain.example.com,tls://broker-2.domain.example.com",
		"-a", "CLIENT_USER",
		"-a", "CLIENT_PASS",
		"-p", "**/*.go,*.mod,*.sum",
	})

	for _, host := range hosts {
		fmt.Printf("broker: '%s'\n", host)
	}
	for _, arg := range args {
		fmt.Printf("arg: '%s'\n", arg)
	}
	for _, pattern := range patterns {
		fmt.Printf("patterns: '%s'\n", pattern)
	}
}

Output:
broker: 'tls://broker-1.domain.example.com'
broker: 'tls://broker-2.domain.example.com'
arg: 'CLIENT_USER'
arg: 'CLIENT_PASS'
patterns: '**/*.go'
patterns: '*.mod'
patterns: '*.sum'

func Strings(ss *[]string) *StringsVar

func (s StringsVar) Get() any

func (s *StringsVar) Set(value string) error

func (s StringsVar) String() string

type TimeVar ¶

type TimeVar time.Time

TimeVar is a flag.Value for flags that accept timestamps in time.RFC3339 format. TimeVar also implements flag.Getter.

package main

import (
	"flag"
	"fmt"
	"time"

	"github.com/brandon1024/cmder/getopt"
)

func main() {
	fs := flag.NewFlagSet("custom", flag.ContinueOnError)

	// option 1: using TimeVar directly
	var since getopt.TimeVar
	fs.Var(&since, "since", "show items since")

	// option 2: with Time
	var until time.Time
	fs.Var(getopt.Time(&until), "until", "show items until")

	args := []string{
		"-since", "2025-01-01T00:00:00Z",
		"-until", "2026-01-01T00:00:00Z",
	}

	if err := fs.Parse(args); err != nil {
		panic(err)
	}

	fmt.Printf("since: %s\n", since.String())
	fmt.Printf("until: %s\n", until.String())
}

Output:
since: 2025-01-01T00:00:00Z
until: 2026-01-01 00:00:00 +0000 UTC

func Time(tm *time.Time) *TimeVar

func (t *TimeVar) Get() any

func (t *TimeVar) Set(value string) error

func (t *TimeVar) String() string