github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/hcl2/functions/encoding/yamldecode.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: yamldecode - Functions - Configuration Language
     4  description: |-
     5    The yamldecode function decodes a YAML string into a representation of its
     6    value.
     7  ---
     8  
     9  # `yamldecode` Function
    10  
    11  `yamldecode` parses a string as a subset of YAML, and produces a representation
    12  of its value.
    13  
    14  This function supports a subset of [YAML 1.2](https://yaml.org/spec/1.2/spec.html),
    15  as described below.
    16  
    17  This function maps YAML values to
    18  [Nomad language values](/docs/job-specification/hcl2/expressions#types-and-values)
    19  in the following way:
    20  
    21  | YAML type     | Nomad type                                                         |
    22  | ------------- | ------------------------------------------------------------------ |
    23  | `!!str`       | `string`                                                           |
    24  | `!!float`     | `number`                                                           |
    25  | `!!int`       | `number`                                                           |
    26  | `!!bool`      | `bool`                                                             |
    27  | `!!map`       | `object(...)` with attribute types determined per this table       |
    28  | `!!seq`       | `tuple(...)` with element types determined per this table          |
    29  | `!!null`      | The Nomad language `null` value                                    |
    30  | `!!timestamp` | `string` in [RFC 3339](https://tools.ietf.org/html/rfc3339) format |
    31  | `!!binary`    | `string` containing base64-encoded representation                  |
    32  
    33  The Nomad language automatic type conversion rules mean that you don't
    34  usually need to worry about exactly what type is produced for a given value,
    35  and can just use the result in an intuitive way.
    36  
    37  Note though that the mapping above is ambiguous -- several different source
    38  types map to the same target type -- and so round-tripping through `yamldecode`
    39  and then `yamlencode` cannot produce an identical result.
    40  
    41  YAML is a complex language and it supports a number of possibilities that the
    42  Nomad language's type system cannot represent. Therefore this YAML decoder
    43  supports only a subset of YAML 1.2, with restrictions including the following:
    44  
    45  - Although aliases to earlier anchors are supported, cyclic data structures
    46    (where a reference to a collection appears inside that collection) are not.
    47    If `yamldecode` detects such a structure then it will return an error.
    48  
    49  - Only the type tags shown in the above table (or equivalent alternative
    50    representations of those same tags) are supported. Any other tags will
    51    result in an error.
    52  
    53  - Only one YAML document is permitted. If multiple documents are present in
    54    the given string then this function will return an error.
    55  
    56  ## Examples
    57  
    58  ```shell-session
    59  > yamldecode("{\"hello\": \"world\"}")
    60  {
    61    "hello" = "world"
    62  }
    63  
    64  > yamldecode("true")
    65  true
    66  
    67  > yamldecode("{a: &foo [1, 2, 3], b: *foo}")
    68  {
    69    "a" = [
    70      1,
    71      2,
    72      3,
    73    ]
    74    "b" = [
    75      1,
    76      2,
    77      3,
    78    ]
    79  }
    80  
    81  > yamldecode("{a: &foo [1, *foo, 3]}")
    82  
    83  Error: Error in function call
    84  
    85  Call to function "yamldecode" failed: cannot refer to anchor "foo" from inside
    86  its own definition.
    87  
    88  > yamldecode("{a: !not-supported foo}")
    89  
    90  Error: Error in function call
    91  
    92  Call to function "yamldecode" failed: unsupported tag "!not-supported".
    93  ```
    94  
    95  ## Related Functions
    96  
    97  - [`jsondecode`](/docs/job-specification/hcl2/functions/encoding/jsondecode) is a similar operation using JSON instead
    98    of YAML.
    99  - [`yamlencode`](/docs/job-specification/hcl2/functions/encoding/yamlencode) performs the opposite operation, _encoding_
   100    a value as YAML.