docs/howto: disallow a specific field name

This adds a Commented CUE guide that demonstrates the use of an optional
field constraint with a literal _|_ in order to disallow a specific
field name from existing.

Preview-Path: /docs/howto/disallow-a-specific-field-name/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Id2387e46eb1462a38db268b9f68d2f11e84e5d1f
Dispatch-Trailer: {"type":"trybot","CL":1176893,"patchset":1,"ref":"refs/changes/93/1176893/1","targetBranch":"alpha"}

content/docs/howto/disallow-a-specific-field-name/en.md

@@ -0,0 +1,49 @@
+---
+title: Disallowing specific field names
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+A common way to prevent the existence of data fields is to rely on the
+**closedness** property that comes from the use of
+[**definitions**]({{< relref "docs/tour/basics/definitions" >}}) or the
+[**`close`**]({{< relref "docs/reference/glossary#close-built-in-function" >}})
+built-in function.
+
+In situations where neither of these language features is appropriate then the
+technique demonstrated in this
+[Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) may be used
+to prohibit specific data fields from existing.
+
+{{{with code "en" "emit"}}}
+! exec cue vet .:example data.yaml
+cmp stderr out
+-- file.cue --
+package example
+
+// This schema is open because we do not know
+// which additional fields might be present.
+name!:    string
+address!: string
+
+// We must not allow our data model to contain
+// people's ages, so we disallow the age field.
+age?: _|_
+-- data.yaml --
+name: Charlie Cartwright
+address: Ripon, North Yorkshire
+species: cat
+age: 15.5
+-- out --
+explicit error (_|_ literal) in source:
+    ./file.cue:10:7
+{{{end}}}
+
+## Related content
+
+- The CUE Tour: [**Definitions**]({{< relref "docs/tour/basics/definitions" >}})
+- Glossary:
+  [the **`close`** built-in function]({{< relref "docs/reference/glossary#close-built-in-function" >}})

content/docs/howto/disallow-a-specific-field-name/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"disallow-a-specific-field-name": {
+					page: {
+						cache: {
+							code: {
+								emit: "UVZNk4H9bbA49jSdLghUQ1oxzM6Zmg2sBYpnzqqLz4s="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/disallow-a-specific-field-name/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "disallow-a-specific-field-name": {}

hugo/content/en/docs/howto/disallow-a-specific-field-name/index.md

@@ -0,0 +1,51 @@
+---
+title: Disallowing specific field names
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+A common way to prevent the existence of data fields is to rely on the
+**closedness** property that comes from the use of
+[**definitions**]({{< relref "docs/tour/basics/definitions" >}}) or the
+[**`close`**]({{< relref "docs/reference/glossary#close-built-in-function" >}})
+built-in function.
+
+In situations where neither of these language features is appropriate then the
+technique demonstrated in this
+[Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) may be used
+to prohibit specific data fields from existing.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top-left" >}}
+package example
+
+// This schema is open because we do not know
+// which additional fields might be present.
+name!:    string
+address!: string
+
+// We must not allow our data model to contain
+// people's ages, so we disallow the age field.
+age?: _|_
+{{< /code-tab >}}
+{{< code-tab name="data.yaml" language="yaml"  area="top-right" >}}
+name: Charlie Cartwright
+address: Ripon, North Yorkshire
+species: cat
+age: 15.5
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet .:example data.yaml
+explicit error (_|_ literal) in source:
+    ./file.cue:10:7
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The CUE Tour: [**Definitions**]({{< relref "docs/tour/basics/definitions" >}})
+- Glossary:
+  [the **`close`** built-in function]({{< relref "docs/reference/glossary#close-built-in-function" >}})