Merge pull request #292 from zeroshade/allow-hidden

feat: allow hiding a subcommand using "-" for help

Author: alexflint

doc.go

@@ -33,7 +33,8 @@
 // (e.g. `./example -d`), and any tag string that starts with two hyphens is the long
 // form for the argument (instead of the field name).
 //
-// Other valid tag strings are `positional` and `required`.
+// Other valid tag strings are `positional`, `required`, and `hidden`. Using `hidden` will
+// exclude the field from help text and usage messages.
 //
 // Fields can be excluded from processing with `arg:"-"`.
 package arg

parse.go

@@ -53,6 +53,7 @@ type spec struct {
 	positional    bool                // if true, this option will be looked for in the positional flags
 	separate      bool                // if true, each slice and map entry will have its own --flag
 	help          string              // the help text for this option
+	hidden        bool                // if true, this option will be hidden from help text
 	env           string              // the name of the environment variable for this option, or empty for none
 	defaultValue  reflect.Value       // default value for this option
 	defaultString string              // default value for this option, in string form to be displayed in help text
@@ -68,6 +69,7 @@ type command struct {
 	specs       []*spec
 	subcommands []*command
 	parent      *command
+	hidden      bool
 }
 
 // ErrHelp indicates that the builtin -h or --help were provided
@@ -386,6 +388,8 @@ func cmdFromStruct(name string, dest path, t reflect.Type, envPrefix string) (*c
 				spec.separate = true
 			case key == "help": // deprecated
 				spec.help = value
+			case key == "hidden":
+				spec.hidden = true
 			case key == "env":
 				// Use override name if provided
 				if value != "" {
@@ -436,6 +440,9 @@ func cmdFromStruct(name string, dest path, t reflect.Type, envPrefix string) (*c
 
 		// if this is a subcommand then we've done everything we need to do
 		if isSubcommand {
+			if spec.hidden {
+				cmd.subcommands[len(cmd.subcommands)-1].hidden = true
+			}
 			return false
 		}
 

usage.go

@@ -49,6 +49,9 @@ func (p *Parser) WriteUsageForSubcommand(w io.Writer, subcommand ...string) erro
 
 	var positionals, longOptions, shortOptions []*spec
 	for _, spec := range cmd.specs {
+		if spec.hidden {
+			continue
+		}
 		switch {
 		case spec.positional:
 			positionals = append(positionals, spec)
@@ -199,6 +202,10 @@ func (p *Parser) WriteHelpForSubcommand(w io.Writer, subcommand ...string) error
 	var positionals, longOptions, shortOptions, envOnlyOptions []*spec
 	var hasVersionOption bool
 	for _, spec := range cmd.specs {
+		if spec.hidden {
+			continue
+		}
+
 		switch {
 		case spec.positional:
 			positionals = append(positionals, spec)
@@ -293,6 +300,11 @@ func (p *Parser) WriteHelpForSubcommand(w io.Writer, subcommand ...string) error
 	if len(cmd.subcommands) > 0 {
 		fmt.Fprint(w, "\nCommands:\n")
 		for _, subcmd := range cmd.subcommands {
+			if subcmd.hidden {
+				// skip this subcommand in the help message
+				continue
+			}
+
 			names := append([]string{subcmd.name}, subcmd.aliases...)
 			print(w, strings.Join(names, ", "), subcmd.help)
 		}

usage_test.go

@@ -1016,6 +1016,31 @@ Commands:
 	assert.Equal(t, expectedHelp[1:], help.String())
 }
 
+func TestHelpSkipsSubcommandHelpDash(t *testing.T) {
+	expectedHelp := `
+Usage: example <command> [<args>]
+
+Options:
+  --help, -h             display this help and exit
+
+Commands:
+  remove, rm, r          remove something from somewhere
+  halt, stop             stop now
+`
+
+	var args struct {
+		Remove *struct{} `arg:"subcommand:remove|rm|r" help:"remove something from somewhere"`
+		Simple *struct{} `arg:"subcommand,hidden" help:"simple hidden subcommand"`
+		Stop   *struct{} `arg:"subcommand:halt|stop" help:"stop now"`
+	}
+	p, err := NewParser(Config{Program: "example"}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+}
+
 func TestHelpShowsPositionalWithDefault(t *testing.T) {
 	expectedHelp := `
 Usage: example [FOO]
@@ -1039,6 +1064,30 @@ Options:
 	assert.Equal(t, expectedHelp[1:], help.String())
 }
 
+func TestHelpShowsPositionalWithDefaultSkipHidden(t *testing.T) {
+	expectedHelp := `
+Usage: example [FOO]
+
+Positional arguments:
+  FOO                    this is a positional with a default [default: bar]
+
+Options:
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		Foo string `arg:"positional" default:"bar" help:"this is a positional with a default"`
+		Bar string `arg:"positional,hidden" default:"baz" help:"this is a hidden positional with a default"`
+	}
+
+	p, err := NewParser(Config{Program: "example"}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+}
+
 func TestHelpShowsPositionalWithEnv(t *testing.T) {
 	expectedHelp := `
 Usage: example [FOO]