tinyflags

package module
v0.0.56 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2025 License: Apache-2.0 Imports: 11 Imported by: 1

README

tinyflags

Go Reference

A minimal, fast, and extensible CLI flag-parsing library for Go. Zero dependencies. Full generics support. Rich usage output.

Features

  • Short & long flags (-d, --debug)
  • Boolean strict mode (--flag=true/false, --no-flag)
  • Environment variable overrides (EnvPrefix, per-flag opt-out)
  • Required, deprecated, and grouped flags
  • Slice flags ([]T) with custom delimiters
  • Allowed choices, validation and finalizers
  • One Of groups
  • All or None groups
  • Custom placeholders & help sections
  • Dynamic flags (--group.id.field=value)
  • Typed values (*os.File, *net.TCPAddr, url.URL, time.Duration, etc.)

Why yet another flag library?

  • Validate & Finalize on the fly I got tired of the two-step tango--parse first, then wade through a swamp of if-statements just to check and tweak values. Tinyflags lets you validate and finalize your flags as they're parsed, so you can slap on your business logic (and data massaging) in one go.

  • Group therapy for flags Ever tried juggling "onf of" or "all-or-nothing" flags with plain flag? It's like herding cats. Tinyflags brings built-in onf-of and all-or-none groups so your flags behave like well-trained puppies.

  • Self-service help & version Want to bail out with --help or --version at just the right moment, without writing extra if-blocks? Tinyflags handles the exit routine for you, so you can spend less time plumbing and more time coding.

  • Dynamic flags--finally! I looked high and low for a Go library that lets you declare --group.id.field=value flags, where id is dynamic. No luck. So I built one, folded it into tinyflags, and voila: one library to rule both "regular" and "shape-shifting" dynamic flags.

In short, tinyflags slices away boilerplate, stitches in the goodies I actually needed, and keeps my codebase lean--no extra flag-parsing baggage required. 🚀

Install

go get github.com/containeroo/tinyflags

Quickstart

package main

import (
    "fmt"
    "os"
    "github.com/containeroo/tinyflags"
)

func main() {
    fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)
    fs.EnvPrefix("MYAPP")
    fs.Version("v1.2.3")

    host := fs.String("host", "localhost", "Server hostname").Required().Value()
    port := fs.Int("port", 8080, "Port to bind").Short("p").Value()
    debug := fs.Bool("debug", false, "Enable debug logging").Short("d").Value()
    tags  := fs.StringSlice("tag", nil, "Optional tags").Value()

    if err := fs.Parse(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

    fmt.Println("Host:", *host)
    fmt.Println("Port:", *port)
    fmt.Println("Debug:", *debug)
    fmt.Println("Tags:", *tags)
}

Supported Types

Type Methods
bool Bool, BoolVar
int Int, IntVar
string String, StringVar
[]string StringSlice, StringSliceVar
counter Counter, CounterVar (auto-increment)
time.Duration Duration, DurationVar
net.IP IP, IPVar
[]net.IP IPSlice, IPSliceVar
*net.TCPAddr TCPAddr, TCPAddrVar
url.URL URL, URLVar
*os.File File, FileVar

Slice flags accept repeated use or custom-delimited strings.

Handling toggles with multiple flags

You can model toggles with paired flags (e.g., --debug and --no-debug) and pick the first one the user set:

debug := fs.Bool("debug", false, "Enable debug").Short("d").OneOfGroup("debug")
noDebug := fs.Bool("no-debug", false, "Disable debug").Short("n").OneOfGroup("debug")

// Use the order you prefer; first changed wins
enabled, set := tinyflags.FirstChanged(false, debug, noDebug)
fmt.Printf("debug: %t (set: %v)\n", enabled, set)
Helpers and exported utilities
  • FirstChanged[T](defaultValue, flags...) — returns the value of the first changed flag (by order) plus whether any flag was set.
  • IsHelpRequested(err) / IsVersionRequested(err) — detect help/version parse exits.
  • RequestHelp() / RequestVersion() — trigger help/version errors manually.
  • Flag[T] — minimal interface implemented by flag handles (Changed() bool, Value() *T).

FlagSet API

Common Flag-Builder Methods
Method Applies to Description
Short(s string) static only One-letter alias (-p). Must be exactly one rune (panics otherwise).
Required() all flags Mark the flag as required; parser errors if unset.
HideRequired() all flags Hide the "(Required)" suffix from help.
Hidden() all flags Omit this flag from generated help output.
Deprecated(reason string) all flags Mark flag deprecated; includes DEPRECATED note in help.
OneOfGroup(group string) all flags Assign to a named mutual-exclusion group. Parsing errors if more than one in group set.
AllOrNone(group string) all flags Assign to a named require-together group. All or none in group must be set.
Env(key string) all flags Override the environment-variable name (panics if DisableEnv already called).
HideEnv() all flags Hide the environment-variable name from help.
DisableEnv() all flags Disable environment lookup for this flag (panics if Env(...) already called).
Placeholder(text string) all flags Customize the <VALUE> placeholder in help.
Allowed(vals ...string) all flags Restrict help to show only these allowed values.
HideAllowed() all flags Hide the allowed values from help.
Requires(names ...string) all flags Mark flag as required by the given flag.
HideRequires() all flags Hide the “(Requires)” suffix from help.
Value() *T static only Return the pointer to the parsed value (after Parse).
Static-Flag Extras
Method Description Example
Choices(v1, v2, ...) Only allow the provided literal values; automatically adds them to help output. fs.String("env","dev","...").Choices("dev","staging","prod")
Validate(fn func(v T) error) Run custom check on parsed value; if fn returns non-nil, Parse returns an error. go<br>fs.Int("count",0,"...").Validate(func(n int) error {<br> if n<0 {return fmt.Errorf("must ≥0")}<br> return nil<br>})<br>
Finalize(fn func(v T) T) Transform the parsed value before storing; e.g. trimming, normalization, applying defaults. go<br>fs.String("name","","...").Finalize(func(s string) string {<br> return strings.TrimSpace(s)<br>})<br>
FinalizeWithID(fn func(id string, v T) T) (dynamic only) Finalize with access to the instance ID. http.String("addr","","").FinalizeWithID(func(id, v string) string { return id+":"+v })
Delimiter(sep string) (slice flags only) Use a custom separator instead of the default comma when parsing lists. fs.StringSlice("tags",nil,"...").Delimiter(";")
StrictDelimiter() (slice flags only) Reject mixed separators in one flag occurrence.
AllowEmpty() (slice flags only) Allow empty items (e.g. "a,,b").
HideDefault() Hide the default value from help output.
Section(name string) Group flags under a section header in help output.
Dynamic-Flag Extras
Method Description Example
Has(id string) bool Return whether the given instance-ID was provided on the command line or via env. if port.Has("a") { fmt.Println("port a is set") }
Get(id string) (value T, ok bool) Retrieve the parsed value for that ID; ok==false if unset (returns default). p, ok := port.Get("a"); if ok { fmt.Println("a →", p) }
MustGet(id string) T Like Get, but panics if the instance wasn't provided. timeout.MustGet("b")
Values() map[string]T Get all parsed values keyed by instance ID. for id, v := range timeout.Values() { fmt.Println(id, v) }
ValuesAny() map[string]interface{} Same as Values(), but values are interface{}.
AllowOverride() Allow re-assignment of a dynamic flag per-ID. Only for Scalar flags.

All common methods (Required, Hidden, etc.) and static extras (Choices, Validate, Finalize, Delimiter) also apply to dynamic flags.

FlagSet Core & Help Configuration
Method Description
NewFlagSet(name string, mode ErrorHandling) Create a new flag set (e.g. ExitOnError, ContinueOnError).
EnvPrefix(prefix string) Prefix all environment-variable lookups (e.g. MYAPP_).
SetEnvKeyFunc Set a function to derive env keys from prefix+flag name.
EnvKeyForFlag Derive the env key for a flag.
NewReplacerEnvKeyFunc Build an EnvKeyFunc that applies the given replacer.
Version(version string) Enable the --version flag, printing this string.
Help() Access grouped helpers for title/authors/description/note/help text.
Layout() Access grouped helpers for usage/indent/width/note layout.
BeforeParse(fn func([]string) ([]string, error)) Mutate arguments before parsing (e.g., expand @files).
OnUnknownFlag(fn func(name string) error) Handle or ignore unknown flags instead of failing.
VersionText(text string) Override the --version text. Default: "Show version".
HelpText(text string) Override the --help text. Default: "Show help".
DisableHelp() / DisableVersion() Remove --help or --version.
Usage(fn func()) Install a custom usage function in place of the default.
Title(text string) Override the "Usage:" title heading.
Authors(names ...string) Add an "Authors:" section to help.
Description(text string) Add a free-form description block under the title.
Note(text string) Add a footer note under the flags listing.
SetOutput(w io.Writer) / Output() Redirect or retrieve where help/version is written.
PrintUsage(w, mode) Print the Usage: line.
PrintTitle(w) Print title and description.
PrintAuthors(w) Print authors section.
PrintDescription(w,indent,width) Print the description block.
PrintNotes(w,indent,width) Print footer notes.
PrintStaticDefaults(w,indent,startCol,width) Print static flags help.
PrintDynamicDefaults(w,indent,startCol,width) Print dynamic flags help.
RequirePositional(n int) Enforce at least n positional arguments.
Args() []string / Arg(i int) string Access leftover positional args.
AddOneOfGroup(name string, flags []string) Manually define a mutual-exclusion group.
AddAllOrNoneGroup(name string, flags []string) Manually define a require-together group.
How Validate and Finalize Work

  1. Validate

    • After parsing a flag's raw input into T, Tinyflags calls your validator:
    fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)

count := fs.Int("count", 0, "Number of items").
    Validate(func(n int) error {
        if n < 0 {
            return fmt.Errorf("must be non-negative")
        }
        return nil
    }).
    Value()

fs.Parse(os.Args[1:])
fmt.Println("Count:", *count)

    • If the user does --count=-5, they see:

      invalid value for --count: must be non-negative

    • On error, parsing aborts and your message is shown to the user.

  2. Finalize

    • Only after validation succeeds, Tinyflags passes the parsed value through your finalizer:
    fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)

name := fs.String("name", "", "User name").
  Finalize(func(s string) string {
          return strings.TrimSpace(strings.ToTitle(s))
          }).
  Value()

url := fs.String("url", "", "URL to use").
  // Ensure the URL ends with a slash
  Finalize(func(u *url.URL) *url.URL {
     // Clone to avoid mutating the original (optional, if needed)
     u2 := *u
     if len(u2.Path) > 0 && u2.Path[len(u2.Path)-1] != '/' {
         u2.Path += "/"
     }
     return &u2
  }).
  Value()


 fs.Parse([]string{"--name=   alice smith  ", "--url", "https://containeroo.ch"})
 fmt.Println("Hello,", *name)
 fmt.Println("Visist:", *url)

    Output:

    Hello, Alice Smith
Visti: https://containeroo.ch/
    • Useful for trimming whitespace, applying normalization, setting derived defaults, etc.

Environment Variables

Flags can be set from environment variables in addition to CLI arguments. By default, environment keys are derived from:

  • the global prefix set via fs.EnvPrefix("MYAPP")
  • -, _, ., _, / are replaced with _ in the flag name
  • the whole key upper-cased

For example:

MYAPP_HOST=example.com MYAPP_PORT=9090 ./app --debug

A flag --db.user will look up MYAPP_DB_USER.

You can disable env binding per-flag:

fs.Bool("internal", false, "internal use only").DisableEnv()
Custom key mapping

You can override how keys are derived with SetEnvKeyFunc:

fs.EnvPrefix("MYAPP")
fs.SetEnvKeyFunc(engine.NewReplacerEnvKeyFunc(
    strings.NewReplacer("-", "_", ".", "_", "/", "_"),
    true, // upper-case
))

This would map:

  • --log.level → MYAPP_LOG_LEVEL
  • --db-user → MYAPP_DB_USER
  • --api/v1 → MYAPP_API_V1

Dynamic Flags

package main

import (
    "fmt"
    "os"
    "github.com/containeroo/tinyflags"
)

func main() {
    fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)
    http := fs.DynamicGroup("http")

    port    := http.Int("port", "Backend port")
    timeout := http.Duration("timeout", "Request timeout")

    if err := fs.Parse(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

    for _, id := range http.Instances() {
        p, _ := port.Get(id)
        t, _ := timeout.Get(id)
        fmt.Printf("%s: port=%d, timeout=%s\n", id, p, t)
    }
}

./app --http.a.port=8080 --http.a.timeout=30s \
      --http.b.port=9090 --http.b.timeout=1m

a: port=8080, timeout=30s
b: port=9090, timeout=1m

Grouped Flags: Mutual-Exclusion & Require-Together

When certain flags must be used together, or must be exclusive, tinyflags makes that easy.

🔁 Require-Together Group

You can define a group where either all or none of the flags must be set:

email := fs.String("email", "", "User email").
    AllOrNone("authpair").
    Value()

password := fs.String("password", "", "User password").
    AllOrNone("authpair").
    Value()
🔀 Mutual-Exclusion Group

You can define a group where only one of the flags (or groups!) may be set:

bearer := fs.String("bearer-token", "", "Bearer token").
    OneOfGroup("authmethod").
    Value()

fs.GetOneOfGroup("authmethod").
    Title("Authentication Method").
    AddGroup(fs.GetAllOrNoneGroup("authpair")) // <-- email+password

This enforces:

  • Either --email and --password together, or
  • --bearer-token, but not both
✅ Valid combinations
# Valid:
--email=user --password=secret
--bearer-token=abc123

# Invalid:
--email=user                ❌ password missing
--email=user --bearer-token=abc123 ❌ both auth methods
Help Output Example
Usage: app [flags]

Flags:
  --email EMAIL         User email (Group: Authentication Method) (AllOrNone: authpair)
  --password PASSWORD   User password (Group: Authentication Method) (AllOrNone: authpair)
  --bearer-token TOKEN  Bearer token (Group: Authentication Method)

Authentication Method
(Exactly one required)
  --bearer-token TOKEN
  [--email, --password] (Required together)

authpair
(Required)
  --email EMAIL
  --password PASSWORD

Help Output

Usage: app [flags]

Flags:
  --host HOST         Server hostname (Default: localhost) (Env: MYAPP_HOST) (Required)
  -p, --port PORT     Port to bind (Default: 8080) (Env: MYAPP_PORT)
  -d, --debug         Enable debug logging (Env: MYAPP_DEBUG)
      --tag TAG...    Optional tags
  -v, --version       Show version

License

Apache 2.0 -- see LICENSE

Documentation

Overview

Package tinyflags provides a high-level API for defining and parsing CLI flags with support for dynamic groups, custom types, and rich usage output.

Index

Constants

View Source 
const (
	ContinueOnError = engine.ContinueOnError // Continue and return error
	ExitOnError     = engine.ExitOnError     // Exit with error message
	PanicOnError    = engine.PanicOnError    // Panic on error
)
View Source 
const (
	PrintNone  = engine.PrintNone  // Omits usage line entirely
	PrintFlags = engine.PrintFlags // Prints: [flags]
	PrintShort = engine.PrintShort // Prints: -v
	PrintLong  = engine.PrintLong  // Prints: --verbose
	PrintBoth  = engine.PrintBoth  // Prints: -v|--verbose
)

Variables

View Source 
var (
	IsHelpRequested    = engine.IsHelpRequested
	IsVersionRequested = engine.IsVersionRequested
	RequestHelp        = engine.RequestHelp
	RequestVersion     = engine.RequestVersion
)

Functions

func FirstChanged added in v0.0.56 

func FirstChanged[T any](defaultValue T, flags ...Flag[T]) (T, bool)

FirstChanged returns the value of the first changed flag in the given order. If no flag was changed, it returns defaultValue and false.

func GetDynamic added in v0.0.10 

func GetDynamic[T any](group *dynamic.Group, id, flag string) (T, error)

GetDynamic retrieves the value for a dynamic flag by group, id, and field name.

func GetOrDefaultDynamic added in v0.0.14 

func GetOrDefaultDynamic[T any](group *dynamic.Group, id, flag string) T

GetOrDefaultDynamic returns the value for a dynamic flag or its default.

func MustGetDynamic added in v0.0.10 

func MustGetDynamic[T any](group *dynamic.Group, id, flag string) T

MustGetDynamic retrieves the value for a dynamic flag or panics.

Types

type DynamicGroup added in v0.0.23 

type DynamicGroup = dynamic.Group // Dynamic group of instance-scoped flags

Exported types for advanced access.

type ErrorHandling 

type ErrorHandling = engine.ErrorHandling

ErrorHandling defines how parsing errors are handled.

type Flag 

type Flag[T any] = core.Flag[T] // Minimal flag handle interface

Exported types for advanced access.

type FlagPrintMode 

type FlagPrintMode = engine.FlagPrintMode

FlagPrintMode controls how the usage line is rendered.

type FlagSet 

type FlagSet struct {
	Usage func() // Optional custom usage function
	// contains filtered or unexported fields
}

FlagSet is the user-facing flag parser and usage configurator.

func NewFlagSet 

func NewFlagSet(name string, handling ErrorHandling) *FlagSet

NewFlagSet creates a new flag set with the given name and error handling mode.

func (*FlagSet) AddAllOrNoneGroup added in v0.0.36 

func (f *FlagSet) AddAllOrNoneGroup(name string, g *core.AllOrNoneGroup)

AddAllOrNoneGroup adds a AllOrNoneGroup group.

func (*FlagSet) AddOneOfGroup added in v0.0.36 

func (f *FlagSet) AddOneOfGroup(name string, g *core.OneOfGroupGroup)

AddOneOfGroup adds a AddOneOfGroup group.

func (*FlagSet) AllOrNoneGroup added in v0.0.36 

func (f *FlagSet) AllOrNoneGroup() []*core.AllOrNoneGroup

AllOrNoneGroup returns all registered AllOrNoneGroup group.

func (*FlagSet) Arg 

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

Arg returns the i-th positional argument and whether it exists.

func (*FlagSet) Args 

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

Args returns all leftover positional arguments.

func (*FlagSet) AttachGroupToAllOrNone added in v0.0.52 

func (f *FlagSet) AttachGroupToAllOrNone(parent, child string)

AttachGroupToAllOrNone nests one AllOrNone group into another.

func (*FlagSet) AttachGroupToOneOf added in v0.0.52 

func (f *FlagSet) AttachGroupToOneOf(group, name string)

AttachGroupToOneOf adds an AllOrNone group to a OneOf group.

func (*FlagSet) AttachToAllOrNoneGroup added in v0.0.36 

func (f *FlagSet) AttachToAllOrNoneGroup(flag *core.BaseFlag, group string)

AttachToAllOrNoneGroup attaches a flag to a AllOrNoneGroup group.

func (*FlagSet) AttachToOneOfGroup added in v0.0.36 

func (f *FlagSet) AttachToOneOfGroup(flag *core.BaseFlag, group string)

AttachToOneOfGroup attaches a static flag to a OneOfGroup group.

func (*FlagSet) Authors added in v0.0.8 

func (f *FlagSet) Authors(s string)

Authors sets the list of authors printed in help output.

func (*FlagSet) BeforeParse added in v0.0.52 

func (f *FlagSet) BeforeParse(fn func([]string) ([]string, error))

BeforeParse installs a hook to mutate arguments before parsing.

func (*FlagSet) Bool 

func (f *FlagSet) Bool(name string, def bool, usage string) *scalar.BoolFlag

Bool defines a bool flag. If Strict() is enabled, it must be set explicitly (--flag=true/false).

func (*FlagSet) BoolVar 

func (f *FlagSet) BoolVar(ptr *bool, name string, def bool, usage string) *scalar.BoolFlag

BoolVar defines a bool flag and binds it to the given pointer. If Strict() is enabled, it must be set explicitly (--flag=true/false).

func (*FlagSet) Bytes added in v0.0.8 

func (f *FlagSet) Bytes(name string, def uint64, usage string) *scalar.ScalarFlag[uint64]

Bytes defines a uint64 flag that parses sizes (e.g., "10MB") and returns its handle.

func (*FlagSet) BytesSlice added in v0.0.8 

func (f *FlagSet) BytesSlice(name string, def []uint64, usage string) *slice.SliceFlag[uint64]

BytesSlice defines a []uint64 “bytes” flag and returns its handle.

func (*FlagSet) BytesSliceVar added in v0.0.8 

func (f *FlagSet) BytesSliceVar(ptr *[]uint64, name string, def []uint64, usage string) *slice.SliceFlag[uint64]

BytesSliceVar defines a []uint64 flag that parses human-readable sizes and binds it to the given pointer.

func (*FlagSet) BytesVar added in v0.0.8 

func (f *FlagSet) BytesVar(ptr *uint64, name string, def uint64, usage string) *scalar.ScalarFlag[uint64]

BytesVar defines a uint64 flag with byte parsing and binds it to the given pointer.

func (*FlagSet) Counter added in v0.0.8 

func (f *FlagSet) Counter(name string, def int, usage string) *scalar.CounterFlag

Counter defines a counter flag that increments with each occurrence.

func (*FlagSet) CounterVar added in v0.0.8 

func (f *FlagSet) CounterVar(ptr *int, name string, def int, usage string) *scalar.CounterFlag

CounterVar defines a counter flag and binds it to the given pointer.

func (*FlagSet) DefaultDelimiter added in v0.0.8 

func (f *FlagSet) DefaultDelimiter() string

DefaultDelimiter returns the delimiter used for slice flags.

func (*FlagSet) DescIndent added in v0.0.23 

func (f *FlagSet) DescIndent() int

DescIndent returns the current indent used for the description block.

func (*FlagSet) DescWidth added in v0.0.23 

func (f *FlagSet) DescWidth() int

DescWidth returns the wrapping width for the description block.

func (*FlagSet) Description 

func (f *FlagSet) Description(s string)

Description sets the top description section of the help output.

func (*FlagSet) DisableHelp 

func (f *FlagSet) DisableHelp()

DisableHelp disables the automatic --help flag.

func (*FlagSet) DisableVersion 

func (f *FlagSet) DisableVersion()

DisableVersion disables the automatic --version flag.

func (*FlagSet) Duration 

func (f *FlagSet) Duration(name string, def time.Duration, usage string) *scalar.ScalarFlag[time.Duration]

Duration defines a time.Duration flag and returns its handle.

func (*FlagSet) DurationSlice 

func (f *FlagSet) DurationSlice(name string, def []time.Duration, usage string) *slice.SliceFlag[time.Duration]

DurationSlice defines a []time.Duration flag and returns its handle.

func (*FlagSet) DurationSliceVar 

func (f *FlagSet) DurationSliceVar(ptr *[]time.Duration, name string, def []time.Duration, usage string) *slice.SliceFlag[time.Duration]

DurationSliceVar defines a []time.Duration flag and binds it to the given pointer.

func (*FlagSet) DurationVar 

func (f *FlagSet) DurationVar(ptr *time.Duration, name string, def time.Duration, usage string) *scalar.ScalarFlag[time.Duration]

DurationVar defines a time.Duration flag and binds it to the given pointer.

func (*FlagSet) DynamicAutoUsageColumn added in v0.0.23 

func (f *FlagSet) DynamicAutoUsageColumn(padding int) int

DynamicAutoUsageColumn computes a good usage column for dynamic flags.

func (*FlagSet) DynamicGroup added in v0.0.8 

func (f *FlagSet) DynamicGroup(name string) *dynamic.Group

DynamicGroup registers or retrieves a dynamic group by name.

func (*FlagSet) DynamicGroups added in v0.0.9 

func (f *FlagSet) DynamicGroups() []*dynamic.Group

DynamicGroups returns all dynamic groups in registration order.

func (*FlagSet) DynamicUsageColumn added in v0.0.25 

func (f *FlagSet) DynamicUsageColumn() int

DynamicUsageColumn returns the description column for dynamic flags.

func (*FlagSet) DynamicUsageIndent added in v0.0.25 

func (f *FlagSet) DynamicUsageIndent() int

DynamicUsageIndent returns the dynamic flag usage indent.

func (*FlagSet) DynamicUsageNote added in v0.0.23 

func (f *FlagSet) DynamicUsageNote() string

DynamicUsageNote returns the dynamic flag section note.

func (*FlagSet) DynamicUsageWidth added in v0.0.25 

func (f *FlagSet) DynamicUsageWidth() int

DynamicUsageWidth returns the wrapping width for dynamic flag descriptions.

func (*FlagSet) EnvKeyForFlag added in v0.0.43 

func (f *FlagSet) EnvKeyForFlag(name string) string

EnvKeyForFlag derives the env key for a flag.

func (*FlagSet) EnvPrefix 

func (f *FlagSet) EnvPrefix(s string)

EnvPrefix sets a prefix for all environment variables.

func (*FlagSet) File 

func (f *FlagSet) File(name string, def *os.File, usage string) *scalar.ScalarFlag[*os.File]

File defines an *os.File flag and returns its handle.

func (*FlagSet) FileSlice 

func (f *FlagSet) FileSlice(name string, def []*os.File, usage string) *slice.SliceFlag[*os.File]

FileSlice defines a []*os.File flag and returns its handle.

func (*FlagSet) FileSliceVar 

func (f *FlagSet) FileSliceVar(ptr *[]*os.File, name string, def []*os.File, usage string) *slice.SliceFlag[*os.File]

FileSliceVar defines a []*os.File flag and binds it to the given pointer.

func (*FlagSet) FileVar 

func (f *FlagSet) FileVar(ptr **os.File, name string, def *os.File, usage string) *scalar.ScalarFlag[*os.File]

FileVar defines an *os.File flag and binds it to the given pointer.

func (*FlagSet) Float32 

func (f *FlagSet) Float32(name string, def float32, usage string) *scalar.ScalarFlag[float32]

Float32 defines a float32 flag and returns its handle.

func (*FlagSet) Float32Slice 

func (f *FlagSet) Float32Slice(name string, def []float32, usage string) *slice.SliceFlag[float32]

Float32Slice defines a []float32 flag and returns its handle.

func (*FlagSet) Float32SliceVar 

func (f *FlagSet) Float32SliceVar(ptr *[]float32, name string, def []float32, usage string) *slice.SliceFlag[float32]

Float32SliceVar defines a []float32 flag and binds it to the given pointer.

func (*FlagSet) Float32Var 

func (f *FlagSet) Float32Var(ptr *float32, name string, def float32, usage string) *scalar.ScalarFlag[float32]

Float32Var defines a float32 flag and binds it to the given pointer.

func (*FlagSet) Float64 

func (f *FlagSet) Float64(name string, def float64, usage string) *scalar.ScalarFlag[float64]

Float64 defines a float64 flag and returns its handle.

func (*FlagSet) Float64Slice 

func (f *FlagSet) Float64Slice(name string, def []float64, usage string) *slice.SliceFlag[float64]

Float64Slice defines a []float64 flag and returns its handle.

func (*FlagSet) Float64SliceVar 

func (f *FlagSet) Float64SliceVar(ptr *[]float64, name string, def []float64, usage string) *slice.SliceFlag[float64]

Float64SliceVar defines a []float64 flag and binds it to the given pointer.

func (*FlagSet) Float64Var 

func (f *FlagSet) Float64Var(ptr *float64, name string, def float64, usage string) *scalar.ScalarFlag[float64]

Float64Var defines a float64 flag and binds it to the given pointer.

func (*FlagSet) GetAllOrNoneGroup added in v0.0.36 

func (f *FlagSet) GetAllOrNoneGroup(name string) *core.AllOrNoneGroup

GetAllOrNoneGroup retrieves or creates a named AllOrNoneGroup group.

func (*FlagSet) GetOneOfGroup added in v0.0.36 

func (f *FlagSet) GetOneOfGroup(name string) *core.OneOfGroupGroup

GetOneOfGroup retrieves or creates a named OneOfGroup group.

func (*FlagSet) Globaldelimiter 

func (f *FlagSet) Globaldelimiter(s string)

Globaldelimiter sets the delimiter used for all slice flags.

func (*FlagSet) Help added in v0.0.52 

func (f *FlagSet) Help() *HelpOptions

Help returns grouped helpers for configuring help/usage output.

func (*FlagSet) HelpText added in v0.0.44 

func (f *FlagSet) HelpText(s string)

HelpText sets the --help text.

func (*FlagSet) HideEnvs added in v0.0.23 

func (f *FlagSet) HideEnvs()

HideEnvs disables all env-var annotations in help output.

func (*FlagSet) IP 

func (f *FlagSet) IP(name string, def net.IP, usage string) *scalar.ScalarFlag[net.IP]

IP defines a net.IP flag and returns its handle.

func (*FlagSet) IPMask 

func (f *FlagSet) IPMask(name string, def net.IPMask, usage string) *scalar.ScalarFlag[net.IPMask]

IPMask defines a net.IPMask flag and returns its handle.

func (*FlagSet) IPMaskSlice 

func (f *FlagSet) IPMaskSlice(name string, def []net.IPMask, usage string) *slice.SliceFlag[net.IPMask]

IPMaskSlice defines a []net.IPMask flag and returns its handle.

func (*FlagSet) IPMaskSliceVar 

func (f *FlagSet) IPMaskSliceVar(ptr *[]net.IPMask, name string, def []net.IPMask, usage string) *slice.SliceFlag[net.IPMask]

IPMaskSliceVar defines a []net.IPMask flag and binds it to the given pointer.

func (*FlagSet) IPSlice 

func (f *FlagSet) IPSlice(name string, def []net.IP, usage string) *slice.SliceFlag[net.IP]

IPSlice defines a []net.IP flag and returns its handle.

func (*FlagSet) IPSliceVar 

func (f *FlagSet) IPSliceVar(ptr *[]net.IP, name string, def []net.IP, usage string) *slice.SliceFlag[net.IP]

IPSliceVar defines a []net.IP flag and binds it to the given pointer.

func (*FlagSet) IPVar 

func (f *FlagSet) IPVar(ptr *net.IP, name string, def net.IP, usage string) *scalar.ScalarFlag[net.IP]

IPVar defines a net.IP flag and binds it to the given pointer.

func (*FlagSet) IPv4MaskVar added in v0.0.8 

func (f *FlagSet) IPv4MaskVar(ptr *net.IPMask, name string, def net.IPMask, usage string) *scalar.ScalarFlag[net.IPMask]

IPv4MaskVar defines a net.IPMask flag and binds it to the given pointer.

func (*FlagSet) IgnoreInvalidEnv 

func (f *FlagSet) IgnoreInvalidEnv(b bool)

IgnoreInvalidEnv disables errors for unrecognized environment values.

func (*FlagSet) Int 

func (f *FlagSet) Int(name string, def int, usage string) *scalar.ScalarFlag[int]

Int defines an int flag and returns its handle.

func (*FlagSet) Int32 added in v0.0.50 

func (f *FlagSet) Int32(name string, def int32, usage string) *scalar.ScalarFlag[int32]

Int32 defines an int flag and returns its handle.

func (*FlagSet) Int32Slice added in v0.0.50 

func (f *FlagSet) Int32Slice(name string, def []int32, usage string) *slice.SliceFlag[int32]

Int32Slice defines a []int32 flag and returns its handle.

func (*FlagSet) Int32SliceVar added in v0.0.50 

func (f *FlagSet) Int32SliceVar(ptr *[]int32, name string, def []int32, usage string) *slice.SliceFlag[int32]

Int32SliceVar defines a []int32 flag and binds it to the given pointer.

func (*FlagSet) Int32Var added in v0.0.50 

func (f *FlagSet) Int32Var(ptr *int32, name string, def int32, usage string) *scalar.ScalarFlag[int32]

Int32Var defines an int flag and binds it to the given pointer.

func (*FlagSet) Int64 added in v0.0.50 

func (f *FlagSet) Int64(name string, def int64, usage string) *scalar.ScalarFlag[int64]

Int64 defines an int flag and returns its handle.

func (*FlagSet) Int64Slice added in v0.0.50 

func (f *FlagSet) Int64Slice(name string, def []int64, usage string) *slice.SliceFlag[int64]

Int64Slice defines a []int64 flag and returns its handle.

func (*FlagSet) Int64SliceVar added in v0.0.50 

func (f *FlagSet) Int64SliceVar(ptr *[]int64, name string, def []int64, usage string) *slice.SliceFlag[int64]

Int64SliceVar defines a []int64 flag and binds it to the given pointer.

func (*FlagSet) Int64Var added in v0.0.50 

func (f *FlagSet) Int64Var(ptr *int64, name string, def int64, usage string) *scalar.ScalarFlag[int64]

Int64Var defines an int flag and binds it to the given pointer.

func (*FlagSet) IntSlice 

func (f *FlagSet) IntSlice(name string, def []int, usage string) *slice.SliceFlag[int]

IntSlice defines a []int flag and returns its handle.

func (*FlagSet) IntSliceVar 

func (f *FlagSet) IntSliceVar(ptr *[]int, name string, def []int, usage string) *slice.SliceFlag[int]

IntSliceVar defines a []int flag and binds it to the given pointer.

func (*FlagSet) IntVar 

func (f *FlagSet) IntVar(ptr *int, name string, def int, usage string) *scalar.ScalarFlag[int]

IntVar defines an int flag and binds it to the given pointer.

func (*FlagSet) Layout added in v0.0.52 

func (f *FlagSet) Layout() *LayoutOptions

Layout returns grouped helpers for configuring usage layout.

func (*FlagSet) LookupFlag added in v0.0.19 

func (f *FlagSet) LookupFlag(name string) *core.BaseFlag

LookupFlag retrieves a static flag by name.

func (*FlagSet) Name 

func (f *FlagSet) Name() string

Name returns the flag set's name.

func (*FlagSet) NewReplacerEnvKeyFunc added in v0.0.43 

func (f *FlagSet) NewReplacerEnvKeyFunc(replacer *strings.Replacer, upper bool) engine.EnvKeyFunc

NewReplacerEnvKeyFunc builds an EnvKeyFunc that: - returns "" when prefix is empty - applies the given replacer to the flag name - joins prefix + "_" + transformed name - upper-cases the result (if upper is true)

func (*FlagSet) Note 

func (f *FlagSet) Note(s string)

Note sets the bottom note section of the help output.

func (*FlagSet) NoteIndent added in v0.0.23 

func (f *FlagSet) NoteIndent() int

NoteIndent returns the note section indentation.

func (*FlagSet) NoteWidth added in v0.0.23 

func (f *FlagSet) NoteWidth() int

NoteWidth returns the wrapping width for help notes.

func (*FlagSet) OnUnknownFlag added in v0.0.52 

func (f *FlagSet) OnUnknownFlag(fn func(string) error)

OnUnknownFlag installs a handler for unknown flags. Return nil to ignore.

func (*FlagSet) OneOfGroups added in v0.0.36 

func (f *FlagSet) OneOfGroups() []*core.OneOfGroupGroup

OneOfGroups returns all registered OneOfGroups groups.

func (*FlagSet) Output 

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

Output returns the current output writer.

func (*FlagSet) Parse 

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

Parse processes the given CLI args and populates all registered flags.

func (*FlagSet) PrintAuthors added in v0.0.8 

func (f *FlagSet) PrintAuthors(w io.Writer)

PrintAuthors renders the author line if set.

func (*FlagSet) PrintDescription 

func (f *FlagSet) PrintDescription(w io.Writer, indent, width int)

PrintDescription renders the full description block.

func (*FlagSet) PrintDynamicDefaults added in v0.0.23 

func (f *FlagSet) PrintDynamicDefaults(w io.Writer, indent, col, width int)

PrintDynamicDefaults renders all dynamic flag usage lines.

func (*FlagSet) PrintNotes 

func (f *FlagSet) PrintNotes(w io.Writer, indent, width int)

PrintNotes renders the notes section, if configured.

func (*FlagSet) PrintStaticDefaults added in v0.0.23 

func (f *FlagSet) PrintStaticDefaults(w io.Writer, indent, col, width int)

PrintStaticDefaults renders all static flag usage lines.

func (*FlagSet) PrintTitle 

func (f *FlagSet) PrintTitle(w io.Writer)

PrintTitle renders the title above all help content.

func (*FlagSet) PrintUsage 

func (f *FlagSet) PrintUsage(w io.Writer, mode FlagPrintMode)

PrintUsage renders the top usage line.

func (*FlagSet) RequirePositional 

func (f *FlagSet) RequirePositional(n int)

RequirePositional sets how many positional arguments must be present.

func (*FlagSet) SetDescIndent added in v0.0.23 

func (f *FlagSet) SetDescIndent(n int)

SetDescIndent sets the indentation for the description block.

func (*FlagSet) SetDescWidth added in v0.0.23 

func (f *FlagSet) SetDescWidth(max int)

SetDescWidth sets the wrapping width for the description block.

func (*FlagSet) SetDynamicUsageColumn added in v0.0.25 

func (f *FlagSet) SetDynamicUsageColumn(col int)

SetDynamicUsageColumn sets the column at which dynamic flag descriptions begin.

func (*FlagSet) SetDynamicUsageIndent added in v0.0.25 

func (f *FlagSet) SetDynamicUsageIndent(n int)

SetDynamicUsageIndent sets the indentation for dynamic flag usage lines.

func (*FlagSet) SetDynamicUsageNote added in v0.0.23 

func (f *FlagSet) SetDynamicUsageNote(s string)

SetDynamicUsageNote adds a note after the dynamic flag block.

func (*FlagSet) SetDynamicUsageWidth added in v0.0.25 

func (f *FlagSet) SetDynamicUsageWidth(max int)

SetDynamicUsageWidth sets the max wrapping width for dynamic flags.

func (*FlagSet) SetEnvKeyFunc added in v0.0.43 

func (f *FlagSet) SetEnvKeyFunc(fn engine.EnvKeyFunc)

SetEnvKeyFunc sets a function to derive env keys from prefix+flag name.

func (*FlagSet) SetGetEnvFn 

func (f *FlagSet) SetGetEnvFn(fn func(string) string)

SetGetEnvFn overrides the function used to look up environment variables.

func (*FlagSet) SetNoteIndent added in v0.0.23 

func (f *FlagSet) SetNoteIndent(n int)

SetNoteIndent sets the indentation for help notes.

func (*FlagSet) SetNoteWidth added in v0.0.23 

func (f *FlagSet) SetNoteWidth(max int)

SetNoteWidth sets the wrapping width for help notes.

func (*FlagSet) SetOutput 

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

SetOutput changes the destination writer for usage and error messages.

func (*FlagSet) SetPositionalFinalize added in v0.0.48 

func (f *FlagSet) SetPositionalFinalize(fn func(string) string)

SetPositionalFinalize sets a function to finalize positional arguments.

func (*FlagSet) SetPositionalValidate added in v0.0.48 

func (f *FlagSet) SetPositionalValidate(fn func(string) error)

SetPositionalValidate sets a function to validate positional arguments.

func (*FlagSet) SetStaticUsageColumn added in v0.0.25 

func (f *FlagSet) SetStaticUsageColumn(col int)

SetStaticUsageColumn sets the column at which static flag descriptions begin.

func (*FlagSet) SetStaticUsageIndent added in v0.0.25 

func (f *FlagSet) SetStaticUsageIndent(n int)

SetStaticUsageIndent sets the indentation for static flag usage lines.

func (*FlagSet) SetStaticUsageNote added in v0.0.23 

func (f *FlagSet) SetStaticUsageNote(s string)

SetStaticUsageNote adds a note after the static flag block.

func (*FlagSet) SetStaticUsageWidth added in v0.0.25 

func (f *FlagSet) SetStaticUsageWidth(maxWidth int)

SetStaticUsageWidth sets the max wrapping width for static flag descriptions.

func (*FlagSet) SortedFlags added in v0.0.20 

func (f *FlagSet) SortedFlags()

SortedFlags enables sorted help output for static flags.

func (*FlagSet) SortedGroups added in v0.0.20 

func (f *FlagSet) SortedGroups()

SortedGroups enables sorted help output for dynamic groups.

func (*FlagSet) StaticAutoUsageColumn added in v0.0.23 

func (f *FlagSet) StaticAutoUsageColumn(padding int) int

StaticAutoUsageColumn computes a good usage column for static flags.

func (*FlagSet) StaticUsageColumn added in v0.0.25 

func (f *FlagSet) StaticUsageColumn() int

StaticUsageColumn returns the description column for static flags.

func (*FlagSet) StaticUsageIndent added in v0.0.25 

func (f *FlagSet) StaticUsageIndent() int

StaticUsageIndent returns the static usage indentation.

func (*FlagSet) StaticUsageNote added in v0.0.23 

func (f *FlagSet) StaticUsageNote() string

StaticUsageNote returns the static flag section note.

func (*FlagSet) StaticUsageWidth added in v0.0.25 

func (f *FlagSet) StaticUsageWidth() int

StaticUsageWidth returns the wrapping width for static flag descriptions.

func (*FlagSet) String 

func (f *FlagSet) String(name string, def string, usage string) *scalar.ScalarFlag[string]

String defines a string flag and returns its handle.

func (*FlagSet) StringSlice 

func (f *FlagSet) StringSlice(name string, def []string, usage string) *slice.SliceFlag[string]

StringSlice defines a []string flag and returns its handle.

func (*FlagSet) StringSliceVar 

func (f *FlagSet) StringSliceVar(ptr *[]string, name string, def []string, usage string) *slice.SliceFlag[string]

StringSliceVar defines a []string flag and binds it to the given pointer.

func (*FlagSet) StringVar 

func (f *FlagSet) StringVar(ptr *string, name string, def string, usage string) *scalar.ScalarFlag[string]

StringVar defines a string flag and binds it to the given pointer.

func (*FlagSet) TCPAddr added in v0.0.8 

func (f *FlagSet) TCPAddr(name string, def *net.TCPAddr, usage string) *scalar.ScalarFlag[*net.TCPAddr]

TCPAddr defines a *net.TCPAddr flag and returns its handle.

func (*FlagSet) TCPAddrSlice added in v0.0.8 

func (f *FlagSet) TCPAddrSlice(name string, def []*net.TCPAddr, usage string) *slice.SliceFlag[*net.TCPAddr]

TCPAddrSlice defines a []*net.TCPAddr flag and returns its handle.

func (*FlagSet) TCPAddrSliceVar added in v0.0.8 

func (f *FlagSet) TCPAddrSliceVar(ptr *[]*net.TCPAddr, name string, def []*net.TCPAddr, usage string) *slice.SliceFlag[*net.TCPAddr]

TCPAddrSliceVar defines a []*net.TCPAddr flag and binds it to the given pointer.

func (*FlagSet) TCPAddrVar added in v0.0.8 

func (f *FlagSet) TCPAddrVar(ptr **net.TCPAddr, name string, def *net.TCPAddr, usage string) *scalar.ScalarFlag[*net.TCPAddr]

TCPAddrVar defines a *net.TCPAddr flag and binds it to the given pointer.

func (*FlagSet) Time added in v0.0.8 

func (f *FlagSet) Time(name string, def time.Time, usage string) *scalar.ScalarFlag[time.Time]

Time defines a time.Time flag and returns its handle.

func (*FlagSet) TimeSlice added in v0.0.8 

func (f *FlagSet) TimeSlice(name string, def []time.Time, usage string) *slice.SliceFlag[time.Time]

TimeSlice defines a []time.Time flag and returns its handle.

func (*FlagSet) TimeSliceVar added in v0.0.8 

func (f *FlagSet) TimeSliceVar(ptr *[]time.Time, name string, def []time.Time, usage string) *slice.SliceFlag[time.Time]

TimeSliceVar defines a []time.Time flag and binds it to the given pointer.

func (*FlagSet) TimeVar added in v0.0.8 

func (f *FlagSet) TimeVar(ptr *time.Time, name string, def time.Time, usage string) *scalar.ScalarFlag[time.Time]

TimeVar defines a time.Time flag and binds it to the given pointer.

func (*FlagSet) Title 

func (f *FlagSet) Title(s string)

Title sets the main title shown in usage output.

func (*FlagSet) URL 

func (f *FlagSet) URL(name string, def *url.URL, usage string) *scalar.ScalarFlag[*url.URL]

URL defines a *url.URL flag and returns its handle.

func (*FlagSet) URLSlice 

func (f *FlagSet) URLSlice(name string, def []*url.URL, usage string) *slice.SliceFlag[*url.URL]

URLSlice defines a []*url.URL flag and returns its handle.

func (*FlagSet) URLSliceVar 

func (f *FlagSet) URLSliceVar(ptr *[]*url.URL, name string, def []*url.URL, usage string) *slice.SliceFlag[*url.URL]

URLSliceVar defines a []*url.URL flag and binds it to the given pointer.

func (*FlagSet) URLVar 

func (f *FlagSet) URLVar(ptr **url.URL, name string, def *url.URL, usage string) *scalar.ScalarFlag[*url.URL]

URLVar defines a *url.URL flag and binds it to the given pointer.

func (*FlagSet) Version 

func (f *FlagSet) Version(s string)

Version sets the --version string.

func (*FlagSet) VersionText added in v0.0.44 

func (f *FlagSet) VersionText(s string)

VersionText sets the --version text.

type HelpOptions added in v0.0.52 

type HelpOptions struct {
	// contains filtered or unexported fields
}

HelpOptions groups high-level help/metadata settings.

func (*HelpOptions) Authors added in v0.0.52 

func (h *HelpOptions) Authors(s string)

func (*HelpOptions) Description added in v0.0.52 

func (h *HelpOptions) Description(s string)

func (*HelpOptions) DisableHelp added in v0.0.52 

func (h *HelpOptions) DisableHelp()

func (*HelpOptions) DisableVersion added in v0.0.52 

func (h *HelpOptions) DisableVersion()

func (*HelpOptions) HelpText added in v0.0.52 

func (h *HelpOptions) HelpText(s string)

func (*HelpOptions) Note added in v0.0.52 

func (h *HelpOptions) Note(s string)

func (*HelpOptions) Title added in v0.0.52 

func (h *HelpOptions) Title(s string)

func (*HelpOptions) VersionText added in v0.0.52 

func (h *HelpOptions) VersionText(s string)

type HelpRequested 

type HelpRequested = engine.HelpRequested

Common user-triggered exit conditions.

type LayoutOptions added in v0.0.52 

type LayoutOptions struct {
	// contains filtered or unexported fields
}

LayoutOptions groups usage/indent/width configuration.

func (*LayoutOptions) SetDescIndent added in v0.0.52 

func (l *LayoutOptions) SetDescIndent(n int)

func (*LayoutOptions) SetDescWidth added in v0.0.52 

func (l *LayoutOptions) SetDescWidth(max int)

func (*LayoutOptions) SetDynamicUsageColumn added in v0.0.52 

func (l *LayoutOptions) SetDynamicUsageColumn(col int)

func (*LayoutOptions) SetDynamicUsageIndent added in v0.0.52 

func (l *LayoutOptions) SetDynamicUsageIndent(n int)

func (*LayoutOptions) SetDynamicUsageNote added in v0.0.52 

func (l *LayoutOptions) SetDynamicUsageNote(s string)

func (*LayoutOptions) SetDynamicUsageWidth added in v0.0.52 

func (l *LayoutOptions) SetDynamicUsageWidth(max int)

func (*LayoutOptions) SetNoteIndent added in v0.0.52 

func (l *LayoutOptions) SetNoteIndent(n int)

func (*LayoutOptions) SetNoteWidth added in v0.0.52 

func (l *LayoutOptions) SetNoteWidth(max int)

func (*LayoutOptions) SetStaticUsageColumn added in v0.0.52 

func (l *LayoutOptions) SetStaticUsageColumn(col int)

func (*LayoutOptions) SetStaticUsageIndent added in v0.0.52 

func (l *LayoutOptions) SetStaticUsageIndent(n int)

func (*LayoutOptions) SetStaticUsageNote added in v0.0.52 

func (l *LayoutOptions) SetStaticUsageNote(s string)

func (*LayoutOptions) SetStaticUsageWidth added in v0.0.52 

func (l *LayoutOptions) SetStaticUsageWidth(maxWidth int)

type StaticFlag added in v0.0.23 

type StaticFlag = core.BaseFlag // Static flag definition metadata

Exported types for advanced access.

type VersionRequested 

type VersionRequested = engine.VersionRequested

Common user-triggered exit conditions.

Source Files

View all Source files

Directories

Path Synopsis
examples
advanced command
dynamic command
groups command
simple command
toggle command
internal
builder
core
dynamic
Package dynamic implements dynamic flag types that support multiple per-identifier values (e.g.
 Package dynamic implements dynamic flag types that support multiple per-identifier values (e.g.
engine
scalar
slice
utils

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.