cmd/cue: rewrite help vet

I was showing CUE to a new user recently and was trying to explain
that `cue vet` is a nice starting point, especially given how
one can use one-liners against schemas in the central registry.

However, the existing help text is verbose and long,
and it omits to mention commonly used features like --list
or how one can validate against a schema from a registry.

Do that rewrite. Keep it brief but useful; a new user does not need
to carefuly understand all the steps that `cue vet` goes through,
or all the different modes that the tool internally understands.

The text also had a hidden mistake: validating data files does not
require passing CUE files; one can use CUE packages just the same.
This was reinforced by all examples using CUE files for schemas.

End the rewrite with modern and realistic examples covering
the three use cases that we find most useful:

1) Checking that a set of packages contain no fatal errors
2) Validating local data against a local schema.
3) Validating local data against a schema in a package from a registry.

Overall we shave 17 lines off of `cue help vet`,
which just barely makes it fit on my screen without needing to scroll.

Signed-off-by: Daniel Martí <mvdan@mvdan.cc>
Change-Id: I003a20a89253d88d5442068d7b7f2740932e469f
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1230080
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
Unity-Result: CUE porcuepine <cue.porcuepine@gmail.com>
Reviewed-by: Paul Jolly <paul@myitcv.io>

Daniel Martí 4 months ago 9488f0c6 ba2ce990

+16 -33

1 changed file

expand all

cmd

cue

cmd

vet.go

+16 -33

cmd/cue/cmd/vet.go

··· 23 23 ) 24 24 25 25 const vetDoc = `The vet command validates CUE and other data files. 26 + The command is silent when it succeeds; otherwise it reports any errors found. 26 27 27 - The command is silent when it succeeds, emitting no output and an exit code of 28 - zero. Otherwise, errors are reported and the command returns a non-zero exit 29 - code. 28 + By default, vet ensures that the result of validation is concrete 29 + by reporting an error if any resulting regular fields have non-concrete values. 30 + Use -c=false to not require concreteness, or -c to show these error messages. 30 31 31 - vet starts by ensuring that there are no validation errors. If errors are found 32 - then they are reported and the command exits. 33 - 34 - If there are no validation errors then, by default, vet checks that the result 35 - of the evaluation is concrete. It reports an error if the evaluation contains 36 - any regular fields that have non-concrete values. 37 - Skip this step by specifying -c=false, which permits regular fields to have 38 - non-concrete values. Specify -c/-c=true to report errors mentioning which 39 - regular fields have non-concrete values. 40 - 41 - 42 - Checking non-CUE files 43 - 44 - Vet can also check non-CUE files. The following file formats are 45 - currently supported: 32 + vet can also validate non-CUE files in these file formats: 46 33 47 34 Format Extensions 48 35 JSON .json .jsonl .ndjson ··· 50 37 TOML .toml 51 38 TEXT .txt (validate a single string value) 52 39 53 - To activate this mode, the non-CUE files must be explicitly mentioned on the 54 - command line. There must also be at least one CUE file to hold the constraints. 55 - 56 - In this mode, each file will be verified against a CUE constraint. If the files 57 - contain multiple objects (such as using --- in YAML) then each object will be 58 - verified individually. 40 + Data files with multiple values, such as YAML with --- document separators, 41 + are validated one object at a time. Use --list to validate them as a list. 59 42 60 - By default, each file is checked against the root of the loaded CUE files. 61 - The -d can be used to only verify files against the result of an expression 62 - evaluated within the CUE files. This can be useful if the CUE files contain 63 - a set of definitions to pick from. 43 + By default, each file is checked against the root of the loaded CUE. 44 + Use the -d flag to select a schema at a particular expression instead. 64 45 65 46 Examples: 66 47 67 - # Check files against a CUE file: 48 + # Check that a collection of CUE packages has no errors. 49 + cue vet -c=false ./... 50 + 51 + # Check against a schema at the root of a CUE file: 68 52 cue vet -c foo.cue foo.yaml 69 53 70 - # Check files against a particular expression 71 - cue vet -c foo.cue lang/en.yaml lang/de.yaml -d '#Translation' 54 + # Check against a schema from a registry: 55 + cue vet -c -d '#Workflow' cue.dev/x/githubactions@latest workflow.yml 72 56 73 - More than one expression may be given using multiple -d flags. Each non-CUE 74 - file must match all expression values. 57 + The -d flag can be repeated to validate against multiple schemas at once. 75 58 ` 76 59 77 60 func newVetCmd(c *Command) *cobra.Command {

Configure Feed

Configure Feed