From a4910130542e01ce0f93b6ad448b9a23c0a48116 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Sun, 13 May 2018 10:40:57 -0700 Subject: [PATCH] website: Docs for all of the "encoding" functions --- .../functions/base64decode.html.md | 43 ++++++++++++ .../functions/base64encode.html.md | 45 ++++++++++++ .../functions/base64gzip.html.md | 33 +++++++++ .../configuration/functions/csvdecode.html.md | 68 +++++++++++++++++++ .../functions/jsondecode.html.md | 48 +++++++++++++ .../functions/jsonencode.html.md | 46 +++++++++++++ .../configuration/functions/urlencode.html.md | 34 ++++++++++ 7 files changed, 317 insertions(+) create mode 100644 website/docs/configuration/functions/base64decode.html.md create mode 100644 website/docs/configuration/functions/base64encode.html.md create mode 100644 website/docs/configuration/functions/base64gzip.html.md create mode 100644 website/docs/configuration/functions/csvdecode.html.md create mode 100644 website/docs/configuration/functions/jsondecode.html.md create mode 100644 website/docs/configuration/functions/jsonencode.html.md create mode 100644 website/docs/configuration/functions/urlencode.html.md diff --git a/website/docs/configuration/functions/base64decode.html.md b/website/docs/configuration/functions/base64decode.html.md new file mode 100644 index 000000000..a2442533b --- /dev/null +++ b/website/docs/configuration/functions/base64decode.html.md @@ -0,0 +1,43 @@ +--- +layout: "functions" +page_title: "base64decode function" +sidebar_current: "docs-funcs-encoding-base64decode" +description: |- + The base64decode function decodes a string containing a base64 sequence. +--- + +# `base64decode` Function + +`base64decode` takes a string containing a Base64 character sequence and +returns the original string. + +Terraform uses the "standard" Base64 alphabet as defined in +[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +Strings in the Terraform language are sequences of unicode characters rather +than bytes, so this function will also interpret the resulting bytes as +UTF-8. If the bytes after Base64 decoding are _not_ valid UTF-8, this function +produces an error. + +While we do not recommend manipulating large, raw binary data in the Terraform +language, Base64 encoding is the standard way to represent arbitrary byte +sequences, and so resource types that accept or return binary data will use +Base64 themselves, which avoids the need to encode or decode it directly in +most cases. Various other functions with names containing "base64" can generate +or manipulate Base64 data directly. + +## Examples + +``` +> base64decode("SGVsbG8gV29ybGQ=") +Hello World +``` + +## Related Functions + +* [`base64encode`](./base64encode.html) performs the opposite operation, + encoding the UTF-8 bytes for a string as Base64. +* [`base64gzip`](./base64gzip.html) applies gzip compression to a string + and returns the result with Base64 encoding. +* [`filebase64`](./filebase64.html) reads a file from the local filesystem + and returns its raw bytes with Base64 encoding. diff --git a/website/docs/configuration/functions/base64encode.html.md b/website/docs/configuration/functions/base64encode.html.md new file mode 100644 index 000000000..d8b2005b9 --- /dev/null +++ b/website/docs/configuration/functions/base64encode.html.md @@ -0,0 +1,45 @@ +--- +layout: "functions" +page_title: "base64encode function" +sidebar_current: "docs-funcs-encoding-base64encode" +description: |- + The base64encode function applies Base64 encoding to a string. +--- + +# `base64encode` Function + +`base64encode` applies Base64 encoding to a string. + +Terraform uses the "standard" Base64 alphabet as defined in +[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +Strings in the Terraform language are sequences of unicode characters rather +than bytes, so this function will first encode the characters from the string +as UTF-8, and then apply Base64 encoding to the result. + +The Terraform language applies Unicode normalization to all strings, and so +passing a string through `base64decode` and then `base64encode` may not yield +the original result exactly. + +While we do not recommend manipulating large, raw binary data in the Terraform +language, Base64 encoding is the standard way to represent arbitrary byte +sequences, and so resource types that accept or return binary data will use +Base64 themselves, and so this function exists primarily to allow string +data to be easily provided to resource types that expect Base64 bytes. + +## Examples + +``` +> base64encode("Hello World") +SGVsbG8gV29ybGQ= +``` + +## Related Functions + +* [`base64decode`](./base64decode.html) performs the opposite operation, + decoding Base64 data and interpreting it as a UTF-8 string. +* [`base64gzip`](./base64gzip.html) applies gzip compression to a string + and returns the result with Base64 encoding all in one operation. +* [`filebase64`](./filebase64.html) reads a file from the local filesystem + and returns its raw bytes with Base64 encoding, without creating an + intermediate Unicode string. diff --git a/website/docs/configuration/functions/base64gzip.html.md b/website/docs/configuration/functions/base64gzip.html.md new file mode 100644 index 000000000..f5aa6d138 --- /dev/null +++ b/website/docs/configuration/functions/base64gzip.html.md @@ -0,0 +1,33 @@ +--- +layout: "functions" +page_title: "base64gzip function" +sidebar_current: "docs-funcs-encoding-base64gzip" +description: |- + The base64encode function compresses the given string with gzip and then + encodes the result in Base64. +--- + +# `base64gzip` Function + +`base64gzip` compresses a string with gzip and then encodes the result in +Base64 encoding. + +Terraform uses the "standard" Base64 alphabet as defined in +[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4). + +Strings in the Terraform language are sequences of unicode characters rather +than bytes, so this function will first encode the characters from the string +as UTF-8, then apply gzip compression, and then finally apply Base64 encoding. + +While we do not recommend manipulating large, raw binary data in the Terraform +language, this function can be used to compress reasonably sized text strings +generated within the Terraform language. For example, the result of this +function can be used to create a compressed object in Amazon S3 as part of +an S3 website. + +## Related Functions + +* [`base64encode`](./base64encode.html) applies Base64 encoding _without_ + gzip compression. +* [`filebase64`](./filebase64.html) reads a file from the local filesystem + and returns its raw bytes with Base64 encoding. diff --git a/website/docs/configuration/functions/csvdecode.html.md b/website/docs/configuration/functions/csvdecode.html.md new file mode 100644 index 000000000..743dca198 --- /dev/null +++ b/website/docs/configuration/functions/csvdecode.html.md @@ -0,0 +1,68 @@ +--- +layout: "functions" +page_title: "csvdecode function" +sidebar_current: "docs-funcs-encoding-csvdecode" +description: |- + The csvdecode function decodes CSV data into a list of maps. +--- + +# `base64decode` Function + +`csvdecode` decodes a string containing CSV-formatted data and produces a +list of maps representing that data. + +CSV is _Comma-separated Values_, an encoding format for tabular data. There +are many variants of CSV, but this function implements the format defined +in [RFC 4180](https://tools.ietf.org/html/rfc4180). + +The first line of the CSV data is interpreted as a "header" row: the values +given are used as the keys in the resulting maps. Each subsequent line becomes +a single map in the resulting list, matching the keys from the header row +with the given values by index. All lines in the file must contain the same +number of fields, or this function will produce an error. + +## Examples + +``` +> csvdecode("a,b,c\n1,2,3\n4,5,6") +[ + { + "a" = 1 + "b" = 2 + "c" = 3 + }, + { + "a" = 4 + "b" = 5 + "c" = 6 + } +] +``` + +## Use with the `count` meta-argument + +It can be tempting to use `csvdecode` to generate a set of similar resources +using the `count` meta-argument, as in this example: + +```hcl +locals { + instances = csvdecode(file("${path.module}/instances.csv")) +} + +resource "aws_instance" "example" { + count = len(local.instances) # Beware! (see below) + + instance_type = local.instances[count.index].instance_type + ami = local.instances[count.index].ami +} +``` + +The above example will work on initial creation, but if any rows are removed +from the CSV file, or if the records in the CSV file are re-ordered, Terraform +will not understand that the ordering has changed and will instead interpret +this as requests for changes to many or all of the instances, which will in +turn force these instances to be destroyed and re-created. + +The above pattern can be used with care in situations where, for example, the +CSV file is only ever appended to, or if mass-updating the resources would +not be harmful, but in general we recommend avoiding the above pattern. diff --git a/website/docs/configuration/functions/jsondecode.html.md b/website/docs/configuration/functions/jsondecode.html.md new file mode 100644 index 000000000..4b249f2e9 --- /dev/null +++ b/website/docs/configuration/functions/jsondecode.html.md @@ -0,0 +1,48 @@ +--- +layout: "functions" +page_title: "jsondecode function" +sidebar_current: "docs-funcs-encoding-jsondecode" +description: |- + The jsondecode function decodes a JSON string into a representation of its + value. +--- + +# `jsondecode` Function + +`jsondecode` interprets a given string as JSON, returning a representation +of the result of decoding that string. + +The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159). + +This function maps JSON values to +[Terraform language values](/docs/configuration/expressions.html#types-and-values) +in the following way: + +| JSON type | Terraform type | +| --------- | ------------------------------------------------------------ | +| String | `string` | +| Number | `number` | +| Boolean | `bool` | +| Object | `object(...)` with attribute types determined per this table | +| Array | `tuple(...)` with element types determined per this table | +| Null | The Terraform language `null` value | + +The Terraform language automatic type conversion rules mean that you don't +usually need to worry about exactly what type is produced for a given value, +and can just use the result in an intuitive way. + +## Examples + +``` +> jsondecode("{\"hello\": \"world\"}") +{ + "hello" = "world" +} +> jsondecode("true") +true +``` + +## Related Functions + +* [`jsonencode`](./jsonencode.html) performs the opposite operation, _encoding_ + a value as JSON. diff --git a/website/docs/configuration/functions/jsonencode.html.md b/website/docs/configuration/functions/jsonencode.html.md new file mode 100644 index 000000000..81b836453 --- /dev/null +++ b/website/docs/configuration/functions/jsonencode.html.md @@ -0,0 +1,46 @@ +--- +layout: "functions" +page_title: "jsonencode function" +sidebar_current: "docs-funcs-encoding-jsonencode" +description: |- + The jsonencode function encodes a given value as a JSON string. +--- + +# `jsonencode` Function + +`jsonencode` encodes a given value to a string using JSON syntax. + +The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159). + +This fucntion maps +[Terraform language values](/docs/configuration/expressions.html#types-and-values) +to JSON values in the following way: + +| Terraform type | JSON type | +| -------------- | --------- | +| `string` | String | +| `number` | Number | +| `bool` | Bool | +| `list(...)` | Array | +| `set(...)` | Array | +| `tuple(...)` | Array | +| `map(...)` | Object | +| `object(...)` | Object | +| Null value | `null` | + +Since the JSON format cannot fully represent all of the Terraform language +types, passing the `jsonencode` result to `jsondecode` will not produce an +identical value, but the automatic type conversion rules mean that this is +rarely a problem in practice. + +## Examples + +``` +> jsonencode({"hello"="world"}) +{"hello":"world"} +``` + +## Related Functions + +* [`jsondecode`](./jsondecode.html) performs the opposite operation, _decoding_ + a JSON string to obtain its represented value. diff --git a/website/docs/configuration/functions/urlencode.html.md b/website/docs/configuration/functions/urlencode.html.md new file mode 100644 index 000000000..907f6e4d5 --- /dev/null +++ b/website/docs/configuration/functions/urlencode.html.md @@ -0,0 +1,34 @@ +--- +layout: "functions" +page_title: "urlencode function" +sidebar_current: "docs-funcs-encoding-urlencode" +description: |- + The urlencode function applies URL encoding to a given string. +--- + +# `urlencode` Function + +`urlencode` applies URL encoding to a given string. + +This function identifies characters in the given string that would have a +special meaning when included as a query string argument in a URL and +escapes them using +[RFC 3986 "percent encoding"](https://tools.ietf.org/html/rfc3986#section-2.1). + +The exact set of characters escaped may change over time, but the result +is guaranteed to be interpolatable into a query string argument without +inadvertently introducing additional delimiters. + +If the given string contains non-ASCII characters, these are first encoded as +UTF-8 and then percent encoding is applied separately to each UTF-8 byte. + +## Examples + +``` +> urlencode("Hello World") +Hello%20World +> urlencode("☃") +%E2%98%83 +> "http://example.com/search?q=${urlencode("terraform urlencode")}" +http://example.com/search?q=terraform%20urlencode +```