chore: render usage and help texts differently

Prior to this revision, -h and --help flags rendered complete help text.
This revision adjusts this slightly, now differentiating between usage
text ('-h') and longer help text ('--help'). The usage text offers a
short command summary, and the help text offers longer doc-style text.

With this, a few adjustments were made to the usage machinery and the
relevant execute options.

Usage/help text is now rendered to stdout by default. This makes it
easier to pass the output through a paging program like 'less' or
'more'.

The custom flag value types in the getopt package now feature short
constructor functions (e.g. getopt.Time, getopt.Map). Examples have been
updated.

The 'http' example has been updated with improved flag descriptions.

Author: brandon1024

example_exec_option_bind_env_test.go

@@ -10,8 +10,8 @@ import (
 )
 
 func ExampleWithEnvironmentBinding() {
-	_ = os.Setenv("BINDENV_SHOW_FORMAT", "overidden-by-flag")
-	_ = os.Setenv("BINDENV_SHOW_PAGECOUNT", "20")
+	os.Setenv("BINDENV_SHOW_FORMAT", "overidden-by-flag")
+	os.Setenv("BINDENV_SHOW_PAGECOUNT", "20")
 
 	args := []string{"show", "--format=pretty"}
 

examples/http/main.go

@@ -23,7 +23,7 @@ func main() {
 	err := cmder.Execute(ctx, &ServerCommand{})
 	cancel()
 
-	if err != nil {
+	if err != nil && !errors.Is(err, cmder.ErrShowUsage) && !errors.Is(err, cmder.ErrShowUsage) {
 		fmt.Printf("unexpected error occurred: %v\n", err)
 		os.Exit(1)
 	}
@@ -91,13 +91,20 @@ type ServerCommand struct {
 }
 
 func (c *ServerCommand) InitializeFlags(fs *flag.FlagSet) {
-	fs.StringVar(&c.addr, "http.bind-addr", ":8080", "bind address for the web server")
-	fs.DurationVar(&c.readTimeout, "http.read-timeout", time.Duration(0), "read timeout for requests")
-	fs.DurationVar(&c.writeTimeout, "http.write-timeout", time.Duration(0), "write timeout for responses")
-	fs.IntVar(&c.maxHeaderBytes, "http.max-header-size", http.DefaultMaxHeaderBytes, "max permitted size of the headers in a request")
-	fs.Int64Var(&c.maxBodySize, "http.max-body-size", 1<<26, "max permitted size of the headers in a request")
-	fs.StringVar(&c.basicAuth, "http.auth-basic", "", "basic auth credentials (in format user:pass)")
-	fs.BoolVar(&c.noAuth, "http.no-auth", false, "disable basic auth")
+	fs.StringVar(&c.addr, "http.bind-addr", ":8080",
+		"Sets the `address:port` on which the server will accept requests. The address may be an IPv4 (e.g. 127.0.0.1) or IPv6 (e.g. [2001:db8::1]) address. The address may be empty, in which case the local system is implied (0.0.0.0). If the port is empty or '0' (e.g. ':0'), a port number is automatically chosen.")
+	fs.DurationVar(&c.readTimeout, "http.read-timeout", time.Duration(0),
+		"Configures the maximum duration for reading the entire request, including the body (e.g. 10s). Negative or zero (e.g. 0s) disables the timeout.")
+	fs.DurationVar(&c.writeTimeout, "http.write-timeout", time.Duration(0),
+		"Configures the maximum duration for writing a client response. Negative or zero (e.g. 0s) disables the timeout.")
+	fs.IntVar(&c.maxHeaderBytes, "http.max-header-size", http.DefaultMaxHeaderBytes,
+		"Set the maximum header size, in bytes. Negative or zero disables the limit.")
+	fs.Int64Var(&c.maxBodySize, "http.max-body-size", 1<<26,
+		"Set the maximum request body size, in bytes. Negative or zero disables the limit.")
+	fs.StringVar(&c.basicAuth, "http.auth-basic", "",
+		"Configure basic auth credentials with format `user:pass`.")
+	fs.BoolVar(&c.noAuth, "http.no-auth", false,
+		"Disable basic auth, making the server available to all.")
 }
 
 func (c *ServerCommand) Initialize(ctx context.Context, args []string) error {

execute.go

@@ -70,13 +70,13 @@ var ErrEnvironmentBindFailure = errors.New("cmder: failed to update flag from en
 //
 // # Usage and Help Texts
 //
-// Whenever the user provides the '-h' or '--help' flag at the command line and the command doesn't register custom help
-// flags, Execute will display command usage and return [ErrShowUsage]. 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].
+// Unless explicitly overridden by the command, the '-h' flag instructs Execute to render command usage information to
+// stdout and return [ErrShowUsage]. The default usage text includes a usage synopsis, subcommands and flags. The
+// format of the usage text can be adjusted (see [WithUsageTemplate]). Returning [ErrShowUsage] from a command's
+// Initialize or Run routines will also instruct Execute to render usage.
 //
-// If a command's Run routine returns [ErrShowUsage] (or an error wrapping [ErrShowUsage]), Execute will render
-// help text and return the error.
+// Likewise, the '--help' flag instructs Execute to render extended help usage information to stdout, returning
+// [ErrShowHelp]. The format may be adjusted (see [WithHelpTemplate]).
 func Execute(ctx context.Context, cmd Command, op ...ExecuteOption) error {
 	// do some checks
 	if cmd == nil {
@@ -86,8 +86,9 @@ func Execute(ctx context.Context, cmd Command, op ...ExecuteOption) error {
 	// prepare executor options
 	ops := &ExecuteOptions{
 		args:          os.Args[1:],
-		usageTemplate: CobraUsageTemplate,
-		usageWriter:   os.Stderr,
+		usageTemplate: DefaultUsageTemplate,
+		helpTemplate:  DefaultHelpTemplate,
+		outputWriter:  os.Stdout,
 	}
 	for _, f := range op {
 		f(ops)
@@ -144,18 +145,22 @@ func execute(ctx context.Context, stack []command, ops *ExecuteOptions) error {
 type command struct {
 	Command
 
-	fs       *flag.FlagSet
-	args     []string
-	showHelp bool
+	fs        *flag.FlagSet
+	args      []string
+	showUsage bool
+	showHelp  bool
 }
 
 // onInit calls the [Initializer] init routine if present on c.
 func (c command) onInit(ctx context.Context, ops *ExecuteOptions) error {
 	var err error
 
-	if c.showHelp {
+	if c.showUsage {
 		return errors.Join(ErrShowUsage, usage(c, ops))
 	}
+	if c.showHelp {
+		return errors.Join(ErrShowUsage, help(c, ops))
+	}
 
 	if cmd, ok := c.Command.(Initializer); ok {
 		err = cmd.Initialize(ctx, c.args)
@@ -170,6 +175,13 @@ func (c command) onInit(ctx context.Context, ops *ExecuteOptions) error {
 
 // run calls the [Runnable] run routine of c.
 func (c command) run(ctx context.Context, ops *ExecuteOptions) error {
+	if c.showUsage {
+		return errors.Join(ErrShowUsage, usage(c, ops))
+	}
+	if c.showHelp {
+		return errors.Join(ErrShowUsage, help(c, ops))
+	}
+
 	err := c.Run(ctx, c.args)
 	if errors.Is(err, ErrShowUsage) {
 		return errors.Join(err, usage(c, ops))
@@ -214,9 +226,11 @@ func buildCallStack(cmd Command, ops *ExecuteOptions) ([]command, error) {
 		}
 
 		// add help flags
-		if this.fs.Lookup("h") == nil && this.fs.Lookup("help") == nil {
-			this.fs.BoolVar(&this.showHelp, "h", false, "show command help and usage information")
-			this.fs.BoolVar(&this.showHelp, "help", false, "show command help and usage information")
+		if this.fs.Lookup("h") == nil {
+			this.fs.BoolVar(&this.showUsage, "h", false, "show command usage information")
+		}
+		if this.fs.Lookup("help") == nil {
+			this.fs.BoolVar(&this.showHelp, "help", false, "show command help information")
 		}
 
 		// bind environment variables

flags.go

@@ -8,12 +8,12 @@ import (
 	"github.com/brandon1024/cmder/getopt"
 )
 
-// FlagInitializer is an interface implemented by commands that need to register flags.
+// FlagInitializer is an interface implemented by a [Command] that need to register flags.
 //
-// InitializeFlags will be invoked during [Execute], prior to Initialize/Run/Destroy routines. You can use this to
+// InitializeFlags will be invoked during [Execute], prior to Initialize()/Run()/Destroy() routines. You can use this to
 // register flags for your command.
 //
-// If the command does not define help flags '-h' and '--help', they will be registered automatically and will instruct
+// If the command does not define help flags '-h' or '--help', they will be registered automatically and will instruct
 // [Execute] to render command usage.
 type FlagInitializer interface {
 	InitializeFlags(*flag.FlagSet)

getopt/example_mapvar_test.go

@@ -12,16 +12,20 @@ import (
 // This example demonstrates usage of [getopt.MapVar] for string maps. You'll often find map flags on commands that
 // perform templating of text files, for example.
 func ExampleMapVar() {
-	variables := getopt.MapVar{}
-
 	fs := flag.NewFlagSet("map", flag.ContinueOnError)
+
+	// option 1: use MapVar directly
+	variables := getopt.MapVar{}
 	fs.Var(&variables, "variable", "specify runtime variables")
-	fs.Var(&variables, "v", "specify runtime variables")
+
+	// option 2: wrap an existing map with Map
+	arg := map[string]string{}
+	fs.Var(getopt.Map(arg), "arg", "specify runtime args")
 
 	args := []string{
 		"--variable", "key1=value1",
-		"-v", "key2=value2,key3=value3",
-		`--variable="hello= HI, WORLD "`,
+		"--variable", "key2=value2,key3=value3",
+		`--arg="hello= HI, WORLD "`,
 	}
 
 	if err := fs.Parse(args); err != nil {
@@ -31,9 +35,12 @@ func ExampleMapVar() {
 	for _, k := range slices.Sorted(maps.Keys(variables)) {
 		fmt.Printf("%s: '%s'\n", k, variables[k])
 	}
+	for _, k := range slices.Sorted(maps.Keys(arg)) {
+		fmt.Printf("%s: '%s'\n", k, arg[k])
+	}
 	// Output:
-	// hello: ' HI, WORLD '
 	// key1: 'value1'
 	// key2: 'value2'
 	// key3: 'value3'
+	// hello: ' HI, WORLD '
 }

getopt/example_stringsvar_test.go

@@ -16,14 +16,19 @@ func ExampleStringsVar() {
 	var hosts getopt.StringsVar
 	fs.Var(&hosts, "broker", "connect to a broker")
 
-	// option 2: wrap an existing slice
+	// option 2: wrap an existing slice with Strings
 	var args []string
-	fs.Var((*getopt.StringsVar)(&args), "a", "provide args")
+	fs.Var(getopt.Strings(&args), "a", "provide args")
+
+	// option 3: wrap an existing slice by pointer casting
+	var patterns []string
+	fs.Var((*getopt.StringsVar)(&patterns), "p", "provide patterns")
 
 	fs.Parse([]string{
 		"--broker", "tls://broker-1.domain.example.com,tls://broker-2.domain.example.com",
 		"-a", "CLIENT_USER",
 		"-a", "CLIENT_PASS",
+		"-p", "**/*.go,*.mod,*.sum",
 	})
 
 	for _, host := range hosts {
@@ -32,9 +37,15 @@ func ExampleStringsVar() {
 	for _, arg := range args {
 		fmt.Printf("arg: '%s'\n", arg)
 	}
+	for _, patt := range patterns {
+		fmt.Printf("patterns: '%s'\n", patt)
+	}
 	// Output:
 	// broker: 'tls://broker-1.domain.example.com'
 	// broker: 'tls://broker-2.domain.example.com'
 	// arg: 'CLIENT_USER'
 	// arg: 'CLIENT_PASS'
+	// patterns: '**/*.go'
+	// patterns: '*.mod'
+	// patterns: '*.sum'
 }

getopt/example_timevar_test.go

@@ -3,26 +3,35 @@ package getopt_test
 import (
 	"flag"
 	"fmt"
+	"time"
 
 	"github.com/brandon1024/cmder/getopt"
 )
 
 // This example demonstrates the usage of [getopt.TimeVar].
 func ExampleTimeVar() {
-	var since getopt.TimeVar
-
 	fs := flag.NewFlagSet("custom", flag.ContinueOnError)
+
+	// option 1: using TimeVar directly
+	var since getopt.TimeVar
 	fs.Var(&since, "since", "show items since")
 
+	// option 2: with Time
+	var until time.Time
+	fs.Var(getopt.Time(&until), "until", "show items until")
+
 	args := []string{
 		"-since", "2025-01-01T00:00:00Z",
+		"-until", "2026-01-01T00:00:00Z",
 	}
 
 	if err := fs.Parse(args); err != nil {
 		panic(err)
 	}
 
 	fmt.Printf("since: %s\n", since.String())
+	fmt.Printf("until: %s\n", until.String())
 	// Output:
 	// since: 2025-01-01T00:00:00Z
+	// until: 2026-01-01 00:00:00 +0000 UTC
 }

getopt/mapvar.go

@@ -20,6 +20,11 @@ import (
 //	key1=v=1,key2=v=2
 type MapVar map[string]string
 
+// Map returns a [MapVar] for ss.
+func Map(m map[string]string) MapVar {
+	return MapVar(m)
+}
+
 // String returns the map, formatted as a set of key-value pairs.
 func (m MapVar) String() string {
 	var entries []string

getopt/stringsvar.go

@@ -17,6 +17,11 @@ import (
 //	"value, 1","value, 2"
 type StringsVar []string
 
+// Strings returns a [StringsVar] for ss.
+func Strings(ss *[]string) *StringsVar {
+	return (*StringsVar)(ss)
+}
+
 // String returns the slice, formatted as comma-separated values.
 func (s StringsVar) String() string {
 	var builder strings.Builder

getopt/timevar.go

@@ -8,6 +8,11 @@ import (
 // [flag.Getter].
 type TimeVar time.Time
 
+// Time returns a [TimeVar] for tm.
+func Time(tm *time.Time) *TimeVar {
+	return (*TimeVar)(tm)
+}
+
 // String returns the [time.RFC3339] representation of the timestamp flag.
 func (t *TimeVar) String() string {
 	return time.Time(*t).Format(time.RFC3339)