docs: Improved the documentation for the new functionality added in v…

…1.5.0.
northwood-labs · Nov 11, 2024 · 73be866 · 73be866
1 parent 6ee2d09
commit 73be866
Show file tree

Hide file tree

Showing 17 changed files with 165 additions and 18 deletions.
diff --git a/corefunc/base64gunzip.go b/corefunc/base64gunzip.go
@@ -29,6 +29,12 @@ Base64Gunzip is a function that decodes a Base64-encoded string, then
 decompresses the result with gzip. Supports both padded and non-padded Base64
 strings.
 
+Uses the "standard" Base64 alphabet as defined in RFC 4648 §4.
+<https://datatracker.ietf.org/doc/html/rfc4648#section-4>
+
+There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+is to avoid "decompression bomb" vulnerabilities.
+
 This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.

diff --git a/corefunc/cidr.go b/corefunc/cidr.go
@@ -23,8 +23,11 @@ import (
 )
 
 /*
-CIDRContains checks to see if an IP address or CIDR block is contained within
-another CIDR block.
+CIDRContains determines whether or not a given IP address, or an address prefix
+given in CIDR notation, is within a given IP network address prefix.
+
+Both arguments must belong to the same address family, either IPv4 or IPv6. A
+family mismatch will result in an error.
 
 This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other

diff --git a/corefunc/url.go b/corefunc/url.go
@@ -64,6 +64,10 @@ func URLParse(rawURL string, canon ...types.URLCanonicalizer) (*url.Url, error)
 /*
 URLDecode decodes a URL-encoded string.
 
+It can decode a wide range of characters, including those beyond the ASCII set.
+Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+byte-by-byte, ensuring correct decoding of multibyte characters.
+
 This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.

diff --git a/corefuncprovider/net_cidr_contains_data_source.go b/corefuncprovider/net_cidr_contains_data_source.go
@@ -80,8 +80,11 @@ func (d *netCidrContainsDataSource) Schema( // lint:no_dupe
 
 	resp.Schema = schema.Schema{
 		MarkdownDescription: strings.TrimSpace(dedent.Dedent(`
-		CIDRContains checks to see if an IP address or CIDR block is contained
-		within another CIDR block.
+		CIDRContains determines whether or not a given IP address, or an address prefix
+		given in CIDR notation, is within a given IP network address prefix.
+
+		Both arguments must belong to the same address family, either IPv4 or IPv6. A
+		family mismatch will result in an error.
 
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other

diff --git a/corefuncprovider/net_cidr_contains_function.go b/corefuncprovider/net_cidr_contains_function.go
@@ -67,8 +67,11 @@ func (f *netCidrContainsFunction) Definition( // lint:no_dupe
 	resp.Definition = function.Definition{
 		Summary: "CIDRContains checks to see if an IP address or CIDR block is contained within another CIDR block.",
 		MarkdownDescription: strings.TrimSpace(dedent.Dedent(`
-		CIDRContains checks to see if an IP address or CIDR block is contained
-		within another CIDR block.
+		CIDRContains determines whether or not a given IP address, or an address prefix
+		given in CIDR notation, is within a given IP network address prefix.
+
+		Both arguments must belong to the same address family, either IPv4 or IPv6. A
+		family mismatch will result in an error.
 
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other

diff --git a/corefuncprovider/str_base64_gunzip_data_source.go b/corefuncprovider/str_base64_gunzip_data_source.go
@@ -83,6 +83,12 @@ func (d *strBase64GunzipDataSource) Schema(
 		decompresses the result with gzip. Supports both padded and non-padded Base64
 		strings.
 
+		Uses the "standard" Base64 alphabet as defined in
+		[RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+
+		~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+		is to avoid "decompression bomb" vulnerabilities.
+
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other
 		Go code.

diff --git a/corefuncprovider/str_base64_gunzip_function.go b/corefuncprovider/str_base64_gunzip_function.go
@@ -71,6 +71,12 @@ func (f *strBase64GunzipFunction) Definition(
 		decompresses the result with gzip. Supports both padded and non-padded Base64
 		strings.
 
+		Uses the "standard" Base64 alphabet as defined in
+		[RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+
+		~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+		is to avoid "decompression bomb" vulnerabilities.
+
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other
 		Go code.

diff --git a/corefuncprovider/url_decode_data_source.go b/corefuncprovider/url_decode_data_source.go
@@ -81,6 +81,10 @@ func (d *urlDecodeDataSource) Schema(
 		MarkdownDescription: strings.TrimSpace(dedent.Dedent(`
 		URLDecode decodes a URL-encoded string.
 
+		It can decode a wide range of characters, including those beyond the ASCII set.
+		Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+		byte-by-byte, ensuring correct decoding of multibyte characters.
+
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other
 		Go code.

diff --git a/corefuncprovider/url_decode_function.go b/corefuncprovider/url_decode_function.go
@@ -69,6 +69,10 @@ func (f *urlDecodeFunction) Definition(
 		MarkdownDescription: strings.TrimSpace(dedent.Dedent(`
 		URLDecode decodes a URL-encoded string.
 
+		It can decode a wide range of characters, including those beyond the ASCII set.
+		Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+		byte-by-byte, ensuring correct decoding of multibyte characters.
+
 		-> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 		This also provides a 1:1 implementation that can be used with Terratest or other
 		Go code.

diff --git a/docs/data-sources/net_cidr_contains.md b/docs/data-sources/net_cidr_contains.md
@@ -2,8 +2,10 @@
 page_title: "corefunc_net_cidr_contains Data Source - corefunc"
 subcategory: ""
 description: |-
-  CIDRContains checks to see if an IP address or CIDR block is contained
-  within another CIDR block.
+  CIDRContains determines whether or not a given IP address, or an address prefix
+  given in CIDR notation, is within a given IP network address prefix.
+  Both arguments must belong to the same address family, either IPv4 or IPv6. A
+  family mismatch will result in an error.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -12,8 +14,11 @@ description: |-
 
 # corefunc_net_cidr_contains (Data Source)
 
-CIDRContains checks to see if an IP address or CIDR block is contained
-within another CIDR block.
+CIDRContains determines whether or not a given IP address, or an address prefix
+given in CIDR notation, is within a given IP network address prefix.
+
+Both arguments must belong to the same address family, either IPv4 or IPv6. A
+family mismatch will result in an error.
 
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other

diff --git a/docs/data-sources/str_base64_gunzip.md b/docs/data-sources/str_base64_gunzip.md
@@ -5,6 +5,10 @@ description: |-
   Base64Gunzip is a function that decodes a Base64-encoded string, then
   decompresses the result with gzip. Supports both padded and non-padded Base64
   strings.
+  Uses the "standard" Base64 alphabet as defined in
+  RFC 4648 §4 https://datatracker.ietf.org/doc/html/rfc4648#section-4.
+  ~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+  is to avoid "decompression bomb" vulnerabilities.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -17,6 +21,12 @@ Base64Gunzip is a function that decodes a Base64-encoded string, then
 decompresses the result with gzip. Supports both padded and non-padded Base64
 strings.
 
+Uses the "standard" Base64 alphabet as defined in
+[RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+
+~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+is to avoid "decompression bomb" vulnerabilities.
+
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.
@@ -38,10 +48,10 @@ data "corefunc_str_base64_gunzip" "str" {
 
 ### Required
 
-- `gzipped_base64` (String) A string of gzipped then Base64-encoded data.
+* `gzipped_base64` (String) A string of gzipped then Base64-encoded data.
 
 ### Read-Only
 
-- `value` (String) The Base64-decoded, then un-gzipped data.
+* `value` (String) The Base64-decoded, then un-gzipped data.
 
 <!-- Preview the provider docs with the Terraform registry provider docs preview tool: https://registry.terraform.io/tools/doc-preview -->
diff --git a/docs/data-sources/url_decode.md b/docs/data-sources/url_decode.md
@@ -3,6 +3,9 @@ page_title: "corefunc_url_decode Data Source - corefunc"
 subcategory: ""
 description: |-
   URLDecode decodes a URL-encoded string.
+  It can decode a wide range of characters, including those beyond the ASCII set.
+  Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+  byte-by-byte, ensuring correct decoding of multibyte characters.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -13,6 +16,10 @@ description: |-
 
 URLDecode decodes a URL-encoded string.
 
+It can decode a wide range of characters, including those beyond the ASCII set.
+Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+byte-by-byte, ensuring correct decoding of multibyte characters.
+
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.

diff --git a/docs/functions/net_cidr_contains.md b/docs/functions/net_cidr_contains.md
@@ -2,8 +2,10 @@
 page_title: "net_cidr_contains function - corefunc"
 subcategory: ""
 description: |-
-  CIDRContains checks to see if an IP address or CIDR block is contained
-  within another CIDR block.
+  CIDRContains determines whether or not a given IP address, or an address prefix
+  given in CIDR notation, is within a given IP network address prefix.
+  Both arguments must belong to the same address family, either IPv4 or IPv6. A
+  family mismatch will result in an error.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -12,8 +14,11 @@ description: |-
 
 # net_cidr_contains (function)
 
-CIDRContains checks to see if an IP address or CIDR block is contained
-within another CIDR block.
+CIDRContains determines whether or not a given IP address, or an address prefix
+given in CIDR notation, is within a given IP network address prefix.
+
+Both arguments must belong to the same address family, either IPv4 or IPv6. A
+family mismatch will result in an error.
 
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other

diff --git a/docs/functions/str_base64_gunzip.md b/docs/functions/str_base64_gunzip.md
@@ -5,6 +5,10 @@ description: |-
   Base64Gunzip is a function that decodes a Base64-encoded string, then
   decompresses the result with gzip. Supports both padded and non-padded Base64
   strings.
+  Uses the "standard" Base64 alphabet as defined in
+  RFC 4648 §4 https://datatracker.ietf.org/doc/html/rfc4648#section-4.
+  ~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+  is to avoid "decompression bomb" vulnerabilities.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -17,6 +21,12 @@ Base64Gunzip is a function that decodes a Base64-encoded string, then
 decompresses the result with gzip. Supports both padded and non-padded Base64
 strings.
 
+Uses the "standard" Base64 alphabet as defined in
+[RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+
+~> There is a data limit of 10 MiB (10485760 bytes) for the decompressed data. This
+is to avoid "decompression bomb" vulnerabilities.
+
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.
@@ -44,8 +54,6 @@ output "str" {
 
 ## Arguments
 
-
 1. `gzipped_base64` (String) A string of gzipped then Base64-encoded data.
 
-
 <!-- Preview the provider docs with the Terraform registry provider docs preview tool: https://registry.terraform.io/tools/doc-preview -->
diff --git a/docs/functions/url_decode.md b/docs/functions/url_decode.md
@@ -3,6 +3,9 @@ page_title: "url_decode function - corefunc"
 subcategory: ""
 description: |-
   URLDecode decodes a URL-encoded string.
+  It can decode a wide range of characters, including those beyond the ASCII set.
+  Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+  byte-by-byte, ensuring correct decoding of multibyte characters.
   -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
   This also provides a 1:1 implementation that can be used with Terratest or other
   Go code.
@@ -13,6 +16,10 @@ description: |-
 
 URLDecode decodes a URL-encoded string.
 
+It can decode a wide range of characters, including those beyond the ASCII set.
+Non-ASCII characters are first interpreted as UTF-8 bytes, then percent-decoded
+byte-by-byte, ensuring correct decoding of multibyte characters.
+
 -> This functionality is built into OpenTofu 1.8, but is missing in Terraform 1.9.
 This also provides a 1:1 implementation that can be used with Terratest or other
 Go code.

diff --git a/go.mod b/go.mod
@@ -25,11 +25,19 @@ require (
 
 require (
 	dario.cat/mergo v1.0.1 // indirect
+	github.com/BurntSushi/toml v1.4.0 // indirect
+	github.com/Kunde21/markdownfmt/v3 v3.1.0 // indirect
+	github.com/Masterminds/goutils v1.1.1 // indirect
+	github.com/Masterminds/semver/v3 v3.3.0 // indirect
+	github.com/Masterminds/sprig/v3 v3.3.0 // indirect
 	github.com/ProtonMail/go-crypto v1.1.2 // indirect
 	github.com/agext/levenshtein v1.2.3 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
+	github.com/armon/go-radix v1.0.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/bgentry/speakeasy v0.2.0 // indirect
 	github.com/bits-and-blooms/bitset v1.15.0 // indirect
+	github.com/bmatcuk/doublestar/v4 v4.7.1 // indirect
 	github.com/charmbracelet/bubbles v0.20.0 // indirect
 	github.com/charmbracelet/bubbletea v1.2.1 // indirect
 	github.com/charmbracelet/lipgloss v1.0.0 // indirect
@@ -41,6 +49,8 @@ require (
 	github.com/fatih/color v1.18.0 // indirect
 	github.com/go-test/deep v1.0.7 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/cli v1.1.6 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-checkpoint v0.5.0 // indirect
 	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
@@ -55,11 +65,14 @@ require (
 	github.com/hashicorp/logutils v1.0.0 // indirect
 	github.com/hashicorp/terraform-exec v0.21.0 // indirect
 	github.com/hashicorp/terraform-json v0.23.0 // indirect
+	github.com/hashicorp/terraform-plugin-docs v0.20.0 // indirect
 	github.com/hashicorp/terraform-plugin-sdk/v2 v2.35.0 // indirect
 	github.com/hashicorp/terraform-registry-address v0.2.3 // indirect
 	github.com/hashicorp/terraform-svchost v0.1.1 // indirect
 	github.com/hashicorp/yamux v0.1.2 // indirect
 	github.com/hexops/gotextdiff v1.0.3 // indirect
+	github.com/huandu/xstrings v1.5.0 // indirect
+	github.com/imdario/mergo v0.3.15 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/kr/pretty v0.3.1 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
@@ -78,14 +91,21 @@ require (
 	github.com/northwood-labs/archstring v0.0.0-20240514202917-e9357b4b91c8 // indirect
 	github.com/oklog/run v1.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/posener/complete v1.2.3 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rogpeppe/go-internal v1.13.1 // indirect
+	github.com/shopspring/decimal v1.4.0 // indirect
+	github.com/spf13/cast v1.7.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/vmihailenco/msgpack v4.0.4+incompatible // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/yuin/goldmark v1.7.8 // indirect
+	github.com/yuin/goldmark-meta v1.1.0 // indirect
 	github.com/zclconf/go-cty v1.15.0 // indirect
+	go.abhg.dev/goldmark/frontmatter v0.2.0 // indirect
 	golang.org/x/crypto v0.29.0 // indirect
+	golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f // indirect
 	golang.org/x/mod v0.22.0 // indirect
 	golang.org/x/net v0.31.0 // indirect
 	golang.org/x/sync v0.9.0 // indirect
@@ -96,5 +116,6 @@ require (
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20241104194629-dd2ea8efbc28 // indirect
 	google.golang.org/grpc v1.68.0 // indirect
 	google.golang.org/protobuf v1.35.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )