or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdflag-access.mdflag-definition.mdflag-types.mdflagset-methods.mdgo-integration.mdindex.mdusage-help.md
tile.json

flag-definition.mddocs/

Flag Definition and Parsing

This document covers flag definition patterns, parsing operations, and basic flag management.

Import

import "github.com/spf13/pflag"

Flag Definition Patterns

pflag provides four function variants for each supported type, allowing flexibility in how flags are defined and where their values are stored.

Pattern 1: Type() - Returns Pointer

Defines a flag and returns a pointer to the value. The value is managed internally.

var name *string = pflag.String("name", "default", "help message")
var port *int = pflag.Int("port", 8080, "port number")
var verbose *bool = pflag.Bool("verbose", false, "verbose output")

Pattern 2: TypeP() - Returns Pointer with Shorthand

Like Type() but accepts a shorthand letter for single-dash usage.

var name *string = pflag.StringP("name", "n", "default", "help message")
var port *int = pflag.IntP("port", "p", 8080, "port number")
var verbose *bool = pflag.BoolP("verbose", "v", false, "verbose output")

Pattern 3: TypeVar() - Binds to Variable

Binds the flag value to an existing variable. Changes the variable directly.

var name string
var port int
var verbose bool

pflag.StringVar(&name, "name", "default", "help message")
pflag.IntVar(&port, "port", 8080, "port number")
pflag.BoolVar(&verbose, "verbose", false, "verbose output")

Pattern 4: TypeVarP() - Binds to Variable with Shorthand

Like TypeVar() but accepts a shorthand letter.

var name string
var port int
var verbose bool

pflag.StringVarP(&name, "name", "n", "default", "help message")
pflag.IntVarP(&port, "port", "p", 8080, "port number")
pflag.BoolVarP(&verbose, "verbose", "v", false, "verbose output")

Parsing Operations

Parse

func Parse()

Parse command-line flags from os.Args[1:]. Must be called after all flags are defined and before flags are accessed by the program.

Usage:

pflag.Parse()

// Access parsed values
fmt.Println("Name:", *name)
fmt.Println("Port:", *port)

ParseAll

func ParseAll(fn func(flag *Flag, value string) error)

Parse command-line flags from os.Args[1:] and call fn for each flag. The arguments for fn are flag and value. Must be called after all flags are defined and before flags are accessed.

Usage:

pflag.ParseAll(func(flag *pflag.Flag, value string) error {
	fmt.Printf("Flag %s set to %s\n", flag.Name, value)
	return nil
})

Parsed

func Parsed() bool

Return true if command-line flags have been parsed.

Usage:

if !pflag.Parsed() {
	pflag.Parse()
}

FlagSet Parsing

When using custom FlagSets (for subcommands or independent flag scopes), use FlagSet-specific parsing methods.

FlagSet.Parse

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

Parse flag definitions from the argument list. Returns error if parsing fails (when error handling is ContinueOnError).

Usage:

fs := pflag.NewFlagSet("mycommand", pflag.ContinueOnError)
fs.String("config", "default.conf", "config file")

if err := fs.Parse(os.Args[1:]); err != nil {
	fmt.Fprintf(os.Stderr, "Error: %v\n", err)
	os.Exit(1)
}

FlagSet.ParseAll

func (f *FlagSet) ParseAll(arguments []string, fn func(*Flag, value string) error) error

Parse flags from arguments and call fn for each flag with the flag and its value.

Usage:

fs := pflag.NewFlagSet("mycommand", pflag.ContinueOnError)
fs.String("config", "default.conf", "config file")

err := fs.ParseAll(os.Args[1:], func(flag *pflag.Flag, value string) error {
	fmt.Printf("Parsed: %s = %s\n", flag.Name, value)
	return nil
})

FlagSet.Parsed

func (f *FlagSet) Parsed() bool

Return true if the flag set has been parsed.

Custom Values

For custom types, implement the Value interface and use Var functions.

Value Interface

type Value interface {
	String() string
	Set(string) error
	Type() string
}

Var

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

Define a flag with custom Value implementation.

Usage:

type ipSlice []net.IP

func (i *ipSlice) String() string {
	return fmt.Sprintf("%v", *i)
}

func (i *ipSlice) Set(value string) error {
	ip := net.ParseIP(value)
	if ip == nil {
		return fmt.Errorf("invalid IP address: %s", value)
	}
	*i = append(*i, ip)
	return nil
}

func (i *ipSlice) Type() string {
	return "ipSlice"
}

var ips ipSlice
pflag.Var(&ips, "ip", "IP addresses to connect to")

VarP

func VarP(value Value, name, shorthand, usage string)

Like Var but with shorthand support.

VarPF

func VarPF(value Value, name, shorthand, usage string) *Flag

Like VarP but returns the created Flag for direct manipulation.

Setting Flags Programmatically

Set

func Set(name, value string) error

Set the value of the named command-line flag. Can be used before or after parsing to set flag values programmatically.

Usage:

// Set flag before parsing
pflag.Set("verbose", "true")
pflag.Set("port", "9090")

pflag.Parse()

// Or set after parsing
pflag.Set("log-level", "debug")

FlagSet.Set

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

Set the value of a flag in the FlagSet.

Error Handling

Configure how parsing errors are handled when creating a FlagSet.

ErrorHandling Constants

type ErrorHandling int

const (
	ContinueOnError ErrorHandling = iota  // Return error from Parse()
	ExitOnError                            // Call os.Exit(2) on error
	PanicOnError                           // panic() on error
)

Usage:

// Create FlagSet that returns errors
fs := pflag.NewFlagSet("myapp", pflag.ContinueOnError)
if err := fs.Parse(os.Args[1:]); err != nil {
	// Handle error
}

// Create FlagSet that exits on error (like CommandLine)
fs := pflag.NewFlagSet("myapp", pflag.ExitOnError)
fs.Parse(os.Args[1:])  // Will exit if error occurs

// Create FlagSet that panics on error
fs := pflag.NewFlagSet("myapp", pflag.PanicOnError)
fs.Parse(os.Args[1:])  // Will panic if error occurs

Flag Syntax

Long Flags

--flag           # Boolean flag
--flag=value     # Flag with value
--flag value     # Flag with value (space-separated)

Short Flags

-f               # Boolean shorthand
-f=value         # Shorthand with value
-f value         # Shorthand with value (space-separated)
-fvalue          # Shorthand with value (no separator)

Combined Shorthands

Boolean flags can be combined:

-abc             # Equivalent to -a -b -c
-abcs value      # Equivalent to -a -b -c -s value

Terminator

The -- terminator stops flag parsing. Everything after -- is treated as an argument.

myapp --verbose -- --not-a-flag
# --verbose is parsed as flag
# --not-a-flag is treated as argument

Flag Interspersing

Unlike Go's standard flag package, pflag allows flags to be interspersed with arguments anywhere before the -- terminator.

myapp file1.txt --verbose file2.txt --output=out.txt file3.txt

To disable interspersing:

func SetInterspersed(interspersed bool)

Usage:

pflag.SetInterspersed(false)
pflag.Parse()

FlagSet.SetInterspersed

func (f *FlagSet) SetInterspersed(interspersed bool)

Control interspersing for a specific FlagSet.

NoOptDefVal

The NoOptDefVal field allows a flag to have a special default value when the flag is present on the command line without an argument.

Usage:

port := pflag.Int("port", 8080, "port number")
pflag.Lookup("port").NoOptDefVal = "9090"

pflag.Parse()

// Command line: myapp --port=3000  => *port = 3000
// Command line: myapp --port       => *port = 9090
// Command line: myapp              => *port = 8080

This is particularly useful for optional flag arguments.

Adding Flags from Another FlagSet

AddFlagSet

func (f *FlagSet) AddFlagSet(newSet *FlagSet)

Add all flags from another FlagSet to this FlagSet.

Usage:

commonFlags := pflag.NewFlagSet("common", pflag.ContinueOnError)
commonFlags.Bool("verbose", false, "verbose output")
commonFlags.String("config", "default.conf", "config file")

appFlags := pflag.NewFlagSet("app", pflag.ExitOnError)
appFlags.Int("port", 8080, "port number")
appFlags.AddFlagSet(commonFlags)  // Add common flags

appFlags.Parse(os.Args[1:])

Checking if Flag Was Changed

Changed

func (f *FlagSet) Changed(name string) bool

Return true if the flag was set on the command line (vs using default value).

Usage:

pflag.String("config", "default.conf", "config file")
pflag.Parse()

if pflag.Changed("config") {
	fmt.Println("Config flag was explicitly set")
} else {
	fmt.Println("Using default config")
}

The Flag.Changed field also indicates whether the flag was set:

flag := pflag.Lookup("config")
if flag.Changed {
	fmt.Println("Config was set to:", flag.Value.String())
}