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 demonstrate the round-trip nature of the conversions. Explicit (&-based) unification is avoided in order not to risk overloading and confusing inexperienced CUE users. 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
cue-lang · Jan 22, 2024 · d559efe · d559efe
1 parent 47221f6
commit d559efe
Show file tree

Hide file tree

Showing 4 changed files with 121 additions and 0 deletions.
diff --git a/...-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/en.md b/...-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/en.md
@@ -0,0 +1,52 @@
+---
+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`](https://pkg.go.dev/cuelang.org/go/pkg/net#ParseIP) and
+[`net.IPString`](https://pkg.go.dev/cuelang.org/go/pkg/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.
+// Notice that we're assigning net.IPString's output to the same field names we
+// started with, above. By performing this cross-check we confirm that
+// net.IPString and net.ParseIP both act as the inverse function of the other.
+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
diff --git a/...in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/gen_cache.cue b/...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: "yE0obRypkVZETg4oJLDtPsr71OzzYwyY34J6FKSSSZ8="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/...uilt-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations/page.cue b/...uilt-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": {}
diff --git a/...nctions-net-parseip-net-ipstring-to-convert-ip-address-representations/index.md b/...nctions-net-parseip-net-ipstring-to-convert-ip-address-representations/index.md
@@ -0,0 +1,48 @@
+---
+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`](https://pkg.go.dev/cuelang.org/go/pkg/net#ParseIP) and
+[`net.IPString`](https://pkg.go.dev/cuelang.org/go/pkg/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.
+// Notice that we're assigning net.IPString's output to the same field names we
+// started with, above. By performing this cross-check we confirm that
+// net.IPString and net.ParseIP both act as the inverse function of the other.
+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
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		package site

		content: docs: howto: "use-the-built-in-functions-net-parseip-net-ipstring-to-convert-ip-address-representations": {}