flag

README

lesiw.io/flag

A flag parser for the lazy. Follows the POSIX utility conventions plus GNU --longopts.

So, for example, -abcd could be four boolean flags, or -b could be a string flag that considers cd to be the argument passed to it.

Pass in an io.Writer when creating a flag.Set and the Parse method will write errors and usage help messages directly to that writer. If Parse returns an error, it is recommended that the program author exit as soon as possible without additional output.

Aliases can be made at flag definition time by passing in comma-separated flag names.

Example

package main

import (
    "fmt"
    "os"

    "lesiw.io/flag"
)

var (
    flags = flag.NewSet(os.Stderr, "sandbox [-w WORD] [-n NUM] [-b] ARGS...")
    word  = flags.String("w,word", "a string")
    num   = flags.Int("n,num", "an int")
    bool  = flags.Bool("b,bool", "a bool")
)

func main() {
    os.Exit(run())
}

func run() int {
    // Playground note: Replace os.Args with other strings to test.
    if err := flags.Parse(os.Args[1:]...); err != nil {
        return 1
    }
    if len(flags.Args) < 1 {
        flags.PrintError("at least one arg is required")
        return 1
    }

    fmt.Println("word:", *word)
    fmt.Println("num:", *num)
    fmt.Println("bool:", *bool)
    fmt.Println("args:", flags.Args)

    return 0
}

▶️ Run this example on the Go Playground

Documentation

Index

• type Flag
• type Set
  • func NewSet(output io.Writer, usage string) *Set
  • func (s *Set) Arg(i int) string
  • func (s *Set) Bool(name string, usage string) *bool
  • func (s *Set) BoolVar(p *bool, name string, usage string)
  • func (s *Set) Defaults() string
  • func (s *Set) Int(name string, usage string) *int
  • func (s *Set) IntVar(p *int, name string, usage string)
  • func (s *Set) Parse(args ...string) (err error)
  • func (s *Set) PrintError(e string)
  • func (s *Set) PrintUsage()
  • func (s *Set) Set(name string) bool
  • func (s *Set) String(name string, usage string) *string
  • func (s *Set) StringVar(p *string, name string, usage string)
  • func (s *Set) Strings(name string, usage string) *[]string
  • func (s *Set) StringsVar(p *[]string, name string, usage string)
  • func (s *Set) Var(value Value, name string, usage string)
  • func (s *Set) Visit(fn func(*Flag))
• type Value

Examples

• Set.Bool
• Set.String
• Set.String (Mixed)

Types

type Flag

type Flag struct {
	Names []string
	Usage string
	Value Value
	// contains filtered or unexported fields
}

type Set

type Set struct {
	Args []string
	// contains filtered or unexported fields
}

func NewSet

func NewSet(output io.Writer, usage string) *Set

func (*Set) Arg

func (s *Set) Arg(i int) string

func (*Set) Bool

func (s *Set) Bool(name string, usage string) *bool

Example

package main

import (
	"fmt"
	"os"

	"lesiw.io/flag"
)

func main() {
	var (
		flags = flag.NewSet(os.Stderr, "example")
		bool  = flags.Bool("b", "some bool")
	)
	if err := flags.Parse("example", "-b"); err != nil {
		panic(err)
	}
	fmt.Println("bool:", *bool)
}

Output:

bool: true

func (*Set) BoolVar

func (s *Set) BoolVar(p *bool, name string, usage string)

func (*Set) Defaults

func (s *Set) Defaults() string

func (*Set) Int

func (s *Set) Int(name string, usage string) *int

func (*Set) IntVar

func (s *Set) IntVar(p *int, name string, usage string)

func (*Set) Parse

func (s *Set) Parse(args ...string) (err error)

func (*Set) PrintError

func (s *Set) PrintError(e string)

func (*Set) PrintUsage

func (s *Set) PrintUsage()

func (*Set) Set

func (s *Set) Set(name string) bool

func (*Set) String

func (s *Set) String(name string, usage string) *string

Example

package main

import (
	"fmt"
	"os"

	"lesiw.io/flag"
)

func main() {
	var (
		flags = flag.NewSet(os.Stderr, "example")
		word  = flags.String("w", "a string")
	)
	if err := flags.Parse("example", "-wfoo"); err != nil {
		panic(err)
	}
	fmt.Println("word:", *word)
}

Output:

word: foo

Example (Mixed)

package main

import (
	"fmt"
	"os"

	"lesiw.io/flag"
)

func main() {
	var (
		flags = flag.NewSet(os.Stderr, "example")
		boola = flags.Bool("a", "some bool")
		boolb = flags.Bool("b", "some other bool")
		word  = flags.String("c", "a string")
	)
	if err := flags.Parse("example", "-abcde"); err != nil {
		panic(err)
	}
	fmt.Println("bool 'a':", *boola)
	fmt.Println("bool 'b':", *boolb)
	fmt.Println("word:", *word)
}

Output:

bool 'a': true
bool 'b': true
word: de

func (*Set) StringVar

func (s *Set) StringVar(p *string, name string, usage string)

func (*Set) Strings

func (s *Set) Strings(name string, usage string) *[]string

func (*Set) StringsVar

func (s *Set) StringsVar(p *[]string, name string, usage string)

func (*Set) Var

func (s *Set) Var(value Value, name string, usage string)

func (*Set) Visit

func (s *Set) Visit(fn func(*Flag))

type Value

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