Add flag category support (#796)

app.go

@@ -52,6 +52,8 @@ type App struct {
 	HideVersion bool
 	// categories contains the categorized commands and is populated on app startup
 	categories CommandCategories
+	// flagCategories contains the categorized flags and is populated on app startup
+	flagCategories FlagCategories
 	// An action to execute when the shell completion flag is set
 	BashComplete BashCompleteFunc
 	// An action to execute before any subcommands are run, but after the context is ready
@@ -181,6 +183,15 @@ func (a *App) Setup() {
 		if c.HelpName == "" {
 			c.HelpName = fmt.Sprintf("%s %s", a.HelpName, c.Name)
 		}
+
+		fc := newFlagCategories()
+		for _, fl := range c.Flags {
+			if cf, ok := fl.(CategorizableFlag); ok {
+				fc.AddFlag(cf.GetCategory(), cf)
+			}
+		}
+
+		c.flagCategories = fc
 		newCommands = append(newCommands, c)
 	}
 	a.Commands = newCommands
@@ -205,6 +216,13 @@ func (a *App) Setup() {
 	}
 	sort.Sort(a.categories.(*commandCategories))
 
+	a.flagCategories = newFlagCategories()
+	for _, fl := range a.Flags {
+		if cf, ok := fl.(CategorizableFlag); ok {
+			a.flagCategories.AddFlag(cf.GetCategory(), cf)
+		}
+	}
+
 	if a.Metadata == nil {
 		a.Metadata = make(map[string]interface{})
 	}
@@ -481,6 +499,14 @@ func (a *App) VisibleCommands() []*Command {
 	return ret
 }
 
+// VisibleFlagCategories returns a slice containing all the categories with the flags they contain
+func (a *App) VisibleFlagCategories() []VisibleFlagCategory {
+	if a.flagCategories == nil {
+		a.flagCategories = newFlagCategories()
+	}
+	return a.flagCategories.VisibleCategories()
+}
+
 // VisibleFlags returns a slice of the Flags with Hidden=false
 func (a *App) VisibleFlags() []Flag {
 	return visibleFlags(a.Flags)

app_test.go

@@ -142,8 +142,8 @@ func ExampleApp_Run_appHelp() {
 	//    help, h        Shows a list of commands or help for one command
 	//
 	// GLOBAL OPTIONS:
-	//    --name value   a name to say (default: "bob")
 	//    --help, -h     show help (default: false)
+	//    --name value   a name to say (default: "bob")
 	//    --version, -v  print the version (default: false)
 }
 
@@ -1924,6 +1924,14 @@ func TestApp_VisibleCategories(t *testing.T) {
 	expect(t, []CommandCategory{}, app.VisibleCategories())
 }
 
+func TestApp_VisibleFlagCategories(t *testing.T) {
+	app := &App{}
+	vfc := app.VisibleFlagCategories()
+	if len(vfc) != 0 {
+		t.Errorf("unexpected visible flag categories %+v", vfc)
+	}
+}
+
 func TestApp_Run_DoesNotOverwriteErrorFromBefore(t *testing.T) {
 	app := &App{
 		Action: func(c *Context) error { return nil },

category.go

@@ -1,10 +1,12 @@
 package cli
 
+import "sort"
+
 // CommandCategories interface allows for category manipulation
 type CommandCategories interface {
 	// AddCommand adds a command to a category, creating a new category if necessary.
 	AddCommand(category string, command *Command)
-	// categories returns a copy of the category slice
+	// Categories returns a slice of categories sorted by name
 	Categories() []CommandCategory
 }
 
@@ -77,3 +79,82 @@ func (c *commandCategory) VisibleCommands() []*Command {
 	}
 	return ret
 }
+
+// FlagCategories interface allows for category manipulation
+type FlagCategories interface {
+	// AddFlags adds a flag to a category, creating a new category if necessary.
+	AddFlag(category string, fl Flag)
+	// VisibleCategories returns a slice of visible flag categories sorted by name
+	VisibleCategories() []VisibleFlagCategory
+}
+
+type defaultFlagCategories struct {
+	m map[string]*defaultVisibleFlagCategory
+}
+
+func newFlagCategories() FlagCategories {
+	return &defaultFlagCategories{
+		m: map[string]*defaultVisibleFlagCategory{},
+	}
+}
+
+func (f *defaultFlagCategories) AddFlag(category string, fl Flag) {
+	if _, ok := f.m[category]; !ok {
+		f.m[category] = &defaultVisibleFlagCategory{name: category, m: map[string]Flag{}}
+	}
+
+	f.m[category].m[fl.String()] = fl
+}
+
+func (f *defaultFlagCategories) VisibleCategories() []VisibleFlagCategory {
+	catNames := []string{}
+	for name := range f.m {
+		catNames = append(catNames, name)
+	}
+
+	sort.Strings(catNames)
+
+	ret := make([]VisibleFlagCategory, len(catNames))
+	for i, name := range catNames {
+		ret[i] = f.m[name]
+	}
+
+	return ret
+}
+
+// VisibleFlagCategory is a category containing flags.
+type VisibleFlagCategory interface {
+	// Name returns the category name string
+	Name() string
+	// Flags returns a slice of VisibleFlag sorted by name
+	Flags() []VisibleFlag
+}
+
+type defaultVisibleFlagCategory struct {
+	name string
+	m    map[string]Flag
+}
+
+func (fc *defaultVisibleFlagCategory) Name() string {
+	return fc.name
+}
+
+func (fc *defaultVisibleFlagCategory) Flags() []VisibleFlag {
+	vfNames := []string{}
+	for flName, fl := range fc.m {
+		if vf, ok := fl.(VisibleFlag); ok {
+			if vf.IsVisible() {
+				vfNames = append(vfNames, flName)
+			}
+		}
+	}
+
+	sort.Strings(vfNames)
+
+	ret := make([]VisibleFlag, len(vfNames))
+	for i, flName := range vfNames {
+		ret[i] = fc.m[flName].(VisibleFlag)
+	}
+
+	return ret
+}

command.go

@@ -38,7 +38,8 @@ type Command struct {
 	// List of child commands
 	Subcommands []*Command
 	// List of flags to parse
-	Flags []Flag
+	Flags          []Flag
+	flagCategories FlagCategories
 	// Treat all flags as normal arguments if true
 	SkipFlagParsing bool
 	// Boolean to hide built-in help command and help flag
@@ -280,6 +281,14 @@ func (c *Command) startApp(ctx *Context) error {
 	return app.RunAsSubcommand(ctx)
 }
 
+// VisibleFlagCategories returns a slice containing all the visible flag categories with the flags they contain
+func (c *Command) VisibleFlagCategories() []VisibleFlagCategory {
+	if c.flagCategories == nil {
+		c.flagCategories = newFlagCategories()
+	}
+	return c.flagCategories.VisibleCategories()
+}
+
 // VisibleFlags returns a slice of the Flags with Hidden=false
 func (c *Command) VisibleFlags() []Flag {
 	return visibleFlags(c.Flags)

flag.go

@@ -132,6 +132,14 @@ type VisibleFlag interface {
 	IsVisible() bool
 }
 
+// CategorizableFlag is an interface that allows us to potentially
+// use a flag in a categorized representation.
+type CategorizableFlag interface {
+	VisibleFlag
+
+	GetCategory() string
+}
+
 func flagSet(name string, flags []Flag) (*flag.FlagSet, error) {
 	set := flag.NewFlagSet(name, flag.ContinueOnError)
 

flag_bool.go

@@ -19,6 +19,7 @@ type BoolFlag struct {
 	DefaultText string
 	Destination *bool
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -52,6 +53,11 @@ func (f *BoolFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *BoolFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *BoolFlag) GetValue() string {

flag_duration.go

@@ -19,6 +19,7 @@ type DurationFlag struct {
 	DefaultText string
 	Destination *time.Duration
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -52,6 +53,11 @@ func (f *DurationFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *DurationFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *DurationFlag) GetValue() string {

flag_float64.go

@@ -19,6 +19,7 @@ type Float64Flag struct {
 	DefaultText string
 	Destination *float64
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -52,6 +53,11 @@ func (f *Float64Flag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *Float64Flag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *Float64Flag) GetValue() string {

flag_float64_slice.go

@@ -87,6 +87,7 @@ type Float64SliceFlag struct {
 	Value       *Float64Slice
 	DefaultText string
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -120,6 +121,11 @@ func (f *Float64SliceFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *Float64SliceFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *Float64SliceFlag) GetValue() string {

flag_generic.go

@@ -24,6 +24,7 @@ type GenericFlag struct {
 	Value       Generic
 	DefaultText string
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -57,6 +58,11 @@ func (f *GenericFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *GenericFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *GenericFlag) GetValue() string {

flag_int.go

@@ -19,6 +19,7 @@ type IntFlag struct {
 	DefaultText string
 	Destination *int
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -52,6 +53,11 @@ func (f *IntFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *IntFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *IntFlag) GetValue() string {

flag_int64.go

@@ -19,6 +19,7 @@ type Int64Flag struct {
 	DefaultText string
 	Destination *int64
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -52,6 +53,11 @@ func (f *Int64Flag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *Int64Flag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *Int64Flag) GetValue() string {

flag_int64_slice.go

@@ -88,6 +88,7 @@ type Int64SliceFlag struct {
 	Value       *Int64Slice
 	DefaultText string
 	HasBeenSet  bool
+	Category    string
 }
 
 // IsSet returns whether or not the flag has been set through env or file
@@ -117,10 +118,15 @@ func (f *Int64SliceFlag) TakesValue() bool {
 }
 
 // GetUsage returns the usage string for the flag
-func (f Int64SliceFlag) GetUsage() string {
+func (f *Int64SliceFlag) GetUsage() string {
 	return f.Usage
 }
 
+// GetCategory returns the category for the flag
+func (f *Int64SliceFlag) GetCategory() string {
+	return f.Category
+}
+
 // GetValue returns the flags value as string representation and an empty
 // string if the flag takes no value at all.
 func (f *Int64SliceFlag) GetValue() string {