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

     1  ---
     2  layout: docs
     3  page_title: try - Functions - Configuration Language
     4  description: |-
     5    The try function tries to evaluate a sequence of expressions given as
     6    arguments and returns the result of the first one that does not produce
     7    any errors.
     8  ---
     9  
    10  # `try` Function
    11  
    12  `try` evaluates all of its argument expressions in turn and returns the result
    13  of the first one that does not produce any errors.
    14  
    15  This is a special function that is able to catch errors produced when evaluating
    16  its arguments, which is particularly useful when working with complex data
    17  structures whose shape is not well-known at implementation time.
    18  
    19  For example, if some data is retrieved from an external system in JSON or YAML
    20  format and then decoded, the result may have attributes that are not guaranteed
    21  to be set. We can use `try` to produce a normalized data structure which has
    22  a predictable type that can therefore be used more conveniently elsewhere in
    23  the configuration:
    24  
    25  ```hcl
    26  locals {
    27    raw_value = yamldecode("${path.folder}/example.yaml")
    28    normalized_value = {
    29      name   = tostring(try(local.raw_value.name, null))
    30      groups = try(local.raw_value.groups, [])
    31    }
    32  }
    33  ```
    34  
    35  With the above local value expressions, configuration elsewhere in the folder
    36  can refer to `local.normalized_value` attributes without the need to repeatedly
    37  check for and handle absent attributes that would otherwise produce errors.
    38  
    39  We can also use `try` to deal with situations where a value might be provided
    40  in two different forms, allowing us to normalize to the most general form:
    41  
    42  ```hcl
    43  variable "example" {
    44    type = any
    45  }
    46  
    47  locals {
    48    example = try(
    49      [tostring(var.example)],
    50      tolist(var.example),
    51    )
    52  }
    53  ```
    54  
    55  The above permits `var.example` to be either a list or a single string. If it's
    56  a single string then it'll be normalized to a single-element list containing
    57  that string, again allowing expressions elsewhere in the configuration to just
    58  assume that `local.example` is always a list.
    59  
    60  This second example contains two expressions that can both potentially fail.
    61  For example, if `var.example` were set to `{}` then it could be converted to
    62  neither a string nor a list. If `try` exhausts all of the given expressions
    63  without any succeeding, it will return an error describing all of the problems
    64  it encountered.
    65  
    66  We strongly suggest using `try` only in special local values whose expressions
    67  perform normalization, so that the error handling is confined to a single
    68  location in the folder and the rest of the folder can just use straightforward
    69  references to the normalized structure and thus be more readable for future
    70  maintainers.
    71  
    72  The `try` function can only catch and handle _dynamic_ errors resulting from
    73  access to data that isn't known until runtime. It will not catch errors
    74  relating to expressions that can be proven to be invalid for any input, such
    75  as a malformed reference.
    76  
    77  ~> **Warning:** The `try` function is intended only for concise testing of the
    78  presence of and types of object attributes. Although it can technically accept
    79  any sort of expression, we recommend using it only with simple attribute
    80  references and type conversion functions as shown in the examples above.
    81  Overuse of `try` to suppress errors will lead to a configuration that is hard
    82  to understand and maintain.
    83  
    84  ## Examples
    85  
    86  ```shell-session
    87  > local.foo
    88  {
    89    "bar" = "baz"
    90  }
    91  > try(local.foo.bar, "fallback")
    92  baz
    93  > try(local.foo.boop, "fallback")
    94  fallback
    95  ```
    96  
    97  The `try` function will _not_ catch errors relating to constructs that are
    98  provably invalid even before dynamic expression evaluation, such as a malformed
    99  reference or a reference to a top-level object that has not been declared:
   100  
   101  ```shell-session
   102  > try(local.nonexist, "fallback")
   103  
   104  Error: Reference to undeclared local value
   105  
   106  A local value with the name "nonexist" has not been declared.
   107  ```
   108  
   109  ## Related Functions
   110  
   111  - [`can`](/docs/job-specification/hcl2/functions/conversion/can), which tries evaluating an expression and returns a
   112    boolean value indicating whether it succeeded.