github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/functions/can.html.md (about)

     1  ---
     2  layout: "functions"
     3  page_title: "can - Functions - Configuration Language"
     4  sidebar_current: "docs-funcs-conversion-can"
     5  description: |-
     6    The can function tries to evaluate an expression given as an argument and
     7    indicates whether the evaluation succeeded.
     8  ---
     9  
    10  # `can` Function
    11  
    12  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    13  earlier, see
    14  [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
    15  
    16  `can` evaluates the given expression and returns a boolean value indicating
    17  whether the expression produced a result without any errors.
    18  
    19  This is a special function that is able to catch errors produced when evaluating
    20  its argument. For most situations where you could use `can` it's better to use
    21  [`try`](./try.html) instead, because it allows for more concise definition of
    22  fallback values for failing expressions.
    23  
    24  The primary purpose of `can` is to turn an error condition into a boolean
    25  validation result when writing
    26  [custom variable validation rules](../variables.html#custom-validation-rules).
    27  For example:
    28  
    29  ```
    30  variable "timestamp" {
    31    type        = string
    32  
    33    validation { # NOTE: custom validation is currently an opt-in experiment (see link above)
    34      # formatdate fails if the second argument is not a valid timestamp
    35      condition     = can(formatdate("", var.timestamp))
    36      error_message = "The timestamp argument requires a valid RFC 3339 timestamp."
    37    }
    38  }
    39  ```
    40  
    41  The `can` function can only catch and handle _dynamic_ errors resulting from
    42  access to data that isn't known until runtime. It will not catch errors
    43  relating to expressions that can be proven to be invalid for any input, such
    44  as a malformed resource reference.
    45  
    46  ~> **Warning:** The `can` function is intended only for simple tests in
    47  variable validation rules. Although it can technically accept any sort of
    48  expression and be used elsewhere in the configuration, we recommend against
    49  using it in other contexts. For error handling elsewhere in the configuration,
    50  prefer to use [`try`](./try.html).
    51  
    52  ## Examples
    53  
    54  ```
    55  > local.foo
    56  {
    57    "bar" = "baz"
    58  }
    59  > can(local.foo.bar)
    60  true
    61  > can(local.foo.boop)
    62  false
    63  ```
    64  
    65  The `can` function will _not_ catch errors relating to constructs that are
    66  provably invalid even before dynamic expression evaluation, such as a malformed
    67  reference or a reference to a top-level object that has not been declared:
    68  
    69  ```
    70  > can(local.nonexist)
    71  
    72  Error: Reference to undeclared local value
    73  
    74  A local value with the name "nonexist" has not been declared.
    75  ```
    76  
    77  ## Related Functions
    78  
    79  * [`try`](./try.html), which tries evaluating a sequence of expressions and
    80    returns the result of the first one that succeeds.