Various changes

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

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"`
+		Input    string   `arg:"positional" placeholder:"SRC"`
-		Output   []string `arg:"positional"`
+		Output   []string `arg:"positional" placeholder:"DST"`
-		Verbose  bool     `arg:"-v" help:"verbosity level"`
+		Optimize int      `arg:"-O" help:"optimization level" placeholder:"LEVEL"`
-		Dataset  string   `help:"dataset to use"`
+		MaxJobs  int      `arg:"-j" help:"maximum number of simultaneous jobs" placeholder:"N"`
-		Optimize int      `arg:"-O,help:optimization level,dataname:LEVEL"`
-		MaxJobs  int      `arg:"-j,help:maximum number of simultaneous jobs,dataname: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
+	//   SRC
-	//   OUTPUT
+	//   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
 }
 

parse.go

@@ -44,19 +44,19 @@ func (p path) Child(child string) path {
 
 // spec represents a command line option
 type spec struct {
-	dest       path
+	dest        path
-	typ        reflect.Type
+	typ         reflect.Type
-	long       string
+	long        string
-	short      string
+	short       string
-	multiple   bool
+	multiple    bool
-	required   bool
+	required    bool
-	positional bool
+	positional  bool
-	separate   bool
+	separate    bool
-	help       string
+	help        string
-	env        string
+	env         string
-	boolean    bool
+	boolean     bool
-	defaultVal string // default value for this option
+	defaultVal  string // default value for this option
-	dataname   string // name of the data in help
+	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 == "" {
+		placeholder, hasPlaceholder := field.Tag.Lookup("placeholder")
-			spec.dataname = strings.ToUpper(spec.long)
+		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

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"`

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 {