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,16 @@ func (a *App) Setup() {
 		if c.HelpName == "" {
 			c.HelpName = fmt.Sprintf("%s %s", a.HelpName, c.Name)
 		}
+
+		fc := FlagCategories{}
+		for _, fl := range c.Flags {
+			if cf, ok := fl.(CategorizableFlag); ok {
+				fc = fc.AddFlag(cf.GetCategory(), cf)
+			}
+		}
+
+		sort.Sort(fc)
+		c.FlagCategories = fc
 		newCommands = append(newCommands, c)
 	}
 	a.Commands = newCommands
@@ -205,6 +217,14 @@ func (a *App) Setup() {
 	}
 	sort.Sort(a.categories.(*commandCategories))
 
+	a.flagCategories = FlagCategories{}
+	for _, fl := range a.Flags {
+		if cf, ok := fl.(CategorizableFlag); ok {
+			a.flagCategories.AddFlag(cf.GetCategory(), cf)
+		}
+	}
+	sort.Sort(a.flagCategories)
+
 	if a.Metadata == nil {
 		a.Metadata = make(map[string]interface{})
 	}
@@ -481,6 +501,11 @@ func (a *App) VisibleCommands() []*Command {
 	return ret
 }
 
+// Categories returns a slice containing all the categories with the commands they contain
+func (a *App) VisibleFlagCategories() FlagCategories {
+	return a.flagCategories
+}
+
 // VisibleFlags returns a slice of the Flags with Hidden=false
 func (a *App) VisibleFlags() []Flag {
 	return visibleFlags(a.Flags)

app_test.go

@@ -1789,20 +1789,23 @@ func TestApp_VisibleCategories(t *testing.T) {
 		HideHelp: true,
 		Commands: []*Command{
 			{
-				Name:     "command1",
-				Category: "1",
-				HelpName: "foo command1",
-				Hidden:   true,
+				Name:           "command1",
+				Category:       "1",
+				HelpName:       "foo command1",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command2",
-				Category: "2",
-				HelpName: "foo command2",
+				Name:           "command2",
+				Category:       "2",
+				HelpName:       "foo command2",
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command3",
-				Category: "3",
-				HelpName: "foo command3",
+				Name:           "command3",
+				Category:       "3",
+				HelpName:       "foo command3",
+				FlagCategories: FlagCategories{},
 			},
 		},
 	}
@@ -1830,21 +1833,24 @@ func TestApp_VisibleCategories(t *testing.T) {
 		HideHelp: true,
 		Commands: []*Command{
 			{
-				Name:     "command1",
-				Category: "1",
-				HelpName: "foo command1",
-				Hidden:   true,
+				Name:           "command1",
+				Category:       "1",
+				HelpName:       "foo command1",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command2",
-				Category: "2",
-				HelpName: "foo command2",
-				Hidden:   true,
+				Name:           "command2",
+				Category:       "2",
+				HelpName:       "foo command2",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command3",
-				Category: "3",
-				HelpName: "foo command3",
+				Name:           "command3",
+				Category:       "3",
+				HelpName:       "foo command3",
+				FlagCategories: FlagCategories{},
 			},
 		},
 	}
@@ -1866,22 +1872,25 @@ func TestApp_VisibleCategories(t *testing.T) {
 		HideHelp: true,
 		Commands: []*Command{
 			{
-				Name:     "command1",
-				Category: "1",
-				HelpName: "foo command1",
-				Hidden:   true,
+				Name:           "command1",
+				Category:       "1",
+				HelpName:       "foo command1",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command2",
-				Category: "2",
-				HelpName: "foo command2",
-				Hidden:   true,
+				Name:           "command2",
+				Category:       "2",
+				HelpName:       "foo command2",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 			{
-				Name:     "command3",
-				Category: "3",
-				HelpName: "foo command3",
-				Hidden:   true,
+				Name:           "command3",
+				Category:       "3",
+				HelpName:       "foo command3",
+				Hidden:         true,
+				FlagCategories: FlagCategories{},
 			},
 		},
 	}
@@ -1890,6 +1899,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

@@ -77,3 +77,48 @@ func (c *commandCategory) VisibleCommands() []*Command {
 	}
 	return ret
 }
+
+// FlagCategories is a slice of *FlagCategory.
+type FlagCategories []*FlagCategory
+
+// FlagCategory is a category containing commands.
+type FlagCategory struct {
+	Name  string
+	Flags []Flag
+}
+
+func (f FlagCategories) Less(i, j int) bool {
+	return lexicographicLess(f[i].Name, f[j].Name)
+}
+
+func (f FlagCategories) Len() int {
+	return len(f)
+}
+
+func (f FlagCategories) Swap(i, j int) {
+	f[i], f[j] = f[j], f[i]
+}
+
+// AddFlags adds a command to a category.
+func (f FlagCategories) AddFlag(category string, flag Flag) FlagCategories {
+	for _, flagCategory := range f {
+		if flagCategory.Name == category {
+			flagCategory.Flags = append(flagCategory.Flags, flag)
+			return f
+		}
+	}
+	return append(f, &FlagCategory{Name: category, Flags: []Flag{flag}})
+}
+
+// VisibleFlags returns a slice of the Flags with Hidden=false
+func (c *FlagCategory) VisibleFlags() []VisibleFlag {
+	ret := []VisibleFlag{}
+	for _, fl := range c.Flags {
+		if vf, ok := fl.(VisibleFlag); ok {
+			if vf.IsVisible() {
+				ret = append(ret, vf)
+			}
+		}
+	}
+	return ret
+}

command.go

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

flag.go

@@ -133,6 +133,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

@@ -85,6 +85,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
@@ -118,6 +119,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 {