docs/howto: use strings.{Contains,Has{Suffix,Prefix}}

This adds a Commented CUE guide demonstrating how to use
strings.Contains, strings.HasSuffix, and strings.HasPrefix as field
validators.

Separate strings (containing the same example value) are used because
the alternative (combining all the example constraints onto a single
string) produced messy "cue vet" output, with each line containing a
constraint being mentioned multiple times, in the list of line numbers
that don't satisfy each and every broken constraint. The output from the
alternative presented here reads more cleanly.

Preview-Path: /docs/howto/use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Ic69bd84089587d9207732ffd424a9a7efae60d57
Dispatch-Trailer: {"type":"trybot","CL":1174729,"patchset":15,"ref":"refs/changes/29/1174729/15","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators/en.md

@@ -0,0 +1,74 @@
+---
+title: Using the built-in functions "strings.Contains", "strings.HasPrefix", and "strings.HasSuffix" as field validators
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`strings.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/strings#Contains),
+[`strings.HasPrefix`](https://pkg.go.dev/cuelang.org/go/pkg/strings#HasPrefix), and
+[`strings.HasSuffix`](https://pkg.go.dev/cuelang.org/go/pkg/strings#HasSuffix)
+to validate fields by asserting that their values match specific strings.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "strings"
+
+prefix:   "Some numbers (123) and letters"
+contains: "Some numbers (123) and letters"
+suffix:   "Some numbers (123) and letters"
+
+prefix: strings.HasPrefix("Some numbers")
+prefix: strings.HasPrefix(_incorrectPrefix)
+
+contains: strings.Contains("numbers") & strings.Contains("123")
+contains: strings.Contains("punctuation")
+
+suffix: strings.HasSuffix(_letters)
+suffix: strings.HasSuffix("incorrect suffix")
+
+// None of the built-in functions demonstrated here accept regular expressions.
+// Their parameters are interpreted as fixed strings, whether provided as
+// references or inline.
+contains: strings.Contains(".*")
+
+_incorrectPrefix: "incorrect prefix"
+_letters:         "letters"
+-- out --
+prefix: invalid value "Some numbers (123) and letters" (does not satisfy strings.HasPrefix("incorrect prefix")):
+    ./file.cue:10:9
+    ./file.cue:5:11
+    ./file.cue:9:9
+    ./file.cue:23:19
+contains: invalid value "Some numbers (123) and letters" (does not satisfy strings.Contains("punctuation")):
+    ./file.cue:13:11
+    ./file.cue:6:11
+    ./file.cue:12:11
+    ./file.cue:13:28
+    ./file.cue:21:11
+suffix: invalid value "Some numbers (123) and letters" (does not satisfy strings.HasSuffix("incorrect suffix")):
+    ./file.cue:16:9
+    ./file.cue:7:11
+    ./file.cue:15:9
+    ./file.cue:16:27
+contains: invalid value "Some numbers (123) and letters" (does not satisfy strings.Contains(".*")):
+    ./file.cue:21:11
+    ./file.cue:6:11
+    ./file.cue:12:11
+    ./file.cue:13:11
+    ./file.cue:21:28
+{{{end}}}
+
+## Related content
+
+- The [`strings`](https://pkg.go.dev/cuelang.org/go/pkg/strings) built-in package

content/docs/howto/use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators": {
+					page: {
+						cache: {
+							code: {
+								cc: "uizDpXW0gIGDUNQ7I8GxPnkCzNfPcL4Vftcwt6sTZsY="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators": {}

hugo/content/en/docs/howto/use-the-built-in-functions-strings-contains-strings-hasprefix-strings-hassuffix-as-field-validators/index.md

@@ -0,0 +1,73 @@
+---
+title: Using the built-in functions "strings.Contains", "strings.HasPrefix", and "strings.HasSuffix" as field validators
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`strings.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/strings#Contains),
+[`strings.HasPrefix`](https://pkg.go.dev/cuelang.org/go/pkg/strings#HasPrefix), and
+[`strings.HasSuffix`](https://pkg.go.dev/cuelang.org/go/pkg/strings#HasSuffix)
+to validate fields by asserting that their values match specific strings.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "strings"
+
+prefix:   "Some numbers (123) and letters"
+contains: "Some numbers (123) and letters"
+suffix:   "Some numbers (123) and letters"
+
+prefix: strings.HasPrefix("Some numbers")
+prefix: strings.HasPrefix(_incorrectPrefix)
+
+contains: strings.Contains("numbers") & strings.Contains("123")
+contains: strings.Contains("punctuation")
+
+suffix: strings.HasSuffix(_letters)
+suffix: strings.HasSuffix("incorrect suffix")
+
+// None of the built-in functions demonstrated here accept regular expressions.
+// Their parameters are interpreted as fixed strings, whether provided as
+// references or inline.
+contains: strings.Contains(".*")
+
+_incorrectPrefix: "incorrect prefix"
+_letters:         "letters"
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+prefix: invalid value "Some numbers (123) and letters" (does not satisfy strings.HasPrefix("incorrect prefix")):
+    ./file.cue:10:9
+    ./file.cue:5:11
+    ./file.cue:9:9
+    ./file.cue:23:19
+contains: invalid value "Some numbers (123) and letters" (does not satisfy strings.Contains("punctuation")):
+    ./file.cue:13:11
+    ./file.cue:6:11
+    ./file.cue:12:11
+    ./file.cue:13:28
+    ./file.cue:21:11
+suffix: invalid value "Some numbers (123) and letters" (does not satisfy strings.HasSuffix("incorrect suffix")):
+    ./file.cue:16:9
+    ./file.cue:7:11
+    ./file.cue:15:9
+    ./file.cue:16:27
+contains: invalid value "Some numbers (123) and letters" (does not satisfy strings.Contains(".*")):
+    ./file.cue:21:11
+    ./file.cue:6:11
+    ./file.cue:12:11
+    ./file.cue:13:11
+    ./file.cue:21:28
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`strings`](https://pkg.go.dev/cuelang.org/go/pkg/strings) built-in package