docs/howto: use net.{ParseIP,IPString}

This adds a Commented CUE guide demonstrating how to use the built-in
functions net.ParseIP and net.IPString to convert between IP addresses
represented as strings and lists of bytes.

Implicit unification is used to quietly demonstrate the round-trip
nature of the conversions, but is deliberately not commented upon as the
example reads quite plainly without such comments. Equally, explicit
(&-based) unification is avoided. Both of these choices were made to
avoid confusing inexperienced CUE users, which I felt would be the case
if either explanatory comments or operator-based unification were used -
language features that are unrelated to the guide's subject matter.

Preview-Path: /docs/howto/use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Ie91bc90d013a6f87c4da26f62d37ff3f95086cde
Dispatch-Trailer: {"type":"trybot","CL":1174210,"patchset":4,"ref":"refs/changes/10/1174210/4","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/en.md

@@ -0,0 +1,47 @@
+---
+title: Using the built-in functions "net.ParseIP" and "net.IPString" to convert between IP address representations
+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 `net.ParseIP` and `net.IPString`
+to convert IPv4 and IPv6 addresses between their canonical string and
+list-of-bytes representations.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+# We use eval instead of export in order to keep the v[46]Bytes elements on the
+# same line. Using export significantly elongates the output, which doesn't
+# help the reader.
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "net"
+
+v4String: "198.51.100.14"
+v6String: "2001:db8:85a3::8a2e:370:7334"
+
+// Use net.ParseIP to convert IP addresses from strings to lists of bytes
+v4Bytes: net.ParseIP(v4String)
+v6Bytes: net.ParseIP(v6String)
+
+// Use net.IPString to convert IP addresses from lists of bytes to strings
+v4String: net.IPString(v4Bytes)
+v6String: net.IPString(v6Bytes)
+-- out --
+v4String: "198.51.100.14"
+v6String: "2001:db8:85a3::8a2e:370:7334"
+v4Bytes: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 198, 51, 100, 14]
+v6Bytes: [32, 1, 13, 184, 133, 163, 0, 0, 0, 0, 138, 46, 3, 112, 115, 52]
+{{{end}}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package

content/docs/howto/use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations": {
+					page: {
+						cache: {
+							code: {
+								cc: "3p3rxpqBZeUl5bvjTsWRFJOFdSZTmsZCctommIKqwFc="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations": {}

hugo/content/en/docs/howto/use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/index.md

@@ -0,0 +1,43 @@
+---
+title: Using the built-in functions "net.ParseIP" and "net.IPString" to convert between IP address representations
+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 `net.ParseIP` and `net.IPString`
+to convert IPv4 and IPv6 addresses between their canonical string and
+list-of-bytes representations.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "net"
+
+v4String: "198.51.100.14"
+v6String: "2001:db8:85a3::8a2e:370:7334"
+
+// Use net.ParseIP to convert IP addresses from strings to lists of bytes
+v4Bytes: net.ParseIP(v4String)
+v6Bytes: net.ParseIP(v6String)
+
+// Use net.IPString to convert IP addresses from lists of bytes to strings
+v4String: net.IPString(v4Bytes)
+v6String: net.IPString(v6Bytes)
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+v4String: "198.51.100.14"
+v6String: "2001:db8:85a3::8a2e:370:7334"
+v4Bytes: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 198, 51, 100, 14]
+v6Bytes: [32, 1, 13, 184, 133, 163, 0, 0, 0, 0, 138, 46, 3, 112, 115, 52]
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package