website: Docs for all of the "encoding" functions

This commit is contained in:
Martin Atkins 2018-05-13 10:40:57 -07:00
parent e7d71995f6
commit a491013054
7 changed files with 317 additions and 0 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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
```