Documentation ¶
Overview ¶
Declaratively create heirarchical command line apps.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
An App contains your defined sections, commands, and flags Create a new App with New()
func New ¶
New builds a new App!
Example ¶
package main import ( "fmt" "os" "github.com/bbkane/warg" "github.com/bbkane/warg/command" "github.com/bbkane/warg/flag" "github.com/bbkane/warg/section" "github.com/bbkane/warg/value" ) func login(pf flag.PassedFlags) error { url := pf["--url"].(string) // timeout doesn't have a default value, // so we can't rely on it being passed. timeout, exists := pf["--timeout"] if exists { timeout := timeout.(int) fmt.Printf("Logging into %s with timeout %d\n", url, timeout) return nil } fmt.Printf("Logging into %s\n", url) return nil } func main() { app := warg.New( "blog", section.New( "work with a fictional blog platform", section.Command( "login", "Login to the platform", login, ), section.Flag( "--timeout", "Optional timeout. Defaults to no timeout", value.Int, ), section.Flag( "--url", "URL of the blog", value.String, flag.Default("https://www.myblog.com"), flag.EnvVars("BLOG_URL"), ), section.Section( "comments", "Deal with comments", section.Command( "list", "List all comments", // still prototyping how we want this // command to look, // so use a provided stub action command.DoNothing, ), ), ), ) // normally we would rely on the user to set the environment variable, // bu this is an example err := os.Setenv("BLOG_URL", "https://envvar.com") if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } app.MustRun([]string{"blog.exe", "login"}, os.LookupEnv) }
Output: Logging into https://envvar.com
func (*App) MustRun ¶
func (app *App) MustRun(osArgs []string, osLookupEnv LookupFunc)
MustRun runs the app. Any flag parsing errors will be printed to stderr and os.Exit(64) (EX_USAGE) will be called. Any errors on an Action will be printed to stderr and os.Exit(1) will be called.
func (*App) Parse ¶
func (app *App) Parse(osArgs []string, osLookupEnv LookupFunc) (*ParseResult, error)
Parse parses the args, but does not execute anything.
type AppOpt ¶
type AppOpt = func(*App)
AppOpt let's you customize the app. It panics if there is an error
func ConfigFlag ¶
func ConfigFlag( configFlagName flag.Name, newConfigReader config.NewReader, helpShort flag.HelpShort, flagOpts ...flag.FlagOpt, ) AppOpt
Use ConfigFlag in conjunction with flag.ConfigPath to allow users to override flag defaults with values from a config.
Example ¶
package main import ( "fmt" "io/ioutil" "log" "os" "github.com/bbkane/warg" "github.com/bbkane/warg/command" "github.com/bbkane/warg/config/yamlreader" "github.com/bbkane/warg/flag" "github.com/bbkane/warg/section" "github.com/bbkane/warg/value" ) func exampleConfigFlagTextAdd(pf flag.PassedFlags) error { addends := pf["--addend"].([]int) sum := 0 for _, a := range addends { sum += a } fmt.Printf("Sum: %d\n", sum) return nil } func main() { app := warg.New( "calc", section.New( "do math", section.Command( command.Name("add"), "add integers", exampleConfigFlagTextAdd, command.Flag( flag.Name("--addend"), "Integer to add. Floats will be truncated. Flag is repeatible", value.IntSlice, flag.ConfigPath("add.addends"), flag.Required(), ), ), ), warg.ConfigFlag( "--config", yamlreader.New, "path to YAML config file", flag.Alias("-c"), flag.Default("~/.config/calc.yaml"), ), ) err := ioutil.WriteFile( "/tmp/calc.yaml", []byte( ` add: addends: - 1 - 2 - 3 `), 0644, ) if err != nil { log.Fatalf("write error: %e", err) } app.MustRun([]string{"calc", "-c", "calc.yaml", "add"}, os.LookupEnv) }
Output: Sum: 6
func OverrideHelpFlag ¶ added in v0.0.3
func OverrideHelpFlag( mappings []help.HelpFlagMapping, helpFile *os.File, flagName flag.Name, flagHelp flag.HelpShort, flagOpts ...flag.FlagOpt, ) AppOpt
OverrideHelpFlag customizes your --help. If you write a custom --help function, you'll want to add it to your app here!
Example ¶
package main import ( "fmt" "os" "github.com/bbkane/warg" "github.com/bbkane/warg/command" "github.com/bbkane/warg/flag" "github.com/bbkane/warg/help" "github.com/bbkane/warg/section" ) func exampleOverrideHelpFlaglogin(pf flag.PassedFlags) error { fmt.Println("Logging in") return nil } func exampleOverrideHelpFlagCustomCommandHelp(file *os.File, _ *command.Command, _ help.HelpInfo) command.Action { return func(_ flag.PassedFlags) error { fmt.Fprintln(file, "Custom command help") return nil } } func exampleOverrideHelpFlagCustomSectionHelp(file *os.File, _ *section.SectionT, _ help.HelpInfo) command.Action { return func(_ flag.PassedFlags) error { fmt.Fprintln(file, "Custom section help") return nil } } func main() { app := warg.New( "blog", section.New( "work with a fictional blog platform", section.Command( "login", "Login to the platform", exampleOverrideHelpFlaglogin, ), ), warg.OverrideHelpFlag( []help.HelpFlagMapping{ { Name: "default", CommandHelp: help.DetailedCommandHelp, SectionHelp: help.DetailedSectionHelp, }, { Name: "custom", CommandHelp: exampleOverrideHelpFlagCustomCommandHelp, SectionHelp: exampleOverrideHelpFlagCustomSectionHelp, }, }, os.Stdout, "--help", "Print help", flag.Alias("-h"), // the flag default should match a name in the HelpFlagMapping flag.Default("default"), ), ) app.MustRun([]string{"blog.exe", "-h", "custom"}, os.LookupEnv) }
Output: Custom section help
type LookupFunc ¶ added in v0.0.2
Look up keys (meant for environment variable parsing) - fulfillable with os.LookupEnv or warg.LookupMap(map)
func LookupMap ¶ added in v0.0.3
func LookupMap(m map[string]string) LookupFunc
LookupMap loooks up keys from a provided map. Useful to mock os.LookupEnv when parsing
type ParseResult ¶
type ParseResult struct { // Path to the command invoked. Does not include executable name (os.Args[0]) Path []string // PassedFlags holds the set flags! PassedFlags flag.PassedFlags // Action holds the passed command's action to execute. Action command.Action }
ParseResult holds the result of parsing the command line.