diff --git a/README.md b/README.md index 1f02559..ae0c567 100644 --- a/README.md +++ b/README.md @@ -148,6 +148,32 @@ var args struct { arg.MustParse(&args) ``` +### Custom placeholders + +```go +var args struct { + Input string `arg:"positional" placeholder:"SRC"` + Output []string `arg:"positional" placeholder:"DST"` + Optimize int `arg:"-O" help:"optimization level" placeholder:"LEVEL"` + MaxJobs int `arg:"-j" help:"maximum number of simultaneous jobs" placeholder:"N"` +} +arg.MustParse(&args) +``` +```shell +$ ./example -h +Usage: example [--optimize LEVEL] [--maxjobs N] SRC [DST [DST ...]] + +Positional arguments: + SRC + DST + +Options: + --optimize LEVEL, -O LEVEL + optimization level + --maxjobs N, -j N maximum number of simultaneous jobs + --help, -h display this help and exit +``` + ### Default values (before v1.2) ```go diff --git a/example_test.go b/example_test.go index 3f7f2ab..8f308f1 100644 --- a/example_test.go +++ b/example_test.go @@ -135,18 +135,16 @@ func Example_helpText() { // --help, -h display this help and exit } -// This example shows the usage string generated by go-arg with custom datanames +// This example shows the usage string generated by go-arg with customized placeholders func Example_helpDataname() { // These are the args you would pass in on the command line os.Args = split("./example --help") var args struct { - Input string `arg:"positional,dataname:DATAFILE"` - Output []string `arg:"positional"` - Verbose bool `arg:"-v" help:"verbosity level"` - Dataset string `help:"dataset to use"` - Optimize int `arg:"-O,help:optimization level,dataname:LEVEL"` - MaxJobs int `arg:"-j,help:maximum number of simultaneous jobs,dataname:N"` + Input string `arg:"positional" placeholder:"SRC"` + Output []string `arg:"positional" placeholder:"DST"` + Optimize int `arg:"-O" help:"optimization level" placeholder:"LEVEL"` + MaxJobs int `arg:"-j" help:"maximum number of simultaneous jobs" placeholder:"N"` } // This is only necessary when running inside golang's runnable example harness @@ -156,18 +154,16 @@ func Example_helpDataname() { // output: - // Usage: example [--verbose] [--dataset DATASET] [--optimize LEVEL] [--maxjobs N] DATAFILE [OUTPUT [OUTPUT ...]] + // Usage: example [--optimize LEVEL] [--maxjobs N] SRC [DST [DST ...]] // Positional arguments: - // DATAFILE - // OUTPUT + // SRC + // DST // Options: - // --verbose, -v verbosity level - // --dataset DATASET dataset to use // --optimize LEVEL, -O LEVEL // optimization level - // --maxjobs N, -j N maximum number of simultanious jobs + // --maxjobs N, -j N maximum number of simultaneous jobs // --help, -h display this help and exit } diff --git a/parse.go b/parse.go index 3e1d719..5d3edec 100644 --- a/parse.go +++ b/parse.go @@ -44,19 +44,19 @@ func (p path) Child(child string) path { // spec represents a command line option type spec struct { - dest path - typ reflect.Type - long string - short string - multiple bool - required bool - positional bool - separate bool - help string - env string - boolean bool - defaultVal string // default value for this option - dataname string // name of the data in help + dest path + typ reflect.Type + long string + short string + multiple bool + required bool + positional bool + separate bool + help string + env string + boolean bool + defaultVal string // default value for this option + placeholder string // name of the data in help } // command represents a named subcommand, or the top-level command @@ -345,8 +345,11 @@ func cmdFromStruct(name string, dest path, t reflect.Type) (*command, error) { } } - if spec.dataname == "" { - spec.dataname = strings.ToUpper(spec.long) + placeholder, hasPlaceholder := field.Tag.Lookup("placeholder") + if hasPlaceholder { + spec.placeholder = placeholder + } else { + spec.placeholder = strings.ToUpper(spec.long) } // Check whether this field is supported. It's good to do this here rather than diff --git a/parse_test.go b/parse_test.go index 47e9ccd..f75d1a7 100644 --- a/parse_test.go +++ b/parse_test.go @@ -220,6 +220,17 @@ func TestLongFlag(t *testing.T) { assert.Equal(t, "xyz", args.Foo) } +func TestPlaceholder(t *testing.T) { + var args struct { + Input string `arg:"positional" placeholder:"SRC"` + Output []string `arg:"positional" placeholder:"DST"` + Optimize int `arg:"-O" placeholder:"LEVEL"` + MaxJobs int `arg:"-j" placeholder:"N"` + } + err := parse("-O 5 --maxjobs 2 src dest1 dest2", &args) + assert.NoError(t, err) +} + func TestCaseSensitive(t *testing.T) { var args struct { Lower bool `arg:"-v"` diff --git a/usage.go b/usage.go index 372b77d..57935fd 100644 --- a/usage.go +++ b/usage.go @@ -80,12 +80,12 @@ func (p *Parser) writeUsageForCommand(w io.Writer, cmd *command) { if !spec.required { fmt.Fprint(w, "[") } - fmt.Fprintf(w, "%s [%s ...]", spec.dataname, spec.dataname) + fmt.Fprintf(w, "%s [%s ...]", spec.placeholder, spec.placeholder) if !spec.required { fmt.Fprint(w, "]") } } else { - fmt.Fprint(w, spec.dataname) + fmt.Fprint(w, spec.placeholder) } } fmt.Fprint(w, "\n") @@ -133,7 +133,7 @@ func (p *Parser) writeHelpForCommand(w io.Writer, cmd *command) { if len(positionals) > 0 { fmt.Fprint(w, "\nPositional arguments:\n") for _, spec := range positionals { - printTwoCols(w, spec.dataname, spec.help, "") + printTwoCols(w, spec.placeholder, spec.help, "") } } @@ -179,7 +179,7 @@ func synopsis(spec *spec, form string) string { if spec.boolean { return form } - return form + " " + spec.dataname + return form + " " + spec.placeholder } func ptrTo(s string) *string {