chore: make usage template and writer configurable via exec options

Drop the package variables for configuring the usage render template and
output writer. Instead, make this configurable via exec options avoid
avoid package statefulness.

Author: brandon1024

execute.go

@@ -12,14 +12,12 @@ import (
 	"github.com/brandon1024/cmder/getopt"
 )
 
-var (
-	// ErrIllegalCommandConfiguration is an error returned when a [Command] provided to [Execute] is illegal.
-	ErrIllegalCommandConfiguration = errors.New("cmder: illegal command configuration")
+// ErrIllegalCommandConfiguration is an error returned when a [Command] provided to [Execute] is illegal.
+var ErrIllegalCommandConfiguration = errors.New("cmder: illegal command configuration")
 
-	// ErrEnvironmentBindFailure is an error returned when [Execute] failed to update flag value from environment
-	// variable (see [WithEnvironmentBinding]).
-	ErrEnvironmentBindFailure = errors.New("cmder: failed to update flag from environment variable")
-)
+// ErrEnvironmentBindFailure is an error returned when [Execute] failed to update a flag value from environment
+// variables (see [WithEnvironmentBinding]).
+var ErrEnvironmentBindFailure = errors.New("cmder: failed to update flag from environment variable")
 
 // Execute runs a [Command].
 //
@@ -73,8 +71,8 @@ var (
 // # Usage and Help Texts
 //
 // Whenever the user provides the '-h' or '--help' flag at the command line, [Execute] will display command usage and
-// exit. The format of the help text can be adjusted by configuring [UsageTemplate]. By default, usage information will
-// be written to stderr, but this can be adjusted by setting [UsageOutputWriter].
+// exit. The format of the help text can be adjusted with [WithUsageTemplate]. By default, usage information will
+// be written to stderr, but this can be adjusted by setting [WithUsageOutput].
 //
 // If a command's [Run] routine returns [ErrShowUsage] (or an error wrapping [ErrShowUsage]), [Execute] will render
 // help text and exit with status 2.
@@ -86,7 +84,9 @@ func Execute(ctx context.Context, cmd Command, op ...ExecuteOption) error {
 
 	// prepare executor options
 	ops := &ExecuteOptions{
-		args: os.Args[1:],
+		args:          os.Args[1:],
+		usageTemplate: CobraUsageTemplate,
+		usageWriter:   os.Stderr,
 	}
 	for _, f := range op {
 		f(ops)
@@ -100,14 +100,14 @@ func Execute(ctx context.Context, cmd Command, op ...ExecuteOption) error {
 
 	// if help was requested, display and exit
 	if cmd, ok := helpRequested(stack); ok {
-		return usage(*cmd)
+		return usage(*cmd, ops)
 	}
 
-	return execute(ctx, stack)
+	return execute(ctx, stack, ops)
 }
 
 // execute traverses the command stack recursively executing the lifecycle routines at each level.
-func execute(ctx context.Context, stack []command) error {
+func execute(ctx context.Context, stack []command, ops *ExecuteOptions) error {
 	if len(stack) == 0 {
 		return nil
 	}
@@ -122,22 +122,22 @@ func execute(ctx context.Context, stack []command) error {
 	)
 
 	// run init (if applicable)
-	if err := this.onInit(ctx); err != nil {
+	if err := this.onInit(ctx, ops); err != nil {
 		return err
 	}
 
 	// if this is a leaf, run, otherwise recurse
 	if len(stack) == 1 {
-		err = this.run(ctx)
+		err = this.run(ctx, ops)
 	} else {
-		err = execute(ctx, stack[1:])
+		err = execute(ctx, stack[1:], ops)
 	}
 	if err != nil {
 		return err
 	}
 
 	// run destroy (if applicable)
-	if err := this.onDestroy(ctx); err != nil {
+	if err := this.onDestroy(ctx, ops); err != nil {
 		return err
 	}
 
@@ -154,42 +154,42 @@ type command struct {
 }
 
 // onInit calls the [RunnableLifecycle] init routine if present on c.
-func (c command) onInit(ctx context.Context) error {
+func (c command) onInit(ctx context.Context, ops *ExecuteOptions) error {
 	var err error
 
 	if cmd, ok := c.Command.(RunnableLifecycle); ok {
 		err = cmd.Initialize(ctx, c.args)
 	}
 
 	if errors.Is(err, ErrShowUsage) {
-		_ = usage(c)
+		_ = usage(c, ops)
 		os.Exit(2)
 	}
 
 	return err
 }
 
 // run calls the [Runnable] run routine of c.
-func (c command) run(ctx context.Context) error {
+func (c command) run(ctx context.Context, ops *ExecuteOptions) error {
 	err := c.Run(ctx, c.args)
 	if errors.Is(err, ErrShowUsage) {
-		_ = usage(c)
+		_ = usage(c, ops)
 		os.Exit(2)
 	}
 
 	return err
 }
 
 // onDestroy calls the [RunnableLifecycle] destroy routine if present on c.
-func (c command) onDestroy(ctx context.Context) error {
+func (c command) onDestroy(ctx context.Context, ops *ExecuteOptions) error {
 	var err error
 
 	if cmd, ok := c.Command.(RunnableLifecycle); ok {
 		err = cmd.Destroy(ctx, c.args)
 	}
 
 	if errors.Is(err, ErrShowUsage) {
-		_ = usage(c)
+		_ = usage(c, ops)
 		os.Exit(2)
 	}
 

options.go

@@ -1,12 +1,16 @@
 package cmder
 
+import "io"
+
 // ExecuteOptions configure the behaviour of [Execute].
 type ExecuteOptions struct {
 	args          []string
 	nativeFlags   bool
 	bindEnv       bool
 	bindEnvPrefix string
 	interspersed  bool
+	usageTemplate string
+	usageWriter   io.Writer
 }
 
 // ExecuteOption is a single option passed to [Execute].
@@ -72,3 +76,22 @@ func WithInterspersedArgs() ExecuteOption {
 		ops.interspersed = true
 	}
 }
+
+// WithUsageTemplate is used to provide an alternate template for rendering command usage help text. The template is
+// rendered by the standard [text/template] package. This is particularly useful for applications which prefer to format
+// command usage information differently than the cmder defaults.
+//
+// By default, the [CobraUsageTemplate] template is used.
+func WithUsageTemplate(tmpl string) ExecuteOption {
+	return func(ops *ExecuteOptions) {
+		ops.usageTemplate = tmpl
+	}
+}
+
+// WithUsageOutput is used to provide an alternate [io.Writer] to write rendered command usage help text. By default,
+// [os.Stderr] is used.
+func WithUsageOutput(output io.Writer) ExecuteOption {
+	return func(ops *ExecuteOptions) {
+		ops.usageWriter = output
+	}
+}

usage.go

@@ -4,8 +4,6 @@ import (
 	"bytes"
 	"cmp"
 	"flag"
-	"io"
-	"os"
 	"slices"
 	"strings"
 	"text/template"
@@ -85,19 +83,12 @@ Examples:
 const StdFlagUsageTemplate = `usage: {{ .Command.UsageLine }}
 {{ flagusage . }}`
 
-// UsageTemplate is the text template for rendering command usage information.
-var UsageTemplate = CobraUsageTemplate
-
-// UsageOutputWriter is the default writer for command usage information. Standard error is recommended, but you can
-// override this if needed (particularly useful in tests).
-var UsageOutputWriter io.Writer = os.Stderr
-
-// ErrShowUsage instructs cmder to render usage and exit.
+// ErrShowUsage instructs cmder to render usage and exit (status 2).
 var ErrShowUsage = flag.ErrHelp
 
 // usage renders usage text for a [Command] using the default template [UsageTemplate]. Output is written to
 // [UsageOutputWriter].
-func usage(cmd command) error {
+func usage(cmd command, ops *ExecuteOptions) error {
 	tmpl, err := template.New("usage").Funcs(template.FuncMap{
 		"commands":  subcommands,
 		"flags":     flags,
@@ -111,12 +102,12 @@ func usage(cmd command) error {
 		"contains":  strings.Contains,
 		"trim":      strings.TrimSpace,
 		"lines":     strings.Lines,
-	}).Parse(UsageTemplate)
+	}).Parse(ops.usageTemplate)
 	if err != nil {
 		return err
 	}
 
-	return tmpl.Execute(UsageOutputWriter, cmd)
+	return tmpl.Execute(ops.usageWriter, cmd)
 }
 
 // subcommands returns a map of (visible) child subcommands for cmd.

usage_test.go

@@ -3,7 +3,6 @@ package cmder
 import (
 	"bytes"
 	"flag"
-	"os"
 	"testing"
 	"time"
 
@@ -169,18 +168,14 @@ func TestUsage(t *testing.T) {
 	cmd.fs.String("web.telemetry-path", "/metrics", "path under which to expose metrics")
 	cmd.fs.Bool("web.disable-exporter-metrics", false, "exclude metrics about the exporter itself (go_*)")
 
-	t.Cleanup(func() {
-		UsageOutputWriter = os.Stderr
-		UsageTemplate = CobraUsageTemplate
-	})
-
 	t.Run("CobraUsageTemplate", func(t *testing.T) {
 		t.Run("should render correctly", func(t *testing.T) {
 			var buf bytes.Buffer
-			UsageOutputWriter = &buf
-			UsageTemplate = CobraUsageTemplate
 
-			err := usage(cmd)
+			err := usage(cmd, &ExecuteOptions{
+				usageTemplate: CobraUsageTemplate,
+				usageWriter:   &buf,
+			})
 			assert(t, nilerr(err))
 
 			if diff := cmp.Diff(ExpectedCobraUsageTemplate, buf.String()); diff != "" {
@@ -201,10 +196,11 @@ func TestUsage(t *testing.T) {
 			})
 
 			var buf bytes.Buffer
-			UsageOutputWriter = &buf
-			UsageTemplate = CobraUsageTemplate
 
-			err := usage(cmd)
+			err := usage(cmd, &ExecuteOptions{
+				usageTemplate: CobraUsageTemplate,
+				usageWriter:   &buf,
+			})
 			assert(t, nilerr(err))
 
 			if diff := cmp.Diff(ExpectedCobraUsageTemplate, buf.String()); diff != "" {
@@ -216,10 +212,11 @@ func TestUsage(t *testing.T) {
 	t.Run("StdFlagUsageTemplate", func(t *testing.T) {
 		t.Run("should render correctly", func(t *testing.T) {
 			var buf bytes.Buffer
-			UsageOutputWriter = &buf
-			UsageTemplate = StdFlagUsageTemplate
 
-			err := usage(cmd)
+			err := usage(cmd, &ExecuteOptions{
+				usageTemplate: StdFlagUsageTemplate,
+				usageWriter:   &buf,
+			})
 			assert(t, nilerr(err))
 
 			if diff := cmp.Diff(ExpectedStdFlagUsageTemplate, buf.String()); diff != "" {