cmd/cue/cmd: add injection help topic

Also changes the flag name from --tags to --inject

Change-Id: Ifb35aed2d6d22fece17621a841a58c8a936e12c7
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/5407
Reviewed-by: Paul Jolly <paul@myitcv.org.uk>

cmd/cue/cmd/cmd.go

@@ -233,7 +233,7 @@ Ensure commands are defined in a "_tool.cue" file.
 	}
 
 	cmd.Flags().SetInterspersed(false)
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd

cmd/cue/cmd/common.go

@@ -365,7 +365,7 @@ func parseArgs(cmd *Command, args []string, cfg *config) (p *buildPlan, err erro
 	if builds == nil {
 		return nil, errors.Newf(token.NoPos, "invalid args")
 	}
-	decorateInstances(cmd, flagTags.StringArray(cmd), builds)
+	decorateInstances(cmd, flagInject.StringArray(cmd), builds)
 
 	p = &buildPlan{cfg: cfg, cmd: cmd, forceOrphanProcessing: cfg.loadCfg.DataFiles}
 

cmd/cue/cmd/def.go

@@ -43,7 +43,7 @@ The --expression flag is used to only print parts of a configuration.
 	cmd.Flags().BoolP(string(flagAttributes), "A", false,
 		"display field attributes")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	// TODO: Option to include comments in output.

cmd/cue/cmd/eval.go

@@ -72,7 +72,7 @@ Examples:
 	cmd.Flags().BoolP(string(flagAll), "a", false,
 		"show optional and hidden fields")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	// TODO: Option to include comments in output.

cmd/cue/cmd/export.go

@@ -97,7 +97,7 @@ yaml    output as YAML
 
 	cmd.Flags().StringArrayP(string(flagExpression), "e", nil, "export this expression only")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd

cmd/cue/cmd/flags.go

@@ -30,7 +30,7 @@ const (
 	flagIgnore    flagName = "ignore"
 	flagSimplify  flagName = "simplify"
 	flagPackage   flagName = "package"
-	flagTags      flagName = "tags"
+	flagInject    flagName = "inject"
 
 	flagExpression flagName = "expression"
 	flagSchema     flagName = "schema"

cmd/cue/cmd/help.go

@@ -19,7 +19,7 @@ import (
 )
 
 // TODO: intersperse the examples at the end of the texts in the
-// body of text to make things more concerte for the user early on?
+// body of text to make things more concrete for the user early on?
 // The current approach works will if users just print the text without
 // "more" or "less", in which case the examples show more prominently.
 // The user can then scroll up to get a more in-depth explanation. But is
@@ -30,6 +30,7 @@ func newHelpTopics(c *Command) []*cobra.Command {
 		inputsHelp,
 		flagsHelp,
 		filetypeHelp,
+		injectHelp,
 	}
 }
 
@@ -254,6 +255,51 @@ $ cue export -e name -o=text:foo
 `,
 }
 
+var injectHelp = &cobra.Command{
+	Use:   "injection",
+	Short: "inject values from the command line",
+	Long: `Many of the cue commands allow injecting values
+from the command line using the --inject/-t flag.
+
+The injection mechanism allows values to be injected into fields
+that are marked with a "tag" attribute. For any field of the form
+
+   field: x @tag(key)
+
+an "--inject key=value" flag will modify the field to
+
+   field: x & "value"
+
+By default, the injected value is treated as a string.
+Alternatively, the "type" option allows a value to be interpreted
+as an int, number, or bool. For instance, for a field
+
+   field: x @tag(key,type=int)
+
+the flag "-t key=2" modifies the field to
+
+   field: x & 2
+
+Valid values for type are "int", "number", "bool", and "string".
+
+A tag attribute can also define shorthand values, which can be
+injected into the fields without having to specify the key. For
+instance, for
+
+   environment: string @tag(env,short=prod|staging)
+
+"-t prod" sets the environment field to the value "prod". It is
+still possible to specify "-t env=prod" in this case.
+
+Use the usual CUE constraints to limit the possible values of a
+field. For instance
+
+   environment: "prod" | "staging" @tag(env,short=prod|staging)
+
+ensures the user may only specify "prod" or "staging".
+`,
+}
+
 // TODO: tags
 // - doc/nodoc
 // - attr/noattr
@@ -263,7 +309,4 @@ $ cue export -e name -o=text:foo
 // - textpb
 // - binpb
 
-// TODO: document
-// <tag>['='<value>]{'+'<tag>['='<value>]}':'
-
 // TODO: cue.mod help topic

cmd/cue/cmd/root.go

@@ -254,7 +254,7 @@ func New(args []string) (cmd *Command, err error) {
 	if err != nil {
 		return nil, err
 	}
-	tags, err := cmd.cmd.Flags().GetStringArray(string(flagTags))
+	tags, err := cmd.cmd.Flags().GetStringArray(string(flagInject))
 	if err != nil {
 		return nil, err
 	}
@@ -303,7 +303,7 @@ func addSubcommands(cmd *Command, sub map[string]*subSpec, args []string, isHelp
 				if err != nil {
 					return err
 				}
-				tags, err = cmd.cmd.Flags().GetStringArray(string(flagTags))
+				tags, err = cmd.cmd.Flags().GetStringArray(string(flagInject))
 				if err != nil {
 					return err
 				}

cmd/cue/cmd/testdata/script/help_cmd.txt

@@ -221,8 +221,8 @@ Available Commands:
   hello       say hello to someone
 
 Flags:
-  -h, --help               help for cmd
-  -t, --tags stringArray   set the value of a tagged field
+  -h, --help                 help for cmd
+  -t, --inject stringArray   set the value of a tagged field
 
 Global Flags:
   -E, --all-errors   print all available errors

cmd/cue/cmd/vet.go

@@ -74,7 +74,7 @@ func newVetCmd(c *Command) *cobra.Command {
 	cmd.Flags().BoolP(string(flagConcrete), "c", false,
 		"require the evaluation to be concrete")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd