dump go.*

Signed-off-by: Jeff Carr <jcarr@wit.com>

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [alexflint]

.github/workflows/go.yml

@@ -15,17 +15,17 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        go: ['1.19', '1.20', '1.21']
+        go: ['1.20', '1.21', '1.22']
 
     steps:
     - id: go
       name: Set up Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v5
       with:
         go-version: ${{ matrix.go }}
 
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Build
       run: go build -v .

.gitignore

@@ -22,3 +22,5 @@ _testmain.go
 *.exe
 *.test
 *.prof
+
+go.*

Makefile

@@ -0,0 +1,11 @@
+all:
+	@echo
+	@echo
+
+clean:
+	rm -f go.*
+
+redomod:
+	rm -f go.*
+	GO111MODULE= go mod init
+	GO111MODULE= go mod tidy

README.md

@@ -64,7 +64,7 @@ fmt.Println("Input:", args.Input)
 fmt.Println("Output:", args.Output)
 ```
 
-```
+```shell
 $ ./example src.txt x.out y.out z.out
 Input: src.txt
 Output: [x.out y.out z.out]
@@ -80,12 +80,12 @@ arg.MustParse(&args)
 fmt.Println("Workers:", args.Workers)
 ```
 
-```
+```shell
 $ WORKERS=4 ./example
 Workers: 4
 ```
 
-```
+```shell
 $ WORKERS=4 ./example --workers=6
 Workers: 6
 ```
@@ -100,12 +100,12 @@ arg.MustParse(&args)
 fmt.Println("Workers:", args.Workers)
 ```
 
-```
+```shell
 $ NUM_WORKERS=4 ./example
 Workers: 4
 ```
 
-You can provide multiple values using the CSV (RFC 4180) format:
+You can provide multiple values in environment variables using commas:
 
 ```go
 var args struct {
@@ -115,12 +115,50 @@ arg.MustParse(&args)
 fmt.Println("Workers:", args.Workers)
 ```
 
-```
+```shell
 $ WORKERS='1,99' ./example
 Workers: [1 99]
 ```
 
+Command line arguments take precedence over environment variables:
+
+```go
+var args struct {
+	Workers int `arg:"--count,env:NUM_WORKERS"`
+}
+arg.MustParse(&args)
+fmt.Println("Workers:", args.Workers)
+```
+
+```shell
+$ NUM_WORKERS=6 ./example
+Workers: 6
+$ NUM_WORKERS=6 ./example --count 4
+Workers: 4
+```
+
+Configuring a global environment variable name prefix is also possible:
+
+```go
+var args struct {
+	Workers int `arg:"--count,env:NUM_WORKERS"`
+}
+
+p, err := arg.NewParser(arg.Config{
+    EnvPrefix: "MYAPP_",
+}, &args)
+
+p.MustParse(os.Args[1:])
+fmt.Println("Workers:", args.Workers)
+```
+
+```shell
+$ MYAPP_NUM_WORKERS=6 ./example
+Workers: 6
+```
+
 ### Usage strings
+
 ```go
 var args struct {
 	Input    string   `arg:"positional"`
@@ -158,20 +196,7 @@ var args struct {
 arg.MustParse(&args)
 ```
 
-### Default values (before v1.2)
-
-```go
-var args struct {
-	Foo string
-	Bar bool
-}
-arg.Foo = "abc"
-arg.MustParse(&args)
-```
-
-### Combining command line options, environment variables, and default values
-
-You can combine command line arguments, environment variables, and default values. Command line arguments take precedence over environment variables, which take precedence over default values. This means that we check whether a certain option was provided on the command line, then if not, we check for an environment variable (only if an `env` tag was provided), then if none is found, we check for a `default` tag containing a default value.
+Command line arguments take precedence over environment variables, which take precedence over default values. This means that we check whether a certain option was provided on the command line, then if not, we check for an environment variable (only if an `env` tag was provided), then if none is found, we check for a `default` tag containing a default value.
 
 ```go
 var args struct {
@@ -182,9 +207,6 @@ arg.MustParse(&args)
 
 #### Ignoring environment variables and/or default values
 
-The values in an existing structure can be kept in-tact by ignoring environment
-variables and/or default values.
-
 ```go
 var args struct {
     Test  string `arg:"-t,env:TEST" default:"something"`
@@ -195,10 +217,11 @@ p, err := arg.NewParser(arg.Config{
     IgnoreDefault: true,
 }, &args)
 
-err = p.Parse(os.Args)
+err = p.Parse(os.Args[1:])
 ```
 
 ### Arguments with multiple values
+
 ```go
 var args struct {
 	Database string
@@ -214,6 +237,7 @@ Fetching the following IDs from foo: [1 2 3]
 ```
 
 ### Arguments that can be specified multiple times, mixed with positionals
+
 ```go
 var args struct {
     Commands  []string `arg:"-c,separate"`
@@ -231,6 +255,7 @@ Databases [db1 db2 db3]
 ```
 
 ### Arguments with keys and values
+
 ```go
 var args struct {
 	UserIDs map[string]int
@@ -244,24 +269,6 @@ fmt.Println(args.UserIDs)
 map[john:123 mary:456]
 ```
 
-### Custom validation
-```go
-var args struct {
-	Foo string
-	Bar string
-}
-p := arg.MustParse(&args)
-if args.Foo == "" && args.Bar == "" {
-	p.Fail("you must provide either --foo or --bar")
-}
-```
-
-```shell
-./example
-Usage: samples [--foo FOO] [--bar BAR]
-error: you must provide either --foo or --bar
-```
-
 ### Version strings
 
 ```go
@@ -284,6 +291,28 @@ $ ./example --version
 someprogram 4.3.0
 ```
 
+> **Note**
+> If a `--version` flag is defined in `args` or any subcommand, it overrides the built-in versioning.
+
+### Custom validation
+
+```go
+var args struct {
+	Foo string
+	Bar string
+}
+p := arg.MustParse(&args)
+if args.Foo == "" && args.Bar == "" {
+	p.Fail("you must provide either --foo or --bar")
+}
+```
+
+```shell
+./example
+Usage: samples [--foo FOO] [--bar BAR]
+error: you must provide either --foo or --bar
+```
+
 ### Overriding option names
 
 ```go
@@ -308,13 +337,11 @@ Options:
   --help, -h             display this help and exit
 ```
 
-
 ### Embedded structs
 
 The fields of embedded structs are treated just like regular fields:
 
 ```go
-
 type DatabaseOptions struct {
 	Host     string
 	Username string
@@ -382,6 +409,7 @@ func main() {
 	fmt.Printf("%#v\n", args.Name)
 }
 ```
+
 ```shell
 $ ./example --name=foo.bar
 main.NameDotName{Head:"foo", Tail:"bar"}
@@ -418,6 +446,7 @@ func main() {
 	fmt.Printf("%#v\n", args.Name)
 }
 ```
+
 ```shell
 $ ./example --help
 Usage: test [--name NAME]
@@ -432,8 +461,6 @@ main.NameDotName{Head:"file", Tail:"txt"}
 
 ### Custom placeholders
 
-*Introduced in version 1.3.0*
-
 Use the `placeholder` tag to control which placeholder text is used in the usage text.
 
 ```go
@@ -445,6 +472,7 @@ var args struct {
 }
 arg.MustParse(&args)
 ```
+
 ```shell
 $ ./example -h
 Usage: example [--optimize LEVEL] [--maxjobs N] SRC [DST [DST ...]]
@@ -521,8 +549,6 @@ For more information visit github.com/alexflint/go-arg
 
 ### Subcommands
 
-*Introduced in version 1.1.0*
-
 Subcommands are commonly used in tools that wish to group multiple functions into a single program. An example is the `git` tool:
 ```shell
 $ git checkout [arguments specific to checking out code]
@@ -583,15 +609,187 @@ if p.Subcommand() == nil {
 }
 ```
 
+### Custom handling of --help and --version
+
+The following reproduces the internal logic of `MustParse` for the simple case where
+you are not using subcommands or --version. This allows you to respond
+programatically to --help, and to any errors that come up.
+
+```go
+var args struct {
+	Something string
+}
+
+p, err := arg.NewParser(arg.Config{}, &args)
+if err != nil {
+	log.Fatalf("there was an error in the definition of the Go struct: %v", err)
+}
+
+err = p.Parse(os.Args[1:])
+switch {
+case err == arg.ErrHelp:  // indicates that user wrote "--help" on command line
+	p.WriteHelp(os.Stdout)
+	os.Exit(0)
+case err != nil:
+	fmt.Printf("error: %v\n", err)
+	p.WriteUsage(os.Stdout)
+	os.Exit(1)
+}
+```
+
+```shell
+$ go run ./example --help
+Usage: ./example --something SOMETHING
+
+Options:
+  --something SOMETHING
+  --help, -h             display this help and exit
+
+$ ./example --wrong
+error: unknown argument --wrong
+Usage: ./example --something SOMETHING
+
+$ ./example
+error: --something is required
+Usage: ./example --something SOMETHING
+```
+
+To also handle --version programatically, use the following:
+
+```go
+type args struct {
+	Something string
+}
+
+func (args) Version() string {
+	return "1.2.3"
+}
+
+func main() {
+	var args args
+	p, err := arg.NewParser(arg.Config{}, &args)
+	if err != nil {
+		log.Fatalf("there was an error in the definition of the Go struct: %v", err)
+	}
+
+	err = p.Parse(os.Args[1:])
+	switch {
+	case err == arg.ErrHelp: // found "--help" on command line
+		p.WriteHelp(os.Stdout)
+		os.Exit(0)
+	case err == arg.ErrVersion: // found "--version" on command line
+		fmt.Println(args.Version())
+		os.Exit(0)
+	case err != nil:
+		fmt.Printf("error: %v\n", err)
+		p.WriteUsage(os.Stdout)
+		os.Exit(1)
+	}
+
+	fmt.Printf("got %q\n", args.Something)
+}
+```
+
+```shell
+$ ./example --version
+1.2.3
+
+$ go run ./example --help
+1.2.3
+Usage: example --something SOMETHING
+
+Options:
+  --something SOMETHING
+  --help, -h             display this help and exit
+
+$ ./example --wrong
+1.2.3
+error: unknown argument --wrong
+Usage: example --something SOMETHING
+
+$ ./example
+error: --something is required
+Usage: example --something SOMETHING
+```
+
+To generate subcommand-specific help messages, use the following most general version
+(this also works in absence of subcommands but is a bit more complex):
+
+```go
+type fetchCmd struct {
+	Count int
+}
+
+type args struct {
+	Something string
+	Fetch     *fetchCmd `arg:"subcommand"`
+}
+
+func (args) Version() string {
+	return "1.2.3"
+}
+
+func main() {
+	var args args
+	p, err := arg.NewParser(arg.Config{}, &args)
+	if err != nil {
+		log.Fatalf("there was an error in the definition of the Go struct: %v", err)
+	}
+
+	err = p.Parse(os.Args[1:])
+	switch {
+	case err == arg.ErrHelp: // found "--help" on command line
+		p.WriteHelpForSubcommand(os.Stdout, p.SubcommandNames()...)
+		os.Exit(0)
+	case err == arg.ErrVersion: // found "--version" on command line
+		fmt.Println(args.Version())
+		os.Exit(0)
+	case err != nil:
+		fmt.Printf("error: %v\n", err)
+		p.WriteUsageForSubcommand(os.Stdout, p.SubcommandNames()...)
+		os.Exit(1)
+	}
+}
+```
+
+```shell
+$ ./example --version
+1.2.3
+
+$ ./example --help
+1.2.3
+Usage: example [--something SOMETHING] <command> [<args>]
+
+Options:
+  --something SOMETHING
+  --help, -h             display this help and exit
+  --version              display version and exit
+
+Commands:
+  fetch
+
+$ ./example fetch --help
+1.2.3
+Usage: example fetch [--count COUNT]
+
+Options:
+  --count COUNT
+
+Global options:
+  --something SOMETHING
+  --help, -h             display this help and exit
+  --version              display version and exit
+```
+
 ### API Documentation
 
-https://godoc.org/github.com/alexflint/go-arg
+https://pkg.go.dev/github.com/alexflint/go-arg
 
 ### Rationale
 
 There are many command line argument parsing libraries for Go, including one in the standard library, so why build another?
 
-The `flag` library that ships in the standard library seems awkward to me. Positional arguments must preceed options, so `./prog x --foo=1` does what you expect but `./prog --foo=1 x` does not. It also does not allow arguments to have both long (`--foo`) and short (`-f`) forms.
+The `flag` library that ships in the standard library seems awkward to me. Positional arguments must precede options, so `./prog x --foo=1` does what you expect but `./prog --foo=1 x` does not. It also does not allow arguments to have both long (`--foo`) and short (`-f`) forms.
 
 Many third-party argument parsing libraries are great for writing sophisticated command line interfaces, but feel to me like overkill for a simple script with a few flags.
 
@@ -599,4 +797,4 @@ The idea behind `go-arg` is that Go already has an excellent way to describe dat
 
 ### Backward compatibility notes
 
-Earlier versions of this library required the help text to be part of the `arg` tag. This is still supported but is now deprecated. Instead, you should use a separate `help` tag, described above, which removes most of the limits on the text you can write. In particular, you will need to use the new `help` tag if your help text includes any commas.
+Earlier versions of this library required the help text to be part of the `arg` tag. This is still supported but is now deprecated. Instead, you should use a separate `help` tag, described above, which makes it possible to include commas inside help text.

go.mod

@@ -1,14 +0,0 @@
-module github.com/alexflint/go-arg
-
-require (
-	github.com/alexflint/go-scalar v1.2.0
-	github.com/stretchr/testify v1.7.0
-)
-
-require (
-	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
-	gopkg.in/yaml.v3 v3.0.0 // indirect
-)
-
-go 1.18

go.sum

@@ -1,16 +0,0 @@
-github.com/alexflint/go-scalar v1.2.0 h1:WR7JPKkeNpnYIOfHRa7ivM21aWAdHD0gEWHCx+WQBRw=
-github.com/alexflint/go-scalar v1.2.0/go.mod h1:LoFvNMqS1CPrMVltza4LvnGKhaSpc3oyLEBUZVhhS2o=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
-github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
-github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
-github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-gopkg.in/yaml.v3 v3.0.0 h1:hjy8E9ON/egN1tAYqKb61G10WtihqetD4sz2H+8nIeA=
-gopkg.in/yaml.v3 v3.0.0/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

parse.go

@@ -11,7 +11,7 @@ import (
 	"reflect"
 	"strings"
 
-	scalar "github.com/alexflint/go-scalar"
+	"go.wit.com/dev/alexflint/scalar"
 )
 
 // path represents a sequence of steps to find the output location for an
@@ -56,12 +56,13 @@ type spec struct {
 	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
-	placeholder   string              // name of the data in help
+	placeholder   string              // placeholder string in help
 }
 
 // command represents a named subcommand, or the top-level command
 type command struct {
 	name        string
+	aliases     []string
 	help        string
 	dest        path
 	specs       []*spec
@@ -75,27 +76,39 @@ var ErrHelp = errors.New("help requested by user")
 // ErrVersion indicates that the builtin --version was provided
 var ErrVersion = errors.New("version requested by user")
 
-// for monkey patching in example code
+// for monkey patching in example and test code
 var mustParseExit = os.Exit
+var mustParseOut io.Writer = os.Stdout
+
+// This stores the args sent from modules
+var register []interface{}
+
+/*
+	Use this in your packages to register
+	variables with go-arg. Then add this to your init()
+
+	package 'foo'
+	function init() {
+		args.Register(&argsFoo)
+	}
+*/
+func Register(dest ...interface{}) {
+	register = append(register, dest...)
+}
 
 // MustParse processes command line arguments and exits upon failure
 func MustParse(dest ...interface{}) *Parser {
-	return mustParse(Config{Exit: mustParseExit}, dest...)
+	register = append(register, dest...)
+	return mustParse(Config{Exit: mustParseExit, Out: mustParseOut}, register...)
 }
 
+
 // mustParse is a helper that facilitates testing
 func mustParse(config Config, dest ...interface{}) *Parser {
-	if config.Exit == nil {
-		config.Exit = os.Exit
-	}
-	if config.Out == nil {
-		config.Out = os.Stdout
-	}
-
 	p, err := NewParser(config, dest...)
 	if err != nil {
 		fmt.Fprintln(config.Out, err)
-		config.Exit(-1)
+		config.Exit(2)
 		return nil
 	}
 
@@ -136,6 +149,9 @@ type Config struct {
 	// subcommand
 	StrictSubcommands bool
 
+	// EnvPrefix instructs the library to use a name prefix when reading environment variables.
+	EnvPrefix string
+
 	// Exit is called to terminate the process with an error code (defaults to os.Exit)
 	Exit func(int)
 
@@ -153,7 +169,7 @@ type Parser struct {
 	epilogue    string
 
 	// the following field changes during processing of command line arguments
-	lastCmd *command
+	subcommand []string
 }
 
 // Versioned is the interface that the destination struct should implement to
@@ -240,7 +256,7 @@ func NewParser(config Config, dests ...interface{}) (*Parser, error) {
 			panic(fmt.Sprintf("%s is not a pointer (did you forget an ampersand?)", t))
 		}
 
-		cmd, err := cmdFromStruct(name, path{root: i}, t)
+		cmd, err := cmdFromStruct(name, path{root: i}, t, config.EnvPrefix)
 		if err != nil {
 			return nil, err
 		}
@@ -290,7 +306,7 @@ func NewParser(config Config, dests ...interface{}) (*Parser, error) {
 	return &p, nil
 }
 
-func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
+func cmdFromStruct(name string, dest path, t reflect.Type, envPrefix string) (*command, error) {
 	// commands can only be created from pointers to structs
 	if t.Kind() != reflect.Ptr {
 		return nil, fmt.Errorf("subcommands must be pointers to structs but %s is a %s",
@@ -341,9 +357,8 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
 			spec.help = help
 		}
 
-		// Look at the tag
-		var isSubcommand bool // tracks whether this field is a subcommand
-
+		// process each comma-separated part of the tag
+		var isSubcommand bool
 		for _, key := range strings.Split(tag, ",") {
 			if key == "" {
 				continue
@@ -378,24 +393,30 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
 			case key == "env":
 				// Use override name if provided
 				if value != "" {
-					spec.env = value
+					spec.env = envPrefix + value
 				} else {
-					spec.env = strings.ToUpper(field.Name)
+					spec.env = envPrefix + strings.ToUpper(field.Name)
 				}
 			case key == "subcommand":
 				// decide on a name for the subcommand
-				cmdname := value
-				if cmdname == "" {
-					cmdname = strings.ToLower(field.Name)
+				var cmdnames []string
+				if value == "" {
+					cmdnames = []string{strings.ToLower(field.Name)}
+				} else {
+					cmdnames = strings.Split(value, "|")
+				}
+				for i := range cmdnames {
+					cmdnames[i] = strings.TrimSpace(cmdnames[i])
 				}
 
 				// parse the subcommand recursively
-				subcmd, err := cmdFromStruct(cmdname, subdest, field.Type)
+				subcmd, err := cmdFromStruct(cmdnames[0], subdest, field.Type, envPrefix)
 				if err != nil {
 					errs = append(errs, err.Error())
 					return false
 				}
 
+				subcmd.aliases = cmdnames[1:]
 				subcmd.parent = &cmd
 				subcmd.help = field.Tag.Get("help")
 
@@ -407,6 +428,7 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
 			}
 		}
 
+		// placeholder is the string used in the help text like this: "--somearg PLACEHOLDER"
 		placeholder, hasPlaceholder := field.Tag.Lookup("placeholder")
 		if hasPlaceholder {
 			spec.placeholder = placeholder
@@ -492,8 +514,15 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) {
 	return &cmd, nil
 }
 
-// Parse processes the given command line option, storing the results in the field
-// of the structs from which NewParser was constructed
+// Parse processes the given command line option, storing the results in the fields
+// of the structs from which NewParser was constructed.
+//
+// It returns ErrHelp if "--help" is one of the command line args and ErrVersion if
+// "--version" is one of the command line args (the latter only applies if the
+// destination struct passed to NewParser implements Versioned.)
+//
+// To respond to --help and --version in the way that MustParse does, see examples
+// in the README under "Custom handling of --help and --version".
 func (p *Parser) Parse(args []string) error {
 	err := p.process(args)
 	if err != nil {
@@ -514,13 +543,13 @@ func (p *Parser) MustParse(args []string) {
 	err := p.Parse(args)
 	switch {
 	case err == ErrHelp:
-		p.writeHelpForSubcommand(p.config.Out, p.lastCmd)
+		p.WriteHelpForSubcommand(p.config.Out, p.subcommand...)
 		p.config.Exit(0)
 	case err == ErrVersion:
 		fmt.Fprintln(p.config.Out, p.version)
 		p.config.Exit(0)
 	case err != nil:
-		p.failWithSubcommand(err.Error(), p.lastCmd)
+		p.FailSubcommand(err.Error(), p.subcommand...)
 	}
 }
 
@@ -577,7 +606,7 @@ func (p *Parser) process(args []string) error {
 
 	// union of specs for the chain of subcommands encountered so far
 	curCmd := p.cmd
-	p.lastCmd = curCmd
+	p.subcommand = nil
 
 	// make a copy of the specs because we will add to this list each time we expand a subcommand
 	specs := make([]*spec, len(curCmd.specs))
@@ -607,7 +636,7 @@ func (p *Parser) process(args []string) error {
 	// must use explicit for loop, not range, because we manipulate i inside the loop
 	for i := 0; i < len(args); i++ {
 		arg := args[i]
-		if arg == "--" {
+		if arg == "--" && !allpositional {
 			allpositional = true
 			continue
 		}
@@ -648,7 +677,7 @@ func (p *Parser) process(args []string) error {
 			}
 
 			curCmd = subcmd
-			p.lastCmd = curCmd
+			p.subcommand = append(p.subcommand, arg)
 			continue
 		}
 
@@ -842,6 +871,11 @@ func findSubcommand(cmds []*command, name string) *command {
 		if cmd.name == name {
 			return cmd
 		}
+		for _, alias := range cmd.aliases {
+			if alias == name {
+				return cmd
+			}
+		}
 	}
 	return nil
 }

reflect.go

@@ -7,7 +7,7 @@ import (
 	"unicode"
 	"unicode/utf8"
 
-	scalar "github.com/alexflint/go-scalar"
+	"go.wit.com/dev/alexflint/scalar"
 )
 
 var textUnmarshalerType = reflect.TypeOf([]encoding.TextUnmarshaler{}).Elem()

sequence.go

@@ -5,7 +5,7 @@ import (
 	"reflect"
 	"strings"
 
-	scalar "github.com/alexflint/go-scalar"
+	"go.wit.com/dev/alexflint/scalar"
 )
 
 // setSliceOrMap parses a sequence of strings into a slice or map. If clear is

subcommand.go

@@ -1,5 +1,7 @@
 package arg
 
+import "fmt"
+
 // Subcommand returns the user struct for the subcommand selected by
 // the command line arguments most recently processed by the parser.
 // The return value is always a pointer to a struct. If no subcommand
@@ -7,31 +9,35 @@ package arg
 // no command line arguments have been processed by this parser then it
 // returns nil.
 func (p *Parser) Subcommand() interface{} {
-	if p.lastCmd == nil || p.lastCmd.parent == nil {
+	if len(p.subcommand) == 0 {
 		return nil
 	}
-	return p.val(p.lastCmd.dest).Interface()
+	cmd, err := p.lookupCommand(p.subcommand...)
+	if err != nil {
+		return nil
+	}
+	return p.val(cmd.dest).Interface()
 }
 
 // SubcommandNames returns the sequence of subcommands specified by the
 // user. If no subcommands were given then it returns an empty slice.
 func (p *Parser) SubcommandNames() []string {
-	if p.lastCmd == nil {
-		return nil
-	}
-
-	// make a list of ancestor commands
-	var ancestors []string
-	cur := p.lastCmd
-	for cur.parent != nil { // we want to exclude the root
-		ancestors = append(ancestors, cur.name)
-		cur = cur.parent
-	}
-
-	// reverse the list
-	out := make([]string, len(ancestors))
-	for i := 0; i < len(ancestors); i++ {
-		out[i] = ancestors[len(ancestors)-i-1]
-	}
-	return out
+	return p.subcommand
+}
+
+// lookupCommand finds a subcommand based on a sequence of subcommand names. The
+// first string should be a top-level subcommand, the next should be a child
+// subcommand of that subcommand, and so on. If no strings are given then the
+// root command is returned. If no such subcommand exists then an error is
+// returned.
+func (p *Parser) lookupCommand(path ...string) (*command, error) {
+	cmd := p.cmd
+	for _, name := range path {
+		found := findSubcommand(cmd.subcommands, name)
+		if found == nil {
+			return nil, fmt.Errorf("%q is not a subcommand of %s", name, cmd.name)
+		}
+		cmd = found
+	}
+	return cmd, nil
 }

test/Makefile

@@ -0,0 +1,10 @@
+all:
+	@echo
+	@echo
+
+test:
+
+redomod:
+	rm -f go.*
+	GO111MODULE= go mod init
+	GO111MODULE= go mod tidy

test/example_test.go

@@ -163,6 +163,7 @@ func Example_helpText() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
@@ -195,17 +196,17 @@ func Example_helpPlaceholder() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
 	// output:
-
 	// Usage: example [--optimize LEVEL] [--maxjobs N] SRC [DST [DST ...]]
-
+	//
 	// Positional arguments:
 	//   SRC
 	//   DST
-
+	//
 	// Options:
 	//   --optimize LEVEL, -O LEVEL
 	//                          optimization level
@@ -235,6 +236,7 @@ func Example_helpTextWithSubcommand() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
@@ -272,6 +274,7 @@ func Example_helpTextWhenUsingSubcommand() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
@@ -392,6 +395,7 @@ func Example_errorText() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
@@ -415,6 +419,7 @@ func Example_errorTextForSubcommand() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 
@@ -450,6 +455,7 @@ func Example_subcommand() {
 
 	// This is only necessary when running inside golang's runnable example harness
 	mustParseExit = func(int) {}
+	mustParseOut = os.Stdout
 
 	MustParse(&args)
 

test/go.mod

@@ -0,0 +1,11 @@
+module go.wit.com/dev/alexflint/arg/test
+
+go 1.21.4
+
+require github.com/stretchr/testify v1.8.4
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

test/go.sum

@@ -0,0 +1,10 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

test/parse_test.go

@@ -28,11 +28,11 @@ func parse(cmdline string, dest interface{}) error {
 }
 
 func pparse(cmdline string, dest interface{}) (*Parser, error) {
-	return parseWithEnv(cmdline, nil, dest)
+	return parseWithEnv(Config{}, cmdline, nil, dest)
 }
 
-func parseWithEnv(cmdline string, env []string, dest interface{}) (*Parser, error) {
-	p, err := NewParser(Config{}, dest)
+func parseWithEnv(config Config, cmdline string, env []string, dest interface{}) (*Parser, error) {
+	p, err := NewParser(config, dest)
 	if err != nil {
 		return nil, err
 	}
@@ -231,7 +231,7 @@ func TestRequiredWithEnvOnly(t *testing.T) {
 	var args struct {
 		Foo string `arg:"required,--,-,env:FOO"`
 	}
-	_, err := parseWithEnv("", []string{}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{}, &args)
 	require.Error(t, err, "environment variable FOO is required")
 }
 
@@ -609,6 +609,15 @@ func TestNoMoreOptionsBeforeHelp(t *testing.T) {
 	assert.NotEqual(t, ErrHelp, err)
 }
 
+func TestNoMoreOptionsTwice(t *testing.T) {
+	var args struct {
+		X []string `arg:"positional"`
+	}
+	err := parse("-- --", &args)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"--"}, args.X)
+}
+
 func TestHelpFlag(t *testing.T) {
 	var args struct {
 		Foo string
@@ -692,11 +701,26 @@ func TestMustParse(t *testing.T) {
 	assert.NotNil(t, parser)
 }
 
+func TestMustParseError(t *testing.T) {
+	var args struct {
+		Foo []string `default:""`
+	}
+	var exitCode int
+	var stdout bytes.Buffer
+	mustParseExit = func(code int) { exitCode = code }
+	mustParseOut = &stdout
+	os.Args = []string{"example"}
+	parser := MustParse(&args)
+	assert.Nil(t, parser)
+	assert.Equal(t, 2, exitCode)
+	assert.Contains(t, stdout.String(), "default values are not supported for slice or map fields")
+}
+
 func TestEnvironmentVariable(t *testing.T) {
 	var args struct {
 		Foo string `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{"FOO=bar"}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{"FOO=bar"}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, "bar", args.Foo)
 }
@@ -705,7 +729,7 @@ func TestEnvironmentVariableNotPresent(t *testing.T) {
 	var args struct {
 		NotPresent string `arg:"env"`
 	}
-	_, err := parseWithEnv("", nil, &args)
+	_, err := parseWithEnv(Config{}, "", nil, &args)
 	require.NoError(t, err)
 	assert.Equal(t, "", args.NotPresent)
 }
@@ -714,7 +738,7 @@ func TestEnvironmentVariableOverrideName(t *testing.T) {
 	var args struct {
 		Foo string `arg:"env:BAZ"`
 	}
-	_, err := parseWithEnv("", []string{"BAZ=bar"}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{"BAZ=bar"}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, "bar", args.Foo)
 }
@@ -723,7 +747,7 @@ func TestEnvironmentVariableOverrideArgument(t *testing.T) {
 	var args struct {
 		Foo string `arg:"env"`
 	}
-	_, err := parseWithEnv("--foo zzz", []string{"FOO=bar"}, &args)
+	_, err := parseWithEnv(Config{}, "--foo zzz", []string{"FOO=bar"}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, "zzz", args.Foo)
 }
@@ -732,7 +756,7 @@ func TestEnvironmentVariableError(t *testing.T) {
 	var args struct {
 		Foo int `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{"FOO=bar"}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{"FOO=bar"}, &args)
 	assert.Error(t, err)
 }
 
@@ -740,7 +764,7 @@ func TestEnvironmentVariableRequired(t *testing.T) {
 	var args struct {
 		Foo string `arg:"env,required"`
 	}
-	_, err := parseWithEnv("", []string{"FOO=bar"}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{"FOO=bar"}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, "bar", args.Foo)
 }
@@ -749,7 +773,7 @@ func TestEnvironmentVariableSliceArgumentString(t *testing.T) {
 	var args struct {
 		Foo []string `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=bar,"baz, qux"`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=bar,"baz, qux"`}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, []string{"bar", "baz, qux"}, args.Foo)
 }
@@ -758,7 +782,7 @@ func TestEnvironmentVariableSliceEmpty(t *testing.T) {
 	var args struct {
 		Foo []string `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=`}, &args)
 	require.NoError(t, err)
 	assert.Len(t, args.Foo, 0)
 }
@@ -767,7 +791,7 @@ func TestEnvironmentVariableSliceArgumentInteger(t *testing.T) {
 	var args struct {
 		Foo []int `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=1,99`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=1,99`}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, []int{1, 99}, args.Foo)
 }
@@ -776,7 +800,7 @@ func TestEnvironmentVariableSliceArgumentFloat(t *testing.T) {
 	var args struct {
 		Foo []float32 `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=1.1,99.9`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=1.1,99.9`}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, []float32{1.1, 99.9}, args.Foo)
 }
@@ -785,7 +809,7 @@ func TestEnvironmentVariableSliceArgumentBool(t *testing.T) {
 	var args struct {
 		Foo []bool `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=true,false,0,1`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=true,false,0,1`}, &args)
 	require.NoError(t, err)
 	assert.Equal(t, []bool{true, false, false, true}, args.Foo)
 }
@@ -794,7 +818,7 @@ func TestEnvironmentVariableSliceArgumentWrongCsv(t *testing.T) {
 	var args struct {
 		Foo []int `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=1,99\"`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=1,99\"`}, &args)
 	assert.Error(t, err)
 }
 
@@ -802,7 +826,7 @@ func TestEnvironmentVariableSliceArgumentWrongType(t *testing.T) {
 	var args struct {
 		Foo []bool `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=one,two`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=one,two`}, &args)
 	assert.Error(t, err)
 }
 
@@ -810,7 +834,7 @@ func TestEnvironmentVariableMap(t *testing.T) {
 	var args struct {
 		Foo map[int]string `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=1=one,99=ninetynine`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=1=one,99=ninetynine`}, &args)
 	require.NoError(t, err)
 	assert.Len(t, args.Foo, 2)
 	assert.Equal(t, "one", args.Foo[1])
@@ -821,11 +845,21 @@ func TestEnvironmentVariableEmptyMap(t *testing.T) {
 	var args struct {
 		Foo map[int]string `arg:"env"`
 	}
-	_, err := parseWithEnv("", []string{`FOO=`}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{`FOO=`}, &args)
 	require.NoError(t, err)
 	assert.Len(t, args.Foo, 0)
 }
 
+func TestEnvironmentVariableWithPrefix(t *testing.T) {
+	var args struct {
+		Foo string `arg:"env"`
+	}
+
+	_, err := parseWithEnv(Config{EnvPrefix: "MYAPP_"}, "", []string{"MYAPP_FOO=bar"}, &args)
+	require.NoError(t, err)
+	assert.Equal(t, "bar", args.Foo)
+}
+
 func TestEnvironmentVariableIgnored(t *testing.T) {
 	var args struct {
 		Foo string `arg:"env"`
@@ -858,7 +892,7 @@ func TestRequiredEnvironmentOnlyVariableIsMissing(t *testing.T) {
 		Foo string `arg:"required,--,env:FOO"`
 	}
 
-	_, err := parseWithEnv("", []string{""}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{""}, &args)
 	assert.Error(t, err)
 }
 
@@ -867,7 +901,7 @@ func TestOptionalEnvironmentOnlyVariable(t *testing.T) {
 		Foo string `arg:"env:FOO"`
 	}
 
-	_, err := parseWithEnv("", []string{}, &args)
+	_, err := parseWithEnv(Config{}, "", []string{}, &args)
 	assert.NoError(t, err)
 }
 
@@ -883,7 +917,8 @@ func TestEnvironmentVariableInSubcommandIgnored(t *testing.T) {
 	require.NoError(t, err)
 
 	err = p.Parse([]string{"sub"})
-	assert.NoError(t, err)
+	require.NoError(t, err)
+	require.NotNil(t, args.Sub)
 	assert.Equal(t, "", args.Sub.Foo)
 }
 
@@ -905,7 +940,7 @@ func TestParserMustParse(t *testing.T) {
 	}{
 		{name: "help", args: struct{}{}, cmdLine: []string{"--help"}, code: 0, output: "display this help and exit"},
 		{name: "version", args: versioned{}, cmdLine: []string{"--version"}, code: 0, output: "example 3.2.1"},
-		{name: "invalid", args: struct{}{}, cmdLine: []string{"invalid"}, code: -1, output: ""},
+		{name: "invalid", args: struct{}{}, cmdLine: []string{"invalid"}, code: 2, output: ""},
 	}
 
 	for _, tt := range tests {
@@ -1555,7 +1590,7 @@ func TestMustParseInvalidParser(t *testing.T) {
 	}
 	parser := mustParse(Config{Out: &stdout, Exit: exit}, &args)
 	assert.Nil(t, parser)
-	assert.Equal(t, -1, exitCode)
+	assert.Equal(t, 2, exitCode)
 }
 
 func TestMustParsePrintsHelp(t *testing.T) {
@@ -1731,7 +1766,16 @@ func TestSubcommandGlobalFlag_InCommand_Strict_Inner(t *testing.T) {
 	require.NoError(t, err)
 
 	err = p.Parse([]string{"sub", "-g"})
-	assert.NoError(t, err)
+	require.NoError(t, err)
 	assert.False(t, args.Global)
+	require.NotNil(t, args.Sub)
 	assert.True(t, args.Sub.Guard)
 }
+
+func TestExitFunctionAndOutStreamGetFilledIn(t *testing.T) {
+	var args struct{}
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+	assert.NotNil(t, p.config.Exit) // go prohibits function pointer comparison
+	assert.Equal(t, p.config.Out, os.Stdout)
+}

test/subcommand_test.go

@@ -83,6 +83,19 @@ func TestNamedSubcommand(t *testing.T) {
 	assert.Equal(t, []string{"ls"}, p.SubcommandNames())
 }
 
+func TestSubcommandAliases(t *testing.T) {
+	type listCmd struct {
+	}
+	var args struct {
+		List *listCmd `arg:"subcommand:list|ls"`
+	}
+	p, err := pparse("ls", &args)
+	require.NoError(t, err)
+	assert.NotNil(t, args.List)
+	assert.Equal(t, args.List, p.Subcommand())
+	assert.Equal(t, []string{"ls"}, p.SubcommandNames())
+}
+
 func TestEmptySubcommand(t *testing.T) {
 	type listCmd struct {
 	}
@@ -113,6 +126,23 @@ func TestTwoSubcommands(t *testing.T) {
 	assert.Equal(t, []string{"list"}, p.SubcommandNames())
 }
 
+func TestTwoSubcommandsWithAliases(t *testing.T) {
+	type getCmd struct {
+	}
+	type listCmd struct {
+	}
+	var args struct {
+		Get  *getCmd  `arg:"subcommand:get|g"`
+		List *listCmd `arg:"subcommand:list|ls"`
+	}
+	p, err := pparse("ls", &args)
+	require.NoError(t, err)
+	assert.Nil(t, args.Get)
+	assert.NotNil(t, args.List)
+	assert.Equal(t, args.List, p.Subcommand())
+	assert.Equal(t, []string{"ls"}, p.SubcommandNames())
+}
+
 func TestSubcommandsWithOptions(t *testing.T) {
 	type getCmd struct {
 		Name string
@@ -275,6 +305,60 @@ func TestNestedSubcommands(t *testing.T) {
 	}
 }
 
+func TestNestedSubcommandsWithAliases(t *testing.T) {
+	type child struct{}
+	type parent struct {
+		Child *child `arg:"subcommand:child|ch"`
+	}
+	type grandparent struct {
+		Parent *parent `arg:"subcommand:parent|pa"`
+	}
+	type root struct {
+		Grandparent *grandparent `arg:"subcommand:grandparent|gp"`
+	}
+
+	{
+		var args root
+		p, err := pparse("gp parent child", &args)
+		require.NoError(t, err)
+		require.NotNil(t, args.Grandparent)
+		require.NotNil(t, args.Grandparent.Parent)
+		require.NotNil(t, args.Grandparent.Parent.Child)
+		assert.Equal(t, args.Grandparent.Parent.Child, p.Subcommand())
+		assert.Equal(t, []string{"gp", "parent", "child"}, p.SubcommandNames())
+	}
+
+	{
+		var args root
+		p, err := pparse("grandparent pa", &args)
+		require.NoError(t, err)
+		require.NotNil(t, args.Grandparent)
+		require.NotNil(t, args.Grandparent.Parent)
+		require.Nil(t, args.Grandparent.Parent.Child)
+		assert.Equal(t, args.Grandparent.Parent, p.Subcommand())
+		assert.Equal(t, []string{"grandparent", "pa"}, p.SubcommandNames())
+	}
+
+	{
+		var args root
+		p, err := pparse("grandparent", &args)
+		require.NoError(t, err)
+		require.NotNil(t, args.Grandparent)
+		require.Nil(t, args.Grandparent.Parent)
+		assert.Equal(t, args.Grandparent, p.Subcommand())
+		assert.Equal(t, []string{"grandparent"}, p.SubcommandNames())
+	}
+
+	{
+		var args root
+		p, err := pparse("", &args)
+		require.NoError(t, err)
+		require.Nil(t, args.Grandparent)
+		assert.Nil(t, p.Subcommand())
+		assert.Empty(t, p.SubcommandNames())
+	}
+}
+
 func TestSubcommandsWithPositionals(t *testing.T) {
 	type listCmd struct {
 		Pattern string `arg:"positional"`
@@ -411,3 +495,14 @@ func TestValForNilStruct(t *testing.T) {
 	v := p.val(path{fields: []reflect.StructField{subField, subField}})
 	assert.False(t, v.IsValid())
 }
+
+func TestSubcommandInvalidInternal(t *testing.T) {
+	// this situation should never arise in practice but still good to test for it
+	var cmd struct{}
+	p, err := NewParser(Config{}, &cmd)
+	require.NoError(t, err)
+
+	p.subcommand = []string{"should", "never", "happen"}
+	sub := p.Subcommand()
+	assert.Nil(t, sub)
+}

test/usage_test.go

@@ -237,7 +237,7 @@ func (versioned) Version() string {
 }
 
 func TestUsageWithVersion(t *testing.T) {
-	expectedUsage := "example 3.2.1\nUsage: example"
+	expectedUsage := "Usage: example"
 
 	expectedHelp := `
 example 3.2.1
@@ -260,6 +260,233 @@ Options:
 	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
 }
 
+func TestUsageWithUserDefinedVersionFlag(t *testing.T) {
+	expectedUsage := "Usage: example [--version]"
+
+	expectedHelp := `
+Usage: example [--version]
+
+Options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		ShowVersion bool `arg:"--version" help:"this is a user-defined version flag"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
+func TestUsageWithVersionAndUserDefinedVersionFlag(t *testing.T) {
+	expectedUsage := "Usage: example [--version]"
+
+	expectedHelp := `
+Usage: example [--version]
+
+Options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		versioned
+		ShowVersion bool `arg:"--version" help:"this is a user-defined version flag"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
+type subcommand struct {
+	Number int `arg:"-n,--number" help:"compute something on the given number"`
+}
+
+func TestUsageWithVersionAndSubcommand(t *testing.T) {
+	expectedUsage := "Usage: example <command> [<args>]"
+
+	expectedHelp := `
+example 3.2.1
+Usage: example <command> [<args>]
+
+Options:
+  --help, -h             display this help and exit
+  --version              display version and exit
+
+Commands:
+  cmd
+`
+
+	var args struct {
+		versioned
+		Cmd *subcommand `arg:"subcommand"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+
+	expectedUsage = "Usage: example cmd [--number NUMBER]"
+
+	expectedHelp = `
+example 3.2.1
+Usage: example cmd [--number NUMBER]
+
+Options:
+  --number NUMBER, -n NUMBER
+                         compute something on the given number
+  --help, -h             display this help and exit
+  --version              display version and exit
+`
+	_ = p.Parse([]string{"cmd"})
+
+	help = bytes.Buffer{}
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	usage = bytes.Buffer{}
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
+func TestUsageWithUserDefinedVersionFlagAndSubcommand(t *testing.T) {
+	expectedUsage := "Usage: example [--version] <command> [<args>]"
+
+	expectedHelp := `
+Usage: example [--version] <command> [<args>]
+
+Options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+
+Commands:
+  cmd
+`
+
+	var args struct {
+		Cmd         *subcommand `arg:"subcommand"`
+		ShowVersion bool        `arg:"--version" help:"this is a user-defined version flag"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+
+	expectedUsage = "Usage: example cmd [--number NUMBER]"
+
+	expectedHelp = `
+Usage: example cmd [--number NUMBER]
+
+Options:
+  --number NUMBER, -n NUMBER
+                         compute something on the given number
+
+Global options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+`
+	_ = p.Parse([]string{"cmd"})
+
+	help = bytes.Buffer{}
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	usage = bytes.Buffer{}
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
+func TestUsageWithVersionAndUserDefinedVersionFlagAndSubcommand(t *testing.T) {
+	expectedUsage := "Usage: example [--version] <command> [<args>]"
+
+	expectedHelp := `
+Usage: example [--version] <command> [<args>]
+
+Options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+
+Commands:
+  cmd
+`
+
+	var args struct {
+		versioned
+		Cmd         *subcommand `arg:"subcommand"`
+		ShowVersion bool        `arg:"--version" help:"this is a user-defined version flag"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+
+	expectedUsage = "Usage: example cmd [--number NUMBER]"
+
+	expectedHelp = `
+Usage: example cmd [--number NUMBER]
+
+Options:
+  --number NUMBER, -n NUMBER
+                         compute something on the given number
+
+Global options:
+  --version              this is a user-defined version flag
+  --help, -h             display this help and exit
+`
+	_ = p.Parse([]string{"cmd"})
+
+	help = bytes.Buffer{}
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	usage = bytes.Buffer{}
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
 type described struct{}
 
 // Described returns the description for this program
@@ -415,6 +642,50 @@ Options:
 	assert.Equal(t, expectedUsage, usage.String())
 }
 
+func TestUsageWithSubcommands(t *testing.T) {
+	expectedUsage := "Usage: example child [--values VALUES]"
+
+	expectedHelp := `
+Usage: example child [--values VALUES]
+
+Options:
+  --values VALUES        Values
+
+Global options:
+  --verbose, -v          verbosity level
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		Verbose bool `arg:"-v" help:"verbosity level"`
+		Child   *struct {
+			Values []float64 `help:"Values"`
+		} `arg:"subcommand:child"`
+	}
+
+	os.Args[0] = "example"
+	p, err := NewParser(Config{}, &args)
+	require.NoError(t, err)
+
+	_ = p.Parse([]string{"child"})
+
+	var help bytes.Buffer
+	p.WriteHelp(&help)
+	assert.Equal(t, expectedHelp[1:], help.String())
+
+	var help2 bytes.Buffer
+	p.WriteHelpForSubcommand(&help2, "child")
+	assert.Equal(t, expectedHelp[1:], help2.String())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+
+	var usage2 bytes.Buffer
+	p.WriteUsageForSubcommand(&usage2, "child")
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage2.String()))
+}
+
 func TestUsageWithNestedSubcommands(t *testing.T) {
 	expectedUsage := "Usage: example child nested [--enable] OUTPUT"
 
@@ -450,6 +721,8 @@ Global options:
 
 	_ = p.Parse([]string{"child", "nested", "value"})
 
+	assert.Equal(t, []string{"child", "nested"}, p.SubcommandNames())
+
 	var help bytes.Buffer
 	p.WriteHelp(&help)
 	assert.Equal(t, expectedHelp[1:], help.String())
@@ -471,7 +744,7 @@ func TestNonexistentSubcommand(t *testing.T) {
 	var args struct {
 		sub *struct{} `arg:"subcommand"`
 	}
-	p, err := NewParser(Config{}, &args)
+	p, err := NewParser(Config{Exit: func(int) {}}, &args)
 	require.NoError(t, err)
 
 	var b bytes.Buffer
@@ -522,6 +795,35 @@ Options:
 	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
 }
 
+func TestUsageWithEmptyPlaceholder(t *testing.T) {
+	expectedUsage := "Usage: example [-a] [--b] [--c]"
+
+	expectedHelp := `
+Usage: example [-a] [--b] [--c]
+
+Options:
+  -a                     some help for a
+  --b                    some help for b
+  --c, -c                some help for c
+  --help, -h             display this help and exit
+`
+	var args struct {
+		ShortOnly string `arg:"-a,--" placeholder:"" help:"some help for a"`
+		LongOnly  string `arg:"--b" placeholder:"" help:"some help for b"`
+		Both      string `arg:"-c,--c" placeholder:"" help:"some help for c"`
+	}
+	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())
+
+	var usage bytes.Buffer
+	p.WriteUsage(&usage)
+	assert.Equal(t, expectedUsage, strings.TrimSpace(usage.String()))
+}
+
 func TestUsageWithShortFirst(t *testing.T) {
 	expectedUsage := "Usage: example [-c CAT] [--dog DOG]"
 
@@ -630,7 +932,7 @@ error: something went wrong
 	p.Fail("something went wrong")
 
 	assert.Equal(t, expectedStdout[1:], stdout.String())
-	assert.Equal(t, -1, exitCode)
+	assert.Equal(t, 2, exitCode)
 }
 
 func TestFailSubcommand(t *testing.T) {
@@ -653,7 +955,7 @@ error: something went wrong
 	require.NoError(t, err)
 
 	assert.Equal(t, expectedStdout[1:], stdout.String())
-	assert.Equal(t, -1, exitCode)
+	assert.Equal(t, 2, exitCode)
 }
 
 type lengthOf struct {
@@ -687,3 +989,98 @@ Options:
 	p.WriteHelp(&help)
 	assert.Equal(t, expectedHelp[1:], help.String())
 }
+
+func TestHelpShowsSubcommandAliases(t *testing.T) {
+	expectedHelp := `
+Usage: example <command> [<args>]
+
+Options:
+  --help, -h             display this help and exit
+
+Commands:
+  remove, rm, r          remove something from somewhere
+  simple                 do something simple
+  halt, stop             stop now
+`
+
+	var args struct {
+		Remove *struct{} `arg:"subcommand:remove|rm|r" help:"remove something from somewhere"`
+		Simple *struct{} `arg:"subcommand" help:"do something simple"`
+		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]
+
+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"`
+	}
+
+	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]
+
+Positional arguments:
+  FOO                    this is a positional with an env variable [env: FOO]
+
+Options:
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		Foo string `arg:"positional,env:FOO" help:"this is a positional with an env variable"`
+	}
+
+	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 TestHelpShowsPositionalWithDefaultAndEnv(t *testing.T) {
+	expectedHelp := `
+Usage: example [FOO]
+
+Positional arguments:
+  FOO                    this is a positional with a default and an env variable [default: bar, env: FOO]
+
+Options:
+  --help, -h             display this help and exit
+`
+
+	var args struct {
+		Foo string `arg:"positional,env:FOO" default:"bar" help:"this is a positional with a default and an env variable"`
+	}
+
+	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())
+}

usage.go

@@ -9,40 +9,31 @@ import (
 // the width of the left column
 const colWidth = 25
 
-// Fail prints usage information to stderr and exits with non-zero status
+// Fail prints usage information to p.Config.Out and exits with status code 2.
 func (p *Parser) Fail(msg string) {
-	p.failWithSubcommand(msg, p.cmd)
+	p.FailSubcommand(msg)
 }
 
-// FailSubcommand prints usage information for a specified subcommand to stderr,
-// then exits with non-zero status. To write usage information for a top-level
+// FailSubcommand prints usage information for a specified subcommand to p.Config.Out,
+// then exits with status code 2. To write usage information for a top-level
 // subcommand, provide just the name of that subcommand. To write usage
 // information for a subcommand that is nested under another subcommand, provide
 // a sequence of subcommand names starting with the top-level subcommand and so
 // on down the tree.
 func (p *Parser) FailSubcommand(msg string, subcommand ...string) error {
-	cmd, err := p.lookupCommand(subcommand...)
+	err := p.WriteUsageForSubcommand(p.config.Out, subcommand...)
 	if err != nil {
 		return err
 	}
-	p.failWithSubcommand(msg, cmd)
-	return nil
-}
 
-// failWithSubcommand prints usage information for the given subcommand to stderr and exits with non-zero status
-func (p *Parser) failWithSubcommand(msg string, cmd *command) {
-	p.writeUsageForSubcommand(p.config.Out, cmd)
 	fmt.Fprintln(p.config.Out, "error:", msg)
-	p.config.Exit(-1)
+	p.config.Exit(2)
+	return nil
 }
 
 // WriteUsage writes usage information to the given writer
 func (p *Parser) WriteUsage(w io.Writer) {
-	cmd := p.cmd
-	if p.lastCmd != nil {
-		cmd = p.lastCmd
-	}
-	p.writeUsageForSubcommand(w, cmd)
+	p.WriteUsageForSubcommand(w, p.subcommand...)
 }
 
 // WriteUsageForSubcommand writes the usage information for a specified
@@ -55,12 +46,7 @@ func (p *Parser) WriteUsageForSubcommand(w io.Writer, subcommand ...string) erro
 	if err != nil {
 		return err
 	}
-	p.writeUsageForSubcommand(w, cmd)
-	return nil
-}
 
-// writeUsageForSubcommand writes usage information for the given subcommand
-func (p *Parser) writeUsageForSubcommand(w io.Writer, cmd *command) {
 	var positionals, longOptions, shortOptions []*spec
 	for _, spec := range cmd.specs {
 		switch {
@@ -73,22 +59,10 @@ func (p *Parser) writeUsageForSubcommand(w io.Writer, cmd *command) {
 		}
 	}
 
-	if p.version != "" {
-		fmt.Fprintln(w, p.version)
-	}
-
-	// make a list of ancestor commands so that we print with full context
-	var ancestors []string
-	ancestor := cmd
-	for ancestor != nil {
-		ancestors = append(ancestors, ancestor.name)
-		ancestor = ancestor.parent
-	}
-
 	// print the beginning of the usage string
-	fmt.Fprint(w, "Usage:")
-	for i := len(ancestors) - 1; i >= 0; i-- {
-		fmt.Fprint(w, " "+ancestors[i])
+	fmt.Fprintf(w, "Usage: %s", p.cmd.name)
+	for _, s := range subcommand {
+		fmt.Fprint(w, " "+s)
 	}
 
 	// write the option component of the usage message
@@ -149,47 +123,66 @@ func (p *Parser) writeUsageForSubcommand(w io.Writer, cmd *command) {
 	}
 
 	fmt.Fprint(w, "\n")
+	return nil
 }
 
-func printTwoCols(w io.Writer, left, help string, defaultVal string, envVal string) {
-	lhs := "  " + left
+// print prints a line like this:
+//
+//	--option FOO            A description of the option [default: 123]
+//
+// If the text on the left is longer than a certain threshold, the description is moved to the next line:
+//
+//	--verylongoptionoption VERY_LONG_VARIABLE
+//	                        A description of the option [default: 123]
+//
+// If multiple "extras" are provided then they are put inside a single set of square brackets:
+//
+//	--option FOO            A description of the option [default: 123, env: FOO]
+func print(w io.Writer, item, description string, bracketed ...string) {
+	lhs := "  " + item
 	fmt.Fprint(w, lhs)
-	if help != "" {
+	if description != "" {
 		if len(lhs)+2 < colWidth {
 			fmt.Fprint(w, strings.Repeat(" ", colWidth-len(lhs)))
 		} else {
 			fmt.Fprint(w, "\n"+strings.Repeat(" ", colWidth))
 		}
-		fmt.Fprint(w, help)
+		fmt.Fprint(w, description)
 	}
 
-	bracketsContent := []string{}
-
-	if defaultVal != "" {
-		bracketsContent = append(bracketsContent,
-			fmt.Sprintf("default: %s", defaultVal),
-		)
+	var brack string
+	for _, s := range bracketed {
+		if s != "" {
+			if brack != "" {
+				brack += ", "
+			}
+			brack += s
+		}
 	}
 
-	if envVal != "" {
-		bracketsContent = append(bracketsContent,
-			fmt.Sprintf("env: %s", envVal),
-		)
-	}
-
-	if len(bracketsContent) > 0 {
-		fmt.Fprintf(w, " [%s]", strings.Join(bracketsContent, ", "))
+	if brack != "" {
+		fmt.Fprintf(w, " [%s]", brack)
 	}
 	fmt.Fprint(w, "\n")
 }
 
+func withDefault(s string) string {
+	if s == "" {
+		return ""
+	}
+	return "default: " + s
+}
+
+func withEnv(env string) string {
+	if env == "" {
+		return ""
+	}
+	return "env: " + env
+}
+
 // WriteHelp writes the usage string followed by the full help string for each option
 func (p *Parser) WriteHelp(w io.Writer) {
-	cmd := p.cmd
-	if p.lastCmd != nil {
-		cmd = p.lastCmd
-	}
-	p.writeHelpForSubcommand(w, cmd)
+	p.WriteHelpForSubcommand(w, p.subcommand...)
 }
 
 // WriteHelpForSubcommand writes the usage string followed by the full help
@@ -202,12 +195,7 @@ func (p *Parser) WriteHelpForSubcommand(w io.Writer, subcommand ...string) error
 	if err != nil {
 		return err
 	}
-	p.writeHelpForSubcommand(w, cmd)
-	return nil
-}
 
-// writeHelp writes the usage string for the given subcommand
-func (p *Parser) writeHelpForSubcommand(w io.Writer, cmd *command) {
 	var positionals, longOptions, shortOptions, envOnlyOptions []*spec
 	var hasVersionOption bool
 	for _, spec := range cmd.specs {
@@ -216,6 +204,9 @@ func (p *Parser) writeHelpForSubcommand(w io.Writer, cmd *command) {
 			positionals = append(positionals, spec)
 		case spec.long != "":
 			longOptions = append(longOptions, spec)
+			if spec.long == "version" {
+				hasVersionOption = true
+			}
 		case spec.short != "":
 			shortOptions = append(shortOptions, spec)
 		case spec.short == "" && spec.long == "":
@@ -223,16 +214,36 @@ func (p *Parser) writeHelpForSubcommand(w io.Writer, cmd *command) {
 		}
 	}
 
+	// obtain a flattened list of options from all ancestors
+	// also determine if any ancestor has a version option spec
+	var globals []*spec
+	ancestor := cmd.parent
+	for ancestor != nil {
+		for _, spec := range ancestor.specs {
+			if spec.long == "version" {
+				hasVersionOption = true
+				break
+			}
+		}
+		globals = append(globals, ancestor.specs...)
+		ancestor = ancestor.parent
+	}
+
 	if p.description != "" {
 		fmt.Fprintln(w, p.description)
 	}
-	p.writeUsageForSubcommand(w, cmd)
+
+	if !hasVersionOption && p.version != "" {
+		fmt.Fprintln(w, p.version)
+	}
+
+	p.WriteUsageForSubcommand(w, subcommand...)
 
 	// write the list of positionals
 	if len(positionals) > 0 {
 		fmt.Fprint(w, "\nPositional arguments:\n")
 		for _, spec := range positionals {
-			printTwoCols(w, spec.placeholder, spec.help, "", "")
+			print(w, spec.placeholder, spec.help, withDefault(spec.defaultString), withEnv(spec.env))
 		}
 	}
 
@@ -244,28 +255,14 @@ func (p *Parser) writeHelpForSubcommand(w io.Writer, cmd *command) {
 		}
 		for _, spec := range longOptions {
 			p.printOption(w, spec)
-			if spec.long == "version" {
-				hasVersionOption = true
-			}
 		}
 	}
 
-	// obtain a flattened list of options from all ancestors
-	var globals []*spec
-	ancestor := cmd.parent
-	for ancestor != nil {
-		globals = append(globals, ancestor.specs...)
-		ancestor = ancestor.parent
-	}
-
 	// write the list of global options
 	if len(globals) > 0 {
 		fmt.Fprint(w, "\nGlobal options:\n")
 		for _, spec := range globals {
 			p.printOption(w, spec)
-			if spec.long == "version" {
-				hasVersionOption = true
-			}
 		}
 	}
 
@@ -296,13 +293,15 @@ func (p *Parser) writeHelpForSubcommand(w io.Writer, cmd *command) {
 	if len(cmd.subcommands) > 0 {
 		fmt.Fprint(w, "\nCommands:\n")
 		for _, subcmd := range cmd.subcommands {
-			printTwoCols(w, subcmd.name, subcmd.help, "", "")
+			names := append([]string{subcmd.name}, subcmd.aliases...)
+			print(w, strings.Join(names, ", "), subcmd.help)
 		}
 	}
 
 	if p.epilogue != "" {
 		fmt.Fprintln(w, "\n"+p.epilogue)
 	}
+	return nil
 }
 
 func (p *Parser) printOption(w io.Writer, spec *spec) {
@@ -314,7 +313,7 @@ func (p *Parser) printOption(w io.Writer, spec *spec) {
 		ways = append(ways, synopsis(spec, "-"+spec.short))
 	}
 	if len(ways) > 0 {
-		printTwoCols(w, strings.Join(ways, ", "), spec.help, spec.defaultString, spec.env)
+		print(w, strings.Join(ways, ", "), spec.help, withDefault(spec.defaultString), withEnv(spec.env))
 	}
 }
 
@@ -330,33 +329,14 @@ func (p *Parser) printEnvOnlyVar(w io.Writer, spec *spec) {
 		ways = append(ways, spec.help)
 	}
 
-	printTwoCols(w, spec.env, strings.Join(ways, " "), spec.defaultString, "")
-}
-
-// lookupCommand finds a subcommand based on a sequence of subcommand names. The
-// first string should be a top-level subcommand, the next should be a child
-// subcommand of that subcommand, and so on. If no strings are given then the
-// root command is returned. If no such subcommand exists then an error is
-// returned.
-func (p *Parser) lookupCommand(path ...string) (*command, error) {
-	cmd := p.cmd
-	for _, name := range path {
-		var found *command
-		for _, child := range cmd.subcommands {
-			if child.name == name {
-				found = child
-			}
-		}
-		if found == nil {
-			return nil, fmt.Errorf("%q is not a subcommand of %s", name, cmd.name)
-		}
-		cmd = found
-	}
-	return cmd, nil
+	print(w, spec.env, strings.Join(ways, " "), withDefault(spec.defaultString))
 }
 
 func synopsis(spec *spec, form string) string {
-	if spec.cardinality == zero {
+	// if the user omits the placeholder tag then we pick one automatically,
+	// but if the user explicitly specifies an empty placeholder then we
+	// leave out the placeholder in the help message
+	if spec.cardinality == zero || spec.placeholder == "" {
 		return form
 	}
 	return form + " " + spec.placeholder