docs/howto: use regexp.ReplaceAll{,Literal}

This adds a Commented CUE guide that demonstrates regexp.ReplaceAll and
regexp.ReplaceAllLiteral.

Preview-Path: /docs/howto/use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: If6dd72cf16b462e3a1199e0d114200f364161d5a
Dispatch-Trailer: {"type":"trybot","CL":1174750,"patchset":3,"ref":"refs/changes/50/1174750/3","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings/en.md

@@ -0,0 +1,63 @@
+---
+title: Using the built-in functions "regexp.ReplaceAll" and "regexp.ReplaceAllLiteral" to modify 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
+[`regexp.ReplaceAll`](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAll)
+and
+[`regexp.ReplaceAllLiteral`](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAllLiteral)
+to modify strings using various features of regular expressions.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "regexp"
+
+// regexp.ReplaceAll and regexp.ReplaceAllLiteral require 3 parameters:
+// - the regular expression pattern to search for
+// - the string to search through
+// - the replacement to be made if the pattern is found
+inlineRA:  regexp.ReplaceAll("[aeiou]", "the quick brown fox jumps over the lazy dog", "X")
+inlineRAL: regexp.ReplaceAllLiteral("[aeiou]", "the quick brown fox jumps over the lazy dog", "X")
+
+// regexp.ReplaceAll's 3rd parameter (the replacement) is a template, which
+// optionally includes features such as match indexes and capture groups.
+// See "Related content", below, for full documentation of the template format.
+// Here we search for the letter "o", followed by one of "uvwxyz", and replace
+// both characters with the second of the pair.
+oPairRA: regexp.ReplaceAll("o([uvwxyz])", _src, "$1")
+
+// regexp.ReplaceAllLiteral's 3rd parameter (the replacement) is used literally.
+oPairRAL: regexp.ReplaceAllLiteral("o([uvwxyz])", _src, "$1")
+
+// Here we search for a vowel, followed by any two letters, at the end of a word.
+// We remove the vowel by replacing the entire match with the contents of a
+// named capture group that contains only the two trailing letters.
+featuresRA: regexp.ReplaceAll("[aeiou](?P<twoLetters>\\w{2}\\b)", _src, "$twoLetters")
+
+// All examples in this guide use _src as their source string.
+_src: "the quick brown fox jumps over the lazy dog"
+-- out --
+inlineRA:   "thX qXXck brXwn fXx jXmps XvXr thX lXzy dXg"
+inlineRAL:  "thX qXXck brXwn fXx jXmps XvXr thX lXzy dXg"
+oPairRA:    "the quick brwn fx jumps ver the lazy dog"
+oPairRAL:   "the quick br$1n f$1 jumps $1er the lazy dog"
+featuresRA: "the quck brwn fox jumps over the lzy dog"
+{{{end}}}
+
+## Related content
+
+- Documentation for `regex.ReplaceAll`'s
+  [replacement templates](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAll)
+- The [`regexp`](https://pkg.go.dev/cuelang.org/go/pkg/regexp) built-in package

content/docs/howto/use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings": {
+					page: {
+						cache: {
+							code: {
+								cc: "5VhEhoStkuLE2i03fhFa89eA7OE716OdLhXSfXzS1KY="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings": {}

hugo/content/en/docs/howto/use-the-built-in-functions-regexp-replaceall-regexp-replaceallliteral-to-modify-strings/index.md

@@ -0,0 +1,62 @@
+---
+title: Using the built-in functions "regexp.ReplaceAll" and "regexp.ReplaceAllLiteral" to modify 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
+[`regexp.ReplaceAll`](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAll)
+and
+[`regexp.ReplaceAllLiteral`](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAllLiteral)
+to modify strings using various features of regular expressions.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "regexp"
+
+// regexp.ReplaceAll and regexp.ReplaceAllLiteral require 3 parameters:
+// - the regular expression pattern to search for
+// - the string to search through
+// - the replacement to be made if the pattern is found
+inlineRA:  regexp.ReplaceAll("[aeiou]", "the quick brown fox jumps over the lazy dog", "X")
+inlineRAL: regexp.ReplaceAllLiteral("[aeiou]", "the quick brown fox jumps over the lazy dog", "X")
+
+// regexp.ReplaceAll's 3rd parameter (the replacement) is a template, which
+// optionally includes features such as match indexes and capture groups.
+// See "Related content", below, for full documentation of the template format.
+// Here we search for the letter "o", followed by one of "uvwxyz", and replace
+// both characters with the second of the pair.
+oPairRA: regexp.ReplaceAll("o([uvwxyz])", _src, "$1")
+
+// regexp.ReplaceAllLiteral's 3rd parameter (the replacement) is used literally.
+oPairRAL: regexp.ReplaceAllLiteral("o([uvwxyz])", _src, "$1")
+
+// Here we search for a vowel, followed by any two letters, at the end of a word.
+// We remove the vowel by replacing the entire match with the contents of a
+// named capture group that contains only the two trailing letters.
+featuresRA: regexp.ReplaceAll("[aeiou](?P<twoLetters>\\w{2}\\b)", _src, "$twoLetters")
+
+// All examples in this guide use _src as their source string.
+_src: "the quick brown fox jumps over the lazy dog"
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+inlineRA:   "thX qXXck brXwn fXx jXmps XvXr thX lXzy dXg"
+inlineRAL:  "thX qXXck brXwn fXx jXmps XvXr thX lXzy dXg"
+oPairRA:    "the quick brwn fx jumps ver the lazy dog"
+oPairRAL:   "the quick br$1n f$1 jumps $1er the lazy dog"
+featuresRA: "the quck brwn fox jumps over the lzy dog"
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- Documentation for `regex.ReplaceAll`'s
+  [replacement templates](https://pkg.go.dev/cuelang.org/go/pkg/regexp#ReplaceAll)
+- The [`regexp`](https://pkg.go.dev/cuelang.org/go/pkg/regexp) built-in package