flagg

README

flagg

go get lukechampine.com/flagg

flagg is a tiny package that makes it easier to build CLI apps that use subcommands. I built it because the stdlib flag package is too low-level, but popular alternatives like spf13/cobra are full-fledged frameworks with too many bells and whistles for my liking.

flagg is designed around the stdlib *flag.FlagSet type. Simply put, it is a utility for constructing a hierarchy of *flag.FlagSet-based commands, parsing them, and identifying which command was selected.

NOTE: flagg requires Go 1.10, which added new methods to the flag.FlagSet type.

Example

// commands are just *flag.FlagSets
var rootCmd *flag.FlagSet = flagg.Root
rootCmd.Usage = flagg.SimpleUsage(rootCmd, "An example program")
verbose := rootCmd.Bool("v", false, "display verbose output")

// flagg.New constructs a *flag.FlagSet with the given name and usage
// description
fooCmd := flagg.New("foo", "The foo subcommand")
bars := fooCmd.Int("bars", 0, "number of bars to foo")
quuxCmd := flagg.New("quux", "The quux subcommand")

// construct the command hierarchy
tree := flagg.Tree{
	Cmd: rootCmd,
	Sub: []flagg.Tree{
		{Cmd: fooCmd},
		{Cmd: quuxCmd},
	},
}

// Parse the command hierarchy. cmd is the selected command, e.g. if
// os.Args = []string{"./example", "quux"}, then cmd == quuxCmd.
cmd := flagg.Parse(tree)

// again, cmd is just a *flag.FlagSet, so Args() returns the arguments of the
// selected command.
args := cmd.Args()

// use a switch to identify the cmd that was selected
switch cmd {
case fooCmd:
	fmt.Printf("fooing %v bars\n", *bars)
case quuxCmd:
	fmt.Println("quux!", args)
}

Documentation

Overview

Package flagg provides a simple means of constructing CLI command hierarchies. A hierarchy is simply a tree of flag.FlagSets; the Parse function is then used to determine which command is being invoked.

Index

• Variables
• func IsDefined(cmd *flag.FlagSet, flg string) bool
• func New(name, usage string) *flag.FlagSet
• func Parse(tree Tree) *flag.FlagSet
• func SimpleUsage(cmd *flag.FlagSet, usage string) func()
• type Tree

Variables

var Root = flag.CommandLine

Root is the default root flag.FlagSet.

Functions

func IsDefined

func IsDefined(cmd *flag.FlagSet, flg string) bool

IsDefined returns true if flg was supplied to cmd. IsDefined may only be called after cmd has been parsed.

func New

func New(name, usage string) *flag.FlagSet

New returns a new flag.FlagSet. It is equivalent to flag.NewFlagSet(name, flag.ExitOnError), and setting f.Usage = SimpleUsage(f, usage)

func Parse

func Parse(tree Tree) *flag.FlagSet

Parse parses os.Args according to the supplied Tree. It returns the most deeply-nested flag.FlagSet selected by the args.

func SimpleUsage

func SimpleUsage(cmd *flag.FlagSet, usage string) func()

SimpleUsage returns a func that writes usage to cmd.Output(). If cmd has associated flags, the func also calls cmd.PrintDefaults.

Types

type Tree

type Tree struct {
	Cmd *flag.FlagSet
	Sub []Tree
}

A Tree is a tree of commands and subcommands.