feat: provide ability to add version input to commands

Right now, I can't see why this library should provide a way to version
subcommands, so this is just intended to be used for the root program
commands to output some vcs / go version info.

Author: steverusso

builder.go

@@ -11,6 +11,10 @@ var DefaultHelpInput = NewBoolOpt("help").
 	Help("Show this help message and exit.").
 	WithHelpGen(DefaultHelpGenerator)
 
+var DefaultVersionOpt = NewVersionOpt('v', "version", VersionOptConfig{
+	HelpBlurb: "Print the build info version and exit",
+})
+
 var (
 	errMixingPosArgsAndSubcmds = "commands cannot have both positional args and subcommands"
 	errEmptyCmdName            = "empty command name"
@@ -315,6 +319,59 @@ func (in InputInfo) WithHelpGen(hg HelpGenerator) InputInfo {
 	return in
 }
 
+// WithVersioner will set this input's Versioner to the given [Versioner]. This will turn
+// this input into one that, similar to help inputs, causes the parsing to return a
+// [HelpOrVersionRequested] error. See [NewVersionOpt] for a convenient way to create
+// version inputs.
+func (in InputInfo) WithVersioner(ver Versioner) InputInfo {
+	in.Versioner = ver
+	return in
+}
+
+// VersionOptConfig is used to pass customization values to [NewVersionOpt].
+type VersionOptConfig struct {
+	HelpBlurb        string
+	IncludeGoVersion bool
+}
+
+// NewVersionOpt returns a input that will the Versioner field set to a function that
+// outputs information based on the given configuration values. At a minimum, the default
+// version message will always contain the Go module version obtained from
+// [debug.BuildInfo]. Version inputs, similar to help inputs, cause this library's
+// parsing to return a [HelpOrVersionRequested] error. This function will panic if the
+// given long name is empty and the given short name is either 0 or '-'.
+func NewVersionOpt(short byte, long string, cfg VersionOptConfig) InputInfo {
+	if cfg.HelpBlurb == "" {
+		cfg.HelpBlurb = "Print version info and exit."
+	}
+
+	hasShort := short != 0 && short != '-'
+
+	id := long
+	if id == "" {
+		if !hasShort {
+			panic("must provide at least either a long or short name for the version option")
+		}
+		id = string(short)
+	}
+
+	in := NewBoolOpt(id).Help(cfg.HelpBlurb)
+	if hasShort && long != "" {
+		in = in.Short(short)
+	}
+	return in.WithVersioner(func(_ Input) string {
+		bi, ok := debug.ReadBuildInfo()
+		if !ok {
+			Fatal(1, "unable to read build info")
+		}
+		ver := bi.Main.Version + "\n"
+		if cfg.IncludeGoVersion {
+			ver += bi.GoVersion + "\n"
+		}
+		return ver
+	})
+}
+
 func (in *InputInfo) isOption() bool {
 	return in.NameShort != 0 || in.NameLong != ""
 }

builder_test.go

@@ -206,6 +206,17 @@ func TestBuilder(t *testing.T) {
 				"command 'root subcmd' contains duplicate subcommand name 'aa'",
 			},
 		},
+		{
+			name: "using NewVersionOpt with neither a short or long name",
+			builds: []func(){
+				func() { NewCmd("root").Opt(NewVersionOpt(0, "", VersionOptConfig{})) },
+				func() { NewCmd("root").Opt(NewVersionOpt('-', "", VersionOptConfig{})) },
+			},
+			expPanicVals: []any{
+				"must provide at least either a long or short name for the version option",
+				"must provide at least either a long or short name for the version option",
+			},
+		},
 	} {
 		t.Run("prevent "+tt.name, func(t *testing.T) {
 			for i, build := range tt.builds {

cli.go

@@ -121,7 +121,8 @@ type InputInfo struct {
 	ValueName   string
 	ValueParser ValueParser
 
-	HelpGen HelpGenerator
+	HelpGen   HelpGenerator
+	Versioner Versioner
 }
 
 // ValueParser describes any function that takes a string and returns some type or an
@@ -134,6 +135,10 @@ type ValueParser = func(string) (any, error)
 // [DefaultHelpGenerator] for an example.
 type HelpGenerator = func(Input, *CommandInfo) string
 
+// Versioner describes any function that will return a version string based on
+// the [Input] that triggered it. See [DefaultHelpGenerator] for an example.
+type Versioner = func(Input) string
+
 // Command is a parsed command structure.
 type Command struct {
 	Name    string
@@ -257,8 +262,8 @@ func (in CommandInfo) ParseOrExit() *Command {
 func (in CommandInfo) ParseTheseOrExit(args ...string) *Command {
 	c, err := in.ParseThese(args...)
 	if err != nil {
-		if e, ok := err.(HelpRequestError); ok {
-			fmt.Print(e.HelpMsg)
+		if e, ok := err.(HelpOrVersionRequested); ok {
+			fmt.Print(e.Msg)
 			os.Exit(0)
 		} else {
 			Fatal(1, err)
@@ -285,12 +290,12 @@ func (in *CommandInfo) ParseThese(args ...string) (*Command, error) {
 	return c, err
 }
 
-type HelpRequestError struct {
-	HelpMsg string
+type HelpOrVersionRequested struct {
+	Msg string
 }
 
-func (h HelpRequestError) Error() string {
-	return h.HelpMsg
+func (h HelpOrVersionRequested) Error() string {
+	return h.Msg
 }
 
 func lookupOptionByShortName(in *CommandInfo, shortName byte) *InputInfo {
@@ -425,8 +430,13 @@ func parse(c *CommandInfo, p *Command, args []string) error {
 				}
 
 				if optInfo.HelpGen != nil {
-					return HelpRequestError{
-						HelpMsg: optInfo.HelpGen(pi, c),
+					return HelpOrVersionRequested{
+						Msg: optInfo.HelpGen(pi, c),
+					}
+				}
+				if optInfo.Versioner != nil {
+					return HelpOrVersionRequested{
+						Msg: optInfo.Versioner(pi),
 					}
 				}
 
@@ -493,8 +503,13 @@ func parse(c *CommandInfo, p *Command, args []string) error {
 		}
 
 		if optInfo.HelpGen != nil {
-			return HelpRequestError{
-				HelpMsg: optInfo.HelpGen(pi, c),
+			return HelpOrVersionRequested{
+				Msg: optInfo.HelpGen(pi, c),
+			}
+		}
+		if optInfo.Versioner != nil {
+			return HelpOrVersionRequested{
+				Msg: optInfo.Versioner(pi),
 			}
 		}
 
@@ -586,7 +601,7 @@ func parse(c *CommandInfo, p *Command, args []string) error {
 	// as no subcommand has requested a help message.
 	errFromSubcmd := parse(subcmdInfo, p.Subcmd, rest[1:])
 	if errMissingOpts != nil {
-		if _, ok := errFromSubcmd.(HelpRequestError); !ok {
+		if _, ok := errFromSubcmd.(HelpOrVersionRequested); !ok {
 			return errMissingOpts
 		}
 	}

cli_test.go

@@ -388,8 +388,8 @@ func TestParsing(t *testing.T) {
 				{
 					Case: ttCase(),
 					args: []string{"one", "-h"},
-					expErr: HelpRequestError{
-						HelpMsg: "cmd one\n\nusage:\n  one [options]\n\noptions:\n      --cc  <arg>   (required)\n  -h, --help        Show this help message and exit.\n",
+					expErr: HelpOrVersionRequested{
+						Msg: "cmd one\n\nusage:\n  one [options]\n\noptions:\n      --cc  <arg>   (required)\n  -h, --help        Show this help message and exit.\n",
 					},
 				},
 				{
@@ -524,6 +524,91 @@ func TestParsing(t *testing.T) {
 				},
 			},
 		},
+		// versioning (on just the top level for now)
+		// using the builder method for a custom versioner
+		{
+			name: "versioning",
+			cmd: NewCmd("cmd").
+				Opt(NewOpt("a")).
+				Opt(NewBoolOpt("b")).
+				Opt(NewBoolOpt("v").WithVersioner(func(_ Input) string { return "version-string" })),
+			variations: []testInputOutput{
+				{
+					Case: ttCase(),
+					args: []string{"-v"},
+					expErr: HelpOrVersionRequested{
+						Msg: "version-string",
+					},
+				},
+				{
+					Case: ttCase(),
+					args: []string{"-a", "A"},
+					expected: Command{
+						Inputs: []Input{
+							{ID: "a", From: ParsedFrom{Opt: "a"}, RawValue: "A", Value: "A"},
+						},
+					},
+				},
+				{
+					Case: ttCase(),
+					args: []string{"-bv"},
+					expErr: HelpOrVersionRequested{
+						Msg: "version-string",
+					},
+				},
+			},
+		},
+		// versioning (on just the top level for now)
+		// using the constructor for a version option
+		{
+			name: "versioning",
+			cmd:  NewCmd("cmd").Opt(DefaultVersionOpt),
+			variations: []testInputOutput{
+				{
+					Case:   ttCase(),
+					args:   []string{"--version"},
+					expErr: HelpOrVersionRequested{Msg: "(devel)\n"},
+				},
+				{
+					Case:   ttCase(),
+					args:   []string{"-v"},
+					expErr: HelpOrVersionRequested{Msg: "(devel)\n"},
+				},
+			},
+		},
+		// versioning (on just the top level for now)
+		// using the constructor for a version option but leaving out a short name
+		{
+			name: "versioning",
+			cmd:  NewCmd("cmd").Opt(NewVersionOpt(0, "version", VersionOptConfig{})),
+			variations: []testInputOutput{
+				{
+					Case:   ttCase(),
+					args:   []string{"--version"},
+					expErr: HelpOrVersionRequested{Msg: "(devel)\n"},
+				},
+				{Case: ttCase(), args: []string{"-v"}, expErr: UnknownOptionError{Name: "-v"}},
+				{Case: ttCase(), args: []string{"-V"}, expErr: UnknownOptionError{Name: "-V"}},
+			},
+		},
+		// versioning (on just the top level for now)
+		// using the constructor for a version option but leaving out a long name
+		{
+			name: "versioning",
+			cmd:  NewCmd("cmd").Opt(NewVersionOpt('Z', "", VersionOptConfig{})),
+			variations: []testInputOutput{
+				{
+					Case:   ttCase(),
+					args:   []string{"-Z"},
+					expErr: HelpOrVersionRequested{Msg: "(devel)\n"},
+				},
+				{
+					Case:   ttCase(),
+					args:   []string{"--version"},
+					expErr: UnknownOptionError{Name: "--version"},
+				},
+			},
+		},
 	} {
 		for tioIdx, tio := range tt.variations {
 			t.Run(fmt.Sprintf("%s %d", tt.name, tioIdx), func(t *testing.T) {