Documentation
¶
Overview ¶
Package getopt offers utilities for parsing getopt-style command-line options (flags).
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Alias ¶ added in v0.0.10
Alias is a simply utility for registering flag aliases, registering a new flag in fs with name alias with the flag.Value of a flag named name.
If flag name doesn't exist in fs, panic.
func Hide ¶
Hide hides the given flag.
Example ¶
This example demonstrates the usage of getopt.Hidden and getopt.Hide.
package main
import (
"flag"
"fmt"
"os"
"github.com/brandon1024/cmder/getopt"
)
func main() {
var (
count uint
output string
)
fs := getopt.NewPosixFlagSet("hidden", flag.ContinueOnError)
fs.UintVar(&count, "count", 12, "`number` of results")
fs.UintVar(&count, "c", 12, "`number` of results (hidden flag)")
fs.StringVar(&output, "output", "-", "output `file`")
fs.StringVar(&output, "o", "-", "output `file`")
// option 1: wrap the flag value
fs.Lookup("c").Value = &getopt.Hidden{fs.Lookup("c").Value}
// option 2: use getopt.Hide
getopt.Hide(fs.Lookup("o"))
// option 3: using FlagSet.Var
var since getopt.TimeVar
fs.Var(&getopt.Hidden{&since}, "since", "show items since")
fs.SetOutput(os.Stdout)
fs.PrintDefaults()
args := []string{"-c", "2025", "-o", "output.txt", "--since", "2025-01-01T00:00:00Z"}
if err := fs.Parse(args); err != nil {
panic(err)
}
fmt.Printf("values: %d %s %s\n", count, output, since.String())
}
Output: --count <number> (default 12) number of results --output <file> (default -) output file values: 2025 output.txt 2025-01-01T00:00:00Z
Types ¶
type Hidden ¶
Hidden is a flag.Value that is hidden from PosixFlagSet.PrintDefaults output.
func (*Hidden) IsHiddenFlag ¶
IsHiddenFlag implements HiddenFlag and returns true.
type HiddenFlag ¶
HiddenFlag is a flag.Value that should be hidden from PosixFlagSet.PrintDefaults output.
type MapVar ¶
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
Example ¶
This example demonstrates usage of getopt.MapVar for string maps. You'll often find map flags on commands that perform templating of text files, for example.
package main
import (
"flag"
"fmt"
"maps"
"slices"
"github.com/brandon1024/cmder/getopt"
)
func main() {
variables := getopt.MapVar{}
fs := flag.NewFlagSet("map", flag.ContinueOnError)
fs.Var(&variables, "variable", "specify runtime variables")
fs.Var(&variables, "v", "specify runtime variables")
args := []string{
"--variable", "key1=value1",
"-v", "key2=value2,key3=value3",
`--variable="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])
}
}
Output: hello: ' HI, WORLD ' key1: 'value1' key2: 'value2' key3: 'value3'
func (MapVar) Get ¶
Get fulfills the flag.Getter interface, allowing typed access to the flag value. In this case, returns a map[string]string.
func (MapVar) Set ¶
Set fulfills the flag.Value interface. The given value must be a set of key-value pairs.
type PosixFlagSet ¶
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 ¶
func NewPosixFlagSet(name string, e flag.ErrorHandling) *PosixFlagSet
NewPosixFlagSet builds a new flag.FlagSet and wraps it with a PosixFlagSet.
func (*PosixFlagSet) Arg ¶
func (f *PosixFlagSet) Arg(i int) string
Arg returns the i'th remaining argument after calling PosixFlagSet.Parse. Returns an empty string if the argument does not exist, or PosixFlagSet.Parse was not called.
func (*PosixFlagSet) Args ¶
func (f *PosixFlagSet) Args() []string
Args returns a slice of non-flag arguments remaining after calling PosixFlagSet.Parse.
func (*PosixFlagSet) NArg ¶
func (f *PosixFlagSet) NArg() int
NArg returns the number of non-flag arguments remaining after calling PosixFlagSet.Parse.
func (*PosixFlagSet) Parse ¶
func (f *PosixFlagSet) Parse(arguments []string) error
Parse processes the given arguments and updates the flags of this flag set. The arguments given should not include the command name. Parse should only be called after all flags have been registered and before flags are accessed by the application.
The return value will be flag.ErrHelp if -help or -h were set but not defined.
func (*PosixFlagSet) Parsed ¶
func (f *PosixFlagSet) Parsed() bool
Parsed returns whether or not PosixFlagSet.Parse has been invoked on this flag set.
func (*PosixFlagSet) PrintDefaults ¶
func (f *PosixFlagSet) PrintDefaults()
PrintDefaults prints usage information and default values for all flags of this flag set to the output location configured with flag.FlagSet.Init or flag.FlagSet.SetOutput.
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"
Example ¶
This example demonstrates usage of getopt.StringsVar for string slice flags. You'll often find string sliceee flags on commands that accept IP addresses, for example.
package main
import (
"flag"
"fmt"
"github.com/brandon1024/cmder/getopt"
)
func main() {
hosts := getopt.StringsVar{}
fs := flag.NewFlagSet("stringsvar", flag.ContinueOnError)
fs.Var(&hosts, "broker", "connect to a broker")
fs.Var(&hosts, "b", "connect to a broker")
args := []string{
"--broker", "tcp://127.0.0.1",
"-b", "tls://broker-1.domain.example.com,tls://broker-2.domain.example.com",
}
if err := fs.Parse(args); err != nil {
panic(err)
}
for _, host := range hosts {
fmt.Printf("'%s'\n", host)
}
}
Output: 'tcp://127.0.0.1' 'tls://broker-1.domain.example.com' 'tls://broker-2.domain.example.com'
func (StringsVar) Get ¶ added in v0.0.5
func (s StringsVar) Get() any
Get fulfills the flag.Getter interface, allowing typed access to the flag value. In this case, returns a []string.
func (*StringsVar) Set ¶ added in v0.0.5
func (s *StringsVar) Set(value string) error
Set fulfills the flag.Value interface.
func (StringsVar) String ¶ added in v0.0.5
func (s StringsVar) String() string
String returns the slice, formatted as comma-separated values.
type TimeVar ¶
TimeVar is a flag.Value for flags that accept timestamps in time.RFC3339 format. TimeVar also implements flag.Getter.
Example ¶
This example demonstrates the usage of getopt.TimeVar.
package main
import (
"flag"
"fmt"
"github.com/brandon1024/cmder/getopt"
)
func main() {
var since getopt.TimeVar
fs := flag.NewFlagSet("custom", flag.ContinueOnError)
fs.Var(&since, "since", "show items since")
args := []string{
"-since", "2025-01-01T00:00:00Z",
}
if err := fs.Parse(args); err != nil {
panic(err)
}
fmt.Printf("since: %s\n", since.String())
}
Output: since: 2025-01-01T00:00:00Z
func (*TimeVar) Get ¶
Get fulfills the flag.Getter interface, allowing typed access to the flag value. In this case, returns a time.Time.
func (*TimeVar) Set ¶
Set fulfills the flag.Value interface. The given value must be a correctly formatted time.RFC3339 timestamp.
func (*TimeVar) String ¶
String returns the time.RFC3339 representation of the timestamp flag.
Source Files