github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/job-specification/hcl2/functions/encoding/yamlencode.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: yamlencode - Functions - Configuration Language
     4  sidebar_title: yamlencode
     5  description: The yamlencode function encodes a given value as a YAML string.
     6  ---
     7  
     8  # `yamlencode` Function
     9  
    10  `yamlencode` encodes a given value to a string using
    11  [YAML 1.2](https://yaml.org/spec/1.2/spec) block syntax.
    12  
    13  ~> **Warning:** This function is currently **experimental** and its exact
    14  result format may change in future versions of Nomad, based on feedback.
    15  Do not use `yamldecode` to construct a value for any argument where
    16  changes to the result would be disruptive. To get a consistent string
    17  representation of a value use [`jsonencode`](/docs/job-specification/hcl2/functions/encoding/jsonencode) instead; its
    18  results are also valid YAML because YAML is a JSON superset.
    19  
    20  <!--
    21      The condition for removing the above warning is that the underlying
    22      go-cty-yaml folder makes a stable release with a commitment to guarantee
    23      that the representation of particular input will not change without a
    24      major release. It is not making that commitment at the time of writing to
    25      allow for responding to user feedback about its output format, since YAML
    26      is a very flexible format and its initial decisions may prove to be
    27      sub-optimal when generating YAML intended for specific external consumers.
    28  -->
    29  
    30  This function maps
    31  [Nomad language values](/docs/job-specification/hcl2/expressions#types-and-values)
    32  to YAML tags in the following way:
    33  
    34  | Nomad type    | YAML type            |
    35  | ------------- | -------------------- |
    36  | `string`      | `!!str`              |
    37  | `number`      | `!!float` or `!!int` |
    38  | `bool`        | `!!bool`             |
    39  | `list(...)`   | `!!seq`              |
    40  | `set(...)`    | `!!seq`              |
    41  | `tuple(...)`  | `!!seq`              |
    42  | `map(...)`    | `!!map`              |
    43  | `object(...)` | `!!map`              |
    44  | Null value    | `!!null`             |
    45  
    46  `yamlencode` uses the implied syntaxes for all of the above types, so it does
    47  not generate explicit YAML tags.
    48  
    49  Because the YAML format cannot fully represent all of the Nomad language
    50  types, passing the `yamlencode` result to `yamldecode` will not produce an
    51  identical value, but the Nomad language automatic type conversion rules
    52  mean that this is rarely a problem in practice.
    53  
    54  ## Examples
    55  
    56  ```shell-session
    57  > yamlencode({"a":"b", "c":"d"})
    58  "a": "b"
    59  "c": "d"
    60  
    61  > yamlencode({"foo":[1, 2, 3], "bar": "baz"})
    62  "bar": "baz"
    63  "foo":
    64  - 1
    65  - 2
    66  - 3
    67  
    68  > yamlencode({"foo":[1, {"a":"b","c":"d"}, 3], "bar": "baz"})
    69  "bar": "baz"
    70  "foo":
    71  - 1
    72  - "a": "b"
    73    "c": "d"
    74  - 3
    75  ```
    76  
    77  `yamlencode` always uses YAML's "block style" for mappings and sequences, unless
    78  the mapping or sequence is empty. To generate flow-style YAML, use
    79  [`jsonencode`](/docs/job-specification/hcl2/functions/encoding/jsonencode) instead: YAML flow-style is a superset
    80  of JSON syntax.
    81  
    82  ## Related Functions
    83  
    84  - [`jsonencode`](/docs/job-specification/hcl2/functions/encoding/jsonencode) is a similar operation using JSON instead
    85    of YAML.
    86  - [`yamldecode`](/docs/job-specification/hcl2/functions/encoding/yamldecode) performs the opposite operation, _decoding_
    87    a YAML string to obtain its represented value.