docs/howto: use list.SortStrings/IsSortedStrings

This adds a Commented CUE guide on the matched pair of list.SortStrings
and list.IsSortedStrings.

Unusually for a Commented CUE guide, 2 separate examples are required.

This is because we would ideally show both the happy-path result of all
3 function calls (SortStrings; IsSortedStrings boolean assignment;
IsSortedStrings field validator mode) and also IsSortedStrings field
validator mode when it fails. Only cue-eval-i lets us combine failure
and success messages in one command's output, and it doesn't work in
this situation.

Here's an example txtar that demonstrates the didactic problem with
combining these 2 functions into a single example:

    exec cue eval -i file.cue
    cmp stdout out
    -- file.cue --
    import "list"

    unsorted: ["c", "b", "a"]
    sorted: list.SortStrings(unsorted)

    sorted:   list.IsSortedStrings
    unsorted: list.IsSortedStrings

    testSorted:   list.IsSortedStrings(sorted)
    testUnsorted: list.IsSortedStrings(unsorted)
    -- out --
    unsorted:     _|_ // unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings) (and 1 more errors)
    sorted:       _|_ // unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings) (and 3 more errors)
    testSorted:   _|_ // unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings) (and 7 more errors)
    testUnsorted: _|_ // unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings) (and 3 more errors)

I believe this is just an unfortunate side effect of cue-eval-i behaving
as intended, so a cue-lang/cue issue hasn't been raised to improve this
output.

Preview-Path: /docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I8938f36f597d3efe88b66b1b78f218db714ab33d
Dispatch-Trailer: {"type":"trybot","CL":1174391,"patchset":3,"ref":"refs/changes/91/1174391/3","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/en.md

@@ -0,0 +1,63 @@
+---
+title: Using the built-in functions "list.SortStrings" and "list.IsSortedStrings" to sort and test lists of strings
+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 `list.SortStrings` to sort lists
+of strings, and `list.IsSortedStrings` to test that list of strings are sorted.
+
+{{{with code "en" "cc1"}}}
+#location left right
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+unsorted: ["z", "Z", "a", "AAA", "42", "!£$%^&*"]
+sorted: list.SortStrings(unsorted)
+
+// IsSortedStrings returns a boolean, which may be
+// assigned as shown here, or used as a validator
+// as shown in the other example on this page.
+testUnsorted: list.IsSortedStrings(unsorted)
+testSorted:   list.IsSortedStrings(sorted)
+-- out --
+unsorted: ["z", "Z", "a", "AAA", "42", "!£$%^&*"]
+sorted: ["!£$%^&*", "42", "AAA", "Z", "a", "z"]
+testUnsorted: false
+testSorted:   true
+{{{end}}}
+
+{{{with code "en" "cc2"}}}
+#location top bottom
+
+! exec cue eval
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+unsorted: ["c", "b", "a"]
+sorted: ["a", "b", "c"]
+
+// IsSortedStrings can be used as a field validator.
+unsorted: list.IsSortedStrings
+sorted:   list.IsSortedStrings
+-- out --
+unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings):
+    ./file.cue:5:11
+    ./file.cue:9:11
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/gen_cache.cue

@@ -0,0 +1,19 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-list-sortstrings-list-issortedstrings": {
+					page: {
+						cache: {
+							code: {
+								cc1: "33swRimo9cq09Can9S03IwsgWTaJdZ8m406VcRGR5K0="
+								cc2: "9h1n1vI4XC8oe4SEDdTos9I4s2aT4IznZhM/uVoVi+8="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-list-sortstrings-list-issortedstrings": {}

hugo/content/en/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/index.md

@@ -0,0 +1,61 @@
+---
+title: Using the built-in functions "list.SortStrings" and "list.IsSortedStrings" to sort and test lists of strings
+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 `list.SortStrings` to sort lists
+of strings, and `list.IsSortedStrings` to test that list of strings are sorted.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="left" >}}
+package example
+
+import "list"
+
+unsorted: ["z", "Z", "a", "AAA", "42", "!£$%^&*"]
+sorted: list.SortStrings(unsorted)
+
+// IsSortedStrings returns a boolean, which may be
+// assigned as shown here, or used as a validator
+// as shown in the other example on this page.
+testUnsorted: list.IsSortedStrings(unsorted)
+testSorted:   list.IsSortedStrings(sorted)
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="right" >}}
+$ cue eval
+unsorted: ["z", "Z", "a", "AAA", "42", "!£$%^&*"]
+sorted: ["!£$%^&*", "42", "AAA", "Z", "a", "z"]
+testUnsorted: false
+testSorted:   true
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+unsorted: ["c", "b", "a"]
+sorted: ["a", "b", "c"]
+
+// IsSortedStrings can be used as a field validator.
+unsorted: list.IsSortedStrings
+sorted:   list.IsSortedStrings
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings):
+    ./file.cue:5:11
+    ./file.cue:9:11
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package