flago

README

Flago

🐉 Simple and Flexible Command line flag parser

Install ⭐️

go get github.com/Gers2017/flago

Basic Usage 🔥

Import flago

import (
    "github.com/Gers2017/flago"
)

Populate the flagset

get := flago.NewFlagSet("get")
get.Bool("all", false)
get.Switch("verbose") // Same as get.Bool("verbose", false)

Builder

get := flago.NewFlagSet("get").
    Bool("all", false).
    Switch("verbose") // Same as get.Bool("verbose", false)

Using the Cli struct

cli := flago.NewCli()
cli.Handle(get, func(fs *flago.FlagSet) error {
    HandleFlagset(fs) // do something with parsed get
    return nil
})

if err := cli.Execute(os.Args); err != nil {
    log.Fatal(err)
}

func HandleFlagset(fs *flago.FlagSet) {
    if fs.Bool("help") {
		fmt.Println("Some helpful help message")
		return
	}

    // Do something...
    fmt.Println(todos)
}

Without the Cli struct

Parse the arguments into flags

// os.Args = []string{ "cli", "all", "help" }
if err := get.ParseFlags(os.Args[1:]); err != nil {
    log.Fatal(err)
    return
}

Then use the parsed flagset

if get.IsParsed("all") {
    if get.Bool("help") {
        fmt.Println("Some helpful help message")
        return
    }
    // Do something...
    fmt.Println(todos)
}

Demo 🐲

A complete example can be found here

New FlagSet

get := flago.NewFlagSet("get")

Add flags

get.SetSwitch("verbose")
get.Int("x", 0)

Check if a flag was parsed

It's highly recommended to use this method to check first if a flag was parsed correctly.

get.IsParsed("your-flag-name")

The FlagSet.[Bool, Int, Float, Str] methods are just a shortcut for:

Get values

verbose := get.Bool("verbose")
x := get.Int("x")

If the flag name inside the getter method is not registered in the flagset, you'll get an error at runtime.

wrong := get.Bool("some-invalid-flag")

About the API

Why so many strings? Isn't that error-prone?

1. The FlagSet.[Bool, Int, Float, Str] method can raise an error at runtine (use FlagSet.IsParsed to avoid this)

2. A note on golang's generics Behind the scenes flago uses maps + generics + type parsing The Flag struct contains a Value property of type any.

   Because if we try to use generics we'd need to declare a map for every type of flag inside Flagset, and Flags map[string]*Flag wouldn't work anymore leading to repeated code.

   The flag module in the standard library solves this by using pointers to the underliying values.

Documentation

Index

• type Cli
  • func NewCli() *Cli
  • func (cli *Cli) Execute(args []string) error
  • func (cli *Cli) Handle(flagset *FlagSet, handler HandlerFunc)
• type DataTypeName
• type Flag
  • func NewFlag[V FlagDataType](name string, value V, datatype DataTypeName) *Flag
  • func (f *Flag) ToBool() bool
  • func (f *Flag) ToFloat() float64
  • func (f *Flag) ToInt() int
  • func (f *Flag) ToStr() string
• type FlagDataType
• type FlagSet
  • func NewFlagSet(name string) *FlagSet
  • func (fs *FlagSet) Bool(key string) bool
  • func (fs *FlagSet) Float(key string) float64
  • func (fs *FlagSet) GetFlag(name string) (*Flag, bool)
  • func (fs *FlagSet) Int(key string) int
  • func (fs *FlagSet) IsParsed(name string) bool
  • func (fs *FlagSet) ParseFlags(args []string) error
  • func (fs *FlagSet) SetBool(name string, init bool) *FlagSet
  • func (fs *FlagSet) SetFloat(name string, init float64) *FlagSet
  • func (fs *FlagSet) SetInt(name string, init int) *FlagSet
  • func (fs *FlagSet) SetStr(name string, init string) *FlagSet
  • func (fs *FlagSet) SetSwitch(name string) *FlagSet
  • func (fs *FlagSet) Str(key string) string
• type HandlerFunc

Types

type Cli

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

func NewCli

func NewCli() *Cli

func (*Cli) Execute

func (cli *Cli) Execute(args []string) error

func (*Cli) Handle

func (cli *Cli) Handle(flagset *FlagSet, handler HandlerFunc)

type DataTypeName

type DataTypeName string

const (
	INT    DataTypeName = "int"
	FLOAT  DataTypeName = "float"
	BOOL   DataTypeName = "bool"
	STRING DataTypeName = "string"
)

type Flag

type Flag struct {
	Name     string
	Value    any
	Datatype DataTypeName
}

func NewFlag

func NewFlag[V FlagDataType](name string, value V, datatype DataTypeName) *Flag

func (*Flag) ToBool

func (f *Flag) ToBool() bool

func (*Flag) ToFloat

func (f *Flag) ToFloat() float64

func (*Flag) ToInt

func (f *Flag) ToInt() int

func (*Flag) ToStr

func (f *Flag) ToStr() string

type FlagDataType

type FlagDataType interface {
	int | float64 | string | bool
}

type FlagSet

type FlagSet struct {
	Name        string
	Flags       map[string]*Flag
	ParsedFlags map[string]bool
}

func NewFlagSet

func NewFlagSet(name string) *FlagSet

func (*FlagSet) Bool

func (fs *FlagSet) Bool(key string) bool

func (*FlagSet) Float

func (fs *FlagSet) Float(key string) float64

func (*FlagSet) GetFlag

func (fs *FlagSet) GetFlag(name string) (*Flag, bool)

func (*FlagSet) Int

func (fs *FlagSet) Int(key string) int

func (*FlagSet) IsParsed

func (fs *FlagSet) IsParsed(name string) bool

func (*FlagSet) ParseFlags

func (fs *FlagSet) ParseFlags(args []string) error

func (*FlagSet) SetBool

func (fs *FlagSet) SetBool(name string, init bool) *FlagSet

func (*FlagSet) SetFloat

func (fs *FlagSet) SetFloat(name string, init float64) *FlagSet

func (*FlagSet) SetInt

func (fs *FlagSet) SetInt(name string, init int) *FlagSet

func (*FlagSet) SetStr

func (fs *FlagSet) SetStr(name string, init string) *FlagSet

func (*FlagSet) SetSwitch

func (fs *FlagSet) SetSwitch(name string) *FlagSet

func (*FlagSet) Str

func (fs *FlagSet) Str(key string) string

type HandlerFunc

type HandlerFunc = func(fs *FlagSet) error