ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/language/functions/yamldecode.mdx

100 lines
3.3 KiB
Plaintext
Raw Normal View History

lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
---
migrate docs to mdx
2021-12-15 03:41:17 +01:00
page_title: yamldecode - Functions - Configuration Language
lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
description: |-
The yamldecode function decodes a YAML string into a representation of its
value.
---
# `yamldecode` Function
`yamldecode` parses a string as a subset of YAML, and produces a representation
of its value.
This function supports a subset of [YAML 1.2](https://yaml.org/spec/1.2/spec.html),
as described below.
This function maps YAML values to
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[Terraform language values](/language/expressions/types)
lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
in the following way:
| YAML type | Terraform type |
| ------------- | ------------------------------------------------------------------ |
| `!!str` | `string` |
| `!!float` | `number` |
| `!!int` | `number` |
| `!!bool` | `bool` |
| `!!map` | `object(...)` with attribute types determined per this table |
| `!!seq` | `tuple(...)` with element types determined per this table |
| `!!null` | The Terraform language `null` value |
| `!!timestamp` | `string` in [RFC 3339](https://tools.ietf.org/html/rfc3339) format |
| `!!binary` | `string` containing base64-encoded representation |
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.
Note though that the mapping above is ambiguous -- several different source
types map to the same target type -- and so round-tripping through `yamldecode`
and then `yamlencode` cannot produce an identical result.
YAML is a complex language and it supports a number of possibilities that the
Terraform language's type system cannot represent. Therefore this YAML decoder
supports only a subset of YAML 1.2, with restrictions including the following:
- Although aliases to earlier anchors are supported, cyclic data structures
(where a reference to a collection appears inside that collection) are not.
If `yamldecode` detects such a structure then it will return an error.
- Only the type tags shown in the above table (or equivalent alternative
representations of those same tags) are supported. Any other tags will
result in an error.
- Only one YAML document is permitted. If multiple documents are present in
the given string then this function will return an error.
## Examples
```
Fix yamldecode example from json to yaml (#28220) * Fix yamldecode example from json to yaml * inline yaml example
2021-04-05 19:41:07 +02:00
> yamldecode("hello: world")
lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
{
"hello" = "world"
}
> yamldecode("true")
true
> yamldecode("{a: &foo [1, 2, 3], b: *foo}")
{
"a" = [
1,
2,
3,
]
"b" = [
1,
2,
3,
]
}
> yamldecode("{a: &foo [1, *foo, 3]}")
Error: Error in function call
Call to function "yamldecode" failed: cannot refer to anchor "foo" from inside
its own definition.
> yamldecode("{a: !not-supported foo}")
Error: Error in function call
Call to function "yamldecode" failed: unsupported tag "!not-supported".
```
## Related Functions
migrate docs to mdx
2021-12-15 03:41:17 +01:00
- [`jsondecode`](/language/functions/jsondecode) is a similar operation using JSON instead
lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
of YAML.
migrate docs to mdx
2021-12-15 03:41:17 +01:00
- [`yamlencode`](/language/functions/yamlencode) performs the opposite operation, _encoding_
lang: yamldecode and yamlencode functions These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
2019-05-26 19:25:18 +02:00
a value as YAML.