feat: allow for subcommand to be optional

Author: steverusso

builder.go

@@ -148,6 +148,16 @@ func (c CommandInfo) Usage(lines ...string) CommandInfo {
 	return c
 }
 
+// SubcmdOptional marks this CommandInfo as not requiring one of its subcommands to be
+// provided. By default, when parsing against a CommandInfo that has subcommands, an error
+// will be returned if there is no subcommand provided. However, calling this method will
+// change it so there will not be a parsing error if a subcommand argument is absent, and
+// the parsed subcommand field Subcmd on [Command] will be nil.
+func (c CommandInfo) SubcmdOptional() CommandInfo {
+	c.IsSubcmdOptional = true
+	return c
+}
+
 // Opt adds o as an option to this CommandInfo. This method will panic if the option has
 // neither a long or short name set (this should never happen when using the builder
 // pattern starting with the [NewOpt] function or its siblings).

cli.go

@@ -103,6 +103,8 @@ type CommandInfo struct {
 	Args      []InputInfo
 	Subcmds   []CommandInfo
 
+	IsSubcmdOptional bool
+
 	isPrepped bool
 }
 
@@ -578,22 +580,25 @@ func parse(c *CommandInfo, p *Command, args []string) error {
 	}
 
 	if len(rest) < 1 {
+		if c.IsSubcmdOptional {
+			return nil
+		}
 		return ErrNoSubcmd
 	}
-	p.Subcmd = &Command{
-		Inputs: make([]Input, 0, len(rest)),
-		Name:   rest[0],
-	}
 
 	var subcmdInfo *CommandInfo
 	for i := range c.Subcmds {
-		if c.Subcmds[i].Name == p.Subcmd.Name {
+		if c.Subcmds[i].Name == rest[0] {
 			subcmdInfo = &c.Subcmds[i]
 			break
 		}
 	}
 	if subcmdInfo == nil {
-		return UnknownSubcmdError{Name: p.Subcmd.Name}
+		return UnknownSubcmdError{Name: rest[0]}
+	}
+	p.Subcmd = &Command{
+		Inputs: make([]Input, 0, len(rest)),
+		Name:   rest[0],
 	}
 
 	// If we have an error from parsing this command (from above), only return it so long

examples_test.go

@@ -12,6 +12,34 @@ import (
 	"github.com/steverusso/cli"
 )
 
+func ExampleCommandInfo_SubcmdOptional() {
+	// Simple command-with-subcommand structure. Parsing the top-level
+	// command will return an error if a subcommand isn't provided.
+	scReq := cli.New("example").
+		Help("an example program").
+		Subcmd(cli.NewCmd("cmd1"))
+
+	// Same command structure as above, except parsing will
+	// NOT return an error if a subcommand isn't provided.
+	scOpt := cli.New("example").
+		Help("an example program").
+		Subcmd(cli.NewCmd("cmd1")).
+		SubcmdOptional()
+
+	c, _ := scReq.ParseThese("cmd1")
+	fmt.Printf("have subcommand %q\n", c.Subcmd.Name)
+
+	_, err := scReq.ParseThese()
+	fmt.Println("err:", err)
+
+	c, err = scOpt.ParseThese()
+	fmt.Printf("err: %v, c.Subcmd: %v\n", err, c.Subcmd) // using c.Subcmd.Name here would panic
+	// Output:
+	// have subcommand "cmd1"
+	// err: missing subcommand
+	// err: <nil>, c.Subcmd: <nil>
+}
+
 func ExampleInputInfo_Default() {
 	in := cli.New().Opt(cli.NewIntOpt("flag").Default("1234"))