website: Docs for all of the "encoding" functions
This commit is contained in:
parent
e7d71995f6
commit
a491013054
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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
|
||||
```
|
Loading…
Reference in New Issue