diff --git a/app.go b/app.go index 2b3a434..683f453 100644 --- a/app.go +++ b/app.go @@ -6,6 +6,8 @@ import ( "os" ) +// App is the main structure of a cli application. It is recomended that +// and app be created with the cli.NewApp() function type App struct { // The name of the program. Defaults to os.Args[0] Name string @@ -21,6 +23,7 @@ type App struct { Action func(context *Context) } +// Creates a new cli Application with some reasonable defaults for Name, Usage, Version and Action. func NewApp() *App { return &App{ Name: os.Args[0], @@ -30,6 +33,7 @@ func NewApp() *App { } } +// Entry point to the cli app. Parses the arguments slice and routes to the proper flag/args combination func (a *App) Run(arguments []string) { // append help to commands if a.Command(helpCommand.Name) == nil { @@ -70,6 +74,7 @@ func (a *App) Run(arguments []string) { a.Action(context) } +// Returns the named command on App. Returns nil if the command does not exist func (a *App) Command(name string) *Command { for _, c := range a.Commands { if c.HasName(name) { diff --git a/command.go b/command.go index ce67258..c26ba2a 100644 --- a/command.go +++ b/command.go @@ -7,15 +7,23 @@ import ( "strings" ) +// Command is a subcommand for a cli.App. type Command struct { - Name string - ShortName string - Usage string + // The name of the command + Name string + // short name of the command. Typically one character + ShortName string + // A short description of the usage of this command + Usage string + // A longer explaination of how the command works Description string - Action func(context *Context) - Flags []Flag + // The function to call when this command is invoked + Action func(context *Context) + // List of flags to parse + Flags []Flag } +// Invokes the command given the context, parses ctx.Args() to generate command-specific flags func (c Command) Run(ctx *Context) { // append help to flags c.Flags = append( @@ -55,6 +63,7 @@ func (c Command) Run(ctx *Context) { c.Action(context) } +// Returns true if Command.Name or Command.ShortName matches given name func (c Command) HasName(name string) bool { return c.Name == name || c.ShortName == name } diff --git a/context.go b/context.go index 4574cf7..877aaa1 100644 --- a/context.go +++ b/context.go @@ -15,6 +15,7 @@ type Context struct { globalSet *flag.FlagSet } +// Creates a new context. For use in when invoking an App or Command action. func NewContext(app *App, set *flag.FlagSet, globalSet *flag.FlagSet) *Context { return &Context{app, set, globalSet} } @@ -69,6 +70,7 @@ func (c *Context) GlobalIntSlice(name string) []int { return c.lookupIntSlice(name, c.globalSet) } +// Returns the command line arguments associated with the context. func (c *Context) Args() []string { return c.flagSet.Args() } diff --git a/flag.go b/flag.go index 1085184..ae70e94 100644 --- a/flag.go +++ b/flag.go @@ -4,8 +4,12 @@ import "fmt" import "flag" import "strconv" +// Flag is a common interface related to parsing flags in cli. +// For more advanced flag parsing techniques, it is recomended that +// this interface be implemented. type Flag interface { fmt.Stringer + // Apply Flag settings to the given flag set Apply(*flag.FlagSet) } diff --git a/flag_test.go b/flag_test.go index df99cba..0cd7990 100644 --- a/flag_test.go +++ b/flag_test.go @@ -45,7 +45,6 @@ func TestStringFlagHelpOutput(t *testing.T) { } } - var intFlagTests = []struct { name string expected string @@ -64,4 +63,4 @@ func TestIntFlagHelpOutput(t *testing.T) { t.Errorf("%s does not match %s", output, test.expected) } } -} \ No newline at end of file +}