cmd/cue/cmd: update trim documentation to new syntax
Also remove mentions of template.
Fixes #119.
Change-Id: Id2053e029a607414090d85bf903447411858c0d0
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/3868
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/cmd/cue/cmd/testdata/script/trim.txt b/cmd/cue/cmd/testdata/script/trim.txt
index a20ddbf..155a14a 100644
--- a/cmd/cue/cmd/testdata/script/trim.txt
+++ b/cmd/cue/cmd/testdata/script/trim.txt
@@ -38,7 +38,7 @@
foo: multipath: {
t: [string]: {
- // Combined with the other template, we know the value must be 5 and
+ // Combined with the other constraints, we know the value must be 5 and
// thus the entry below can be eliminated.
x: >=5 & <=8
}
@@ -95,7 +95,7 @@
foo: multipath: {
t: [string]: {
- // Combined with the other template, we know the value must be 5 and
+ // Combined with the other constraints, we know the value must be 5 and
// thus the entry below can be eliminated.
x: >=5 & <=8
}
diff --git a/cmd/cue/cmd/trim.go b/cmd/cue/cmd/trim.go
index 5101c13..13aaff6 100644
--- a/cmd/cue/cmd/trim.go
+++ b/cmd/cue/cmd/trim.go
@@ -39,13 +39,15 @@
cmd := &cobra.Command{
Use: "trim",
Short: "remove superfluous fields",
- Long: `trim removes fields from structs that are already defined by a template
+ Long: `trim removes fields from structs that can be inferred from constraints
-A field, struct, or list is removed if it is implied by a template, a list type
-value, a comprehension or any other implied content. It will modify the files
-in place.
+A field, struct, or list is removed if it is implied by a constraint, such
+as from an optional field maching a required field, a list type value,
+a comprehension or any other implied content. It will modify the files in place.
+
Limitations
+
Removal is on a best effort basis. Some caveats:
- Fields in implied content may refer to fields within the struct in which
they are included, but are only resolved on a best-effort basis.
@@ -56,13 +58,13 @@
Examples:
$ cat <<EOF > foo.cue
- light <Name>: {
+ light: [string]: {
room: string
brightnessOff: *0.0 | >=0 & <=100.0
brightnessOn: *100.0 | >=0 & <=100.0
}
- light ceiling50: {
+ light: ceiling50: {
room: "MasterBedroom"
brightnessOff: 0.0 // this line
brightnessOn: 100.0 // and this line will be removed
@@ -71,13 +73,13 @@
$ cue trim foo.cue
$ cat foo.cue
- light <Name>: {
+ light: [string]: {
room: string
brightnessOff: *0.0 | >=0 & <=100.0
brightnessOn: *100.0 | >=0 & <=100.0
}
- light ceiling50: {
+ light: ceiling50: {
room: "MasterBedroom"
}
@@ -214,7 +216,8 @@
}
case *ast.Field:
- if _, ok := x.Label.(*ast.TemplateLabel); ok {
+ switch x.Label.(type) {
+ case *ast.TemplateLabel, *ast.ListLit:
t.markAlwaysGen(x.Value, false)
}
@@ -234,7 +237,7 @@
t.fromComp[n] = true
}
if x, ok := n.(*ast.Ident); ok && n != first {
- // Also mark any value used within a template.
+ // Also mark any value used within a constraint from an optional field.
if x.Node != nil {
// fmt.Println("MARKED", internal.DebugStr(x.Node),
// "by", internal.DebugStr(first))
@@ -271,7 +274,7 @@
}
// trim strips fields from structs that would otherwise be generated by implied
-// content, such as templates, comprehensions, and list types.
+// content, such as optional fields turned required, comprehensions, and list types.
//
// The algorithm walks the tree with two values in parallel: one for the full
// configuration, and one for implied content. For each node in the tree it
@@ -282,10 +285,10 @@
// - Fields in the implied content may refer to fields in the complete config.
// To support this, incomplete fields are detected and evaluated within the
// configuration.
-// - Templates are instantiated as a result of the declaration of concrete
-// sibling fields. Such fields should not be removed even if the instantiated
-// template completely subsumes such fields as the reason to instantiate
-// the template will disappear with it.
+// - Values of optional fields are instantiated as a result of the declaration
+// of concrete sibling fields. Such fields should not be removed even if the
+// instantiated constraint completely subsumes such fields as the reason to
+// apply the optional constraint will disappear with it.
// - As the parallel structure is different, it may resolve to different
// default values. There is no support yet for selecting defaults of a value
// based on another value without doing a full unification. So for now we
@@ -313,7 +316,7 @@
}
// Collect generated nodes.
- // Only keep the good parts of the template.
+ // Only keep the good parts of the optional constraint.
// Incoming structs may be incomplete resulting in errors. It is safe
// to ignore these. If there is an actual error, it will manifest in
// the evaluation of v.
@@ -330,7 +333,7 @@
switch v.Kind() {
case cue.StructKind:
- // TODO: merge template preprocessing with that of fields.
+ // TODO: merge optional field preprocessing with that of fields.
// Identify generated components and unify them with the mixin value.
exists := false
