flag

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Dec 27, 2025 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package flag is an alternative to the standard library package of the same name. This implementation adheres to POSIX/GNU standards for option and argument parsing. This package aims to be a simple drop-in replacement for the standard implementation and will continue to track the standard library flag package. No new features deviating from the standard implementation will be accepted.

Unless otherwise mentioned, the documentation for the standard library implementation applies here too. Refer to the documentation there for more information: 

https://pkg.go.dev/flag

Usage

Start by initializing a new FlagSet. 

fs := flag.NewFlagSet("hello", ContinueOnError)

Add flags to your FlagSet with FlagSet.StringVar, FlagSet.BoolVar, FlagSet.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 FlagSet.Parse to parse the flags. 

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

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

Syntax

FlagSet 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 (FlagSet.Int, FlagSet.Uint, FlagSet.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

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrHelp = errors.New("flag: help requested")
)
View Source 
var Usage = func() {
	_, err := fmt.Fprintf(CommandLine.Output(), "Usage of %s:\n", CommandLine.Name())
	if err != nil {
		panic(err)
	}

	CommandLine.PrintDefaults()
}

Usage is a simple usage function which prints usage information for the global CommandLine.

Functions

func Arg 

func Arg(i int) string

Arg returns FlagSet.Arg for the global CommandLine.

func Args 

func Args() []string

Args returns FlagSet.Args for the global CommandLine.

func Bool 

func Bool(name string, value bool, usage string) *bool

func BoolFunc 

func BoolFunc(name, usage string, fn func(string) error)

func BoolVar 

func BoolVar(p *bool, name string, value bool, usage string)

func Duration 

func Duration(name string, value time.Duration, usage string) *time.Duration

func DurationVar 

func DurationVar(p *time.Duration, name string, value time.Duration, usage string)

func Float64 

func Float64(name string, value float64, usage string) *float64

func Float64Var 

func Float64Var(p *float64, name string, value float64, usage string)

func Func 

func Func(name, usage string, fn func(string) error)

func Int 

func Int(name string, value int, usage string) *int

func Int64 

func Int64(name string, value int64, usage string) *int64

func Int64Var 

func Int64Var(p *int64, name string, value int64, usage string)

func IntVar 

func IntVar(p *int, name string, value int, usage string)

func NArg 

func NArg() int

NArg returns FlagSet.NArg for the global CommandLine.

func NFlag 

func NFlag() int

NFlag returns FlagSet.NFlag for the global CommandLine.

func Parse 

func Parse() error

Set invokes FlagSet.Parse for the global CommandLine with arguments from os.Args.

func Parsed 

func Parsed() bool

Parsed returns FlagSet.Parsed for the global CommandLine.

func PrintDefaults 

func PrintDefaults()

PrintDefaults calls FlagSet.PrintDefaults for the global CommandLine.

func Set 

func Set(name, value string) error

Set returns FlagSet.Set for the global CommandLine.

func String 

func String(name string, value string, usage string) *string

func StringVar 

func StringVar(p *string, name string, value string, usage string)

func TextVar 

func TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, usage string)

func Uint 

func Uint(name string, value uint, usage string) *uint

func Uint64 

func Uint64(name string, value uint64, usage string) *uint64

func Uint64Var 

func Uint64Var(p *uint64, name string, value uint64, usage string)

func UintVar 

func UintVar(p *uint, name string, value uint, usage string)

func UnquoteUsage 

func UnquoteUsage(flg *Flag) (string, string)

UnquoteUsage extracts a back-quoted name from the usage string for a Flag and returns it and the un-quoted usage.

Given 

var output string
fs := flag.NewFlagSet("echo", ContinueOnError)
fs.StringVar(&output, "output", "-", "output `file` location")

UnquoteUsage would return 

("file", "output file location").

If there are no back quotes, the name is an educated guess of the type of the flag's value, or the empty string if the flag is boolean.

func Var 

func Var(value Value, name string, usage string)

Set calls FlagSet.Var for the global CommandLine.

func Visit 

func Visit(fn func(*Flag))

Visit calls FlagSet.Visit for the global CommandLine.

func VisitAll 

func VisitAll(fn func(*Flag))

VisitAll calls FlagSet.VisitAll for the global CommandLine.

Types

type ErrorHandling 

type ErrorHandling int

ErrorHandling configures the error handling policy on a flag set, configuring the behaviour of FlagSet.Parse. 

const (
	// Return a descriptive error.
	ContinueOnError ErrorHandling = iota
	// Call os.Exit(2) or for -h/--help Exit(0).
	ExitOnError
	// Call panic with a descriptive error.
	PanicOnError
)

type Flag 

type Flag struct {
	// Name is the name of the flag, as it appears at the command line.
	Name string

	// Usage is a descriptive help message for the flag.
	Usage string

	// Value represents the value of the flag as parsed.
	Value Value

	// DefValue is the (stringified) default value for the flag.
	DefValue string
}

Flag represents a single short or long flag. It is identified by its name (e.g. 'h' for '-h' and 'help' for '--help'), and the value of the flag is represented by the Value interface.

type FlagSet 

type FlagSet struct {
	// Usage is a function called when an error occurs while parsing flags. It is invoked directly after an error is
	// encountered, but immediately before [FlagSet.Parse] returns the error or exits/panics (see [ErrorHandling]).
	//
	// If nil, defaults to [PrintDefaults].
	Usage func()
	// contains filtered or unexported fields
}

FlagSet is a set of flags. The zero value of a FlagSet has no name and has ContinueOnError error handling policy.

Unlike FlagSet in the standard library package, this FlagSet parses flags with POSIX/GNU semantics.

Flag names must be unique within a FlagSet. An attempt to define a flag whose name is already in use will cause a panic. Flag names must also be comprised of only alphanumeric characters, hyphens '-' (except at beginning or end of name), and periods '.'

Example

Two flags with the same Value can be used to create shorthand aliases for longer flags. For example, you may want to provide a shorthand `-u` for the longer `--until` flag. Simply use FlagSet.Lookup to fetch the flag and FlagSet.Var to create the shorthand. 

package main

import (
	"fmt"
	"time"

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

// Two flags with the same [Value] can be used to create shorthand aliases for longer flags. For example, you may want
// to provide a shorthand `-u` for the longer `--until` flag. Simply use [FlagSet.Lookup] to fetch the flag and
// [FlagSet.Var] to create the shorthand.
func main() {
	var since, until time.Duration

	fs := flag.NewFlagSet("alises", flag.ContinueOnError)
	fs.DurationVar(&since, "since", -time.Minute, "show items since")
	fs.Var(alias(fs.Lookup("since"), "s"))
	fs.DurationVar(&until, "until", time.Duration(0), "show items until")
	fs.Var(alias(fs.Lookup("until"), "u"))

	args := []string{
		"--since=-12m", "-u", "1m",
	}

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

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

}

func alias(flg *flag.Flag, name string) (flag.Value, string, string) {
	return flg.Value, name, flg.Usage
}

Output:

since: -12m0s
until: 1m0s

var (
	CommandLine *FlagSet
)

CommandLine is the default set of command-line flags parsed from os.Args.

func NewFlagSet 

func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet

NewFlagSet returns a new flag set with the given name and error handling policy.

func (*FlagSet) Arg 

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

Arg returns the i'th remaining argument after calling FlagSet.Parse. Returns an empty string if the argument does not exist, or FlagSet.Parse was not called.

func (*FlagSet) Args 

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

Args returns a slice of non-flag arguments remaining after calling FlagSet.Parse.

func (*FlagSet) Bool 

func (f *FlagSet) Bool(name string, value bool, usage string) *bool

func (*FlagSet) BoolFunc 

func (f *FlagSet) BoolFunc(name, usage string, fn func(string) error)

func (*FlagSet) BoolVar 

func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string)

func (*FlagSet) Duration 

func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration

func (*FlagSet) DurationVar 

func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string)

func (*FlagSet) ErrorHandling 

func (f *FlagSet) ErrorHandling() ErrorHandling

ErrorHandling returns the error handling policy for this flag set.

func (*FlagSet) Float64 

func (f *FlagSet) Float64(name string, value float64, usage string) *float64

func (*FlagSet) Float64Var 

func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string)

func (*FlagSet) Func 

func (f *FlagSet) Func(name, usage string, fn func(string) error)

func (*FlagSet) Init 

func (f *FlagSet) Init(name string, errorHandling ErrorHandling)

Init sets the name and error handling policy for this flag set.

func (*FlagSet) Int 

func (f *FlagSet) Int(name string, value int, usage string) *int

func (*FlagSet) Int64 

func (f *FlagSet) Int64(name string, value int64, usage string) *int64

func (*FlagSet) Int64Var 

func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string)

func (*FlagSet) IntVar 

func (f *FlagSet) IntVar(p *int, name string, value int, usage string)

func (*FlagSet) Lookup 

func (f *FlagSet) Lookup(name string) *Flag

Lookup returns a Flag with the given name, or nil if no such flag exists.

func (*FlagSet) NArg 

func (f *FlagSet) NArg() int

NArg returns the number of non-flag arguments remaining after calling FlagSet.Parse.

func (*FlagSet) NFlag 

func (f *FlagSet) NFlag() int

NFlag returns the number of flags in this flag set that have been set.

func (*FlagSet) Name 

func (f *FlagSet) Name() string

Name returns the name of this flag set as given to NewFlagSet or FlagSet.Init.

func (*FlagSet) Output 

func (f *FlagSet) Output() io.Writer

Output returns the io.Writer to which usage information is written, according to the ErrorHandling policy. The writer returned is the same given to NewFlagSet or FlagSet.SetOutput.

func (*FlagSet) Parse 

func (f *FlagSet) 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 ErrHelp if -help or -h were set but not defined.

func (*FlagSet) Parsed 

func (f *FlagSet) Parsed() bool

Parsed returns whether or not FlagSet.Parse has been invoked on this flag set.

func (*FlagSet) PrintDefaults 

func (f *FlagSet) PrintDefaults()

PrintDefaults prints usage information and default values for all flags of this flag set to the output location configured with NewFlagSet or FlagSet.SetOutput.

func (*FlagSet) Set 

func (f *FlagSet) Set(name, value string) error

Set updates the value of a flag with the given string. Returns an error if the flag doesn't exist or the value is invalid.

func (*FlagSet) SetOutput 

func (f *FlagSet) SetOutput(output io.Writer)

SetOutput sets the io.Writer to use when writing usage information, according to the ErrorHandling policy.

func (*FlagSet) String 

func (f *FlagSet) String(name string, value string, usage string) *string

func (*FlagSet) StringVar 

func (f *FlagSet) StringVar(p *string, name string, value string, usage string)

func (*FlagSet) TextVar 

func (f *FlagSet) TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextMarshaler, usage string)

func (*FlagSet) Uint 

func (f *FlagSet) Uint(name string, value uint, usage string) *uint

func (*FlagSet) Uint64 

func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64

func (*FlagSet) Uint64Var 

func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string)

func (*FlagSet) UintVar 

func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string)

func (*FlagSet) Var 

func (f *FlagSet) Var(value Value, name string, usage string)

Var registers a flag with an arbitrary Value.

func (*FlagSet) Visit 

func (f *FlagSet) Visit(fn func(*Flag))

VisitAll traverses all set flags in lexical order and executes fn for each one.

func (*FlagSet) VisitAll 

func (f *FlagSet) VisitAll(fn func(*Flag))

VisitAll traverses all flags in lexical order and executes fn for each one.

type Getter 

type Getter interface {
	Value

	// Get yields the (typed) flag value.
	Get() any
}

Getter extends Value but additionally supports retrieval of the typed flag value. All flag types implement this interface, with the exception of FlagSet.BoolFunc and FlagSet.Func.

type Value 

type Value interface {
	// String returns the current value of the flag, represented as a string.
	String() string

	// Set updates the value of this flag.
	Set(string) error
}

Value describes the actual value of a Flag.

Example

You can define custom types implementing flag.Value to handle different types of flags, like timestamps, IP addresses, string maps or slices. 

package main

import (
	"fmt"
	"time"

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

// TimeVar is a [flag.Value] for flags that accept timestamps in [time.RFC3339] format. TimeVar also implements
// [Flag.Getter].
type TimeVar time.Time

// String returns the [time.RFC3339] representation of the timestamp flag.
func (t *TimeVar) String() string {
	return time.Time(*t).Format(time.RFC3339)
}

// Set fulfills the [flag.Value] interface. The given value must be a correctly formatted [time.RFC3339] timestamp.
func (t *TimeVar) Set(value string) error {
	tm, err := time.Parse(time.RFC3339, value)
	if err == nil {
		*t = TimeVar(tm)
	}

	return err
}

// Get fulfills the [flag.Getter] interface, allowing typed access to the flag value. In this case, returns a
// [time.Time].
func (t *TimeVar) Get() any {
	return time.Time(*t)
}

// You can define custom types implementing [flag.Value] to handle different types of flags, like timestamps, IP
// addresses, string maps or slices.
func main() {
	var since 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

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.