github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/language/expressions/splat.html.md (about)

     1  ---
     2  layout: "language"
     3  page_title: "Splat Expressions - Configuration Language"
     4  ---
     5  
     6  # Splat Expressions
     7  
     8  > **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/expressions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
     9  
    10  A _splat expression_ provides a more concise way to express a common
    11  operation that could otherwise be performed with a `for` expression.
    12  
    13  If `var.list` is a list of objects that all have an attribute `id`, then
    14  a list of the ids could be produced with the following `for` expression:
    15  
    16  ```hcl
    17  [for o in var.list : o.id]
    18  ```
    19  
    20  This is equivalent to the following _splat expression:_
    21  
    22  ```hcl
    23  var.list[*].id
    24  ```
    25  
    26  The special `[*]` symbol iterates over all of the elements of the list given
    27  to its left and accesses from each one the attribute name given on its
    28  right. A splat expression can also be used to access attributes and indexes
    29  from lists of complex types by extending the sequence of operations to the
    30  right of the symbol:
    31  
    32  ```hcl
    33  var.list[*].interfaces[0].name
    34  ```
    35  
    36  The above expression is equivalent to the following `for` expression:
    37  
    38  ```hcl
    39  [for o in var.list : o.interfaces[0].name]
    40  ```
    41  
    42  ## Splat Expressions with Maps
    43  
    44  The splat expression patterns shown above apply only to lists, sets, and
    45  tuples. To get a similar result with a map or object value you must use
    46  [`for` expressions](for.html).
    47  
    48  Resources that use the `for_each` argument will appear in expressions as a map
    49  of objects, so you can't use splat expressions with those resources.
    50  For more information, see
    51  [Referring to Resource Instances](/docs/language/meta-arguments/for_each.html#referring-to-instances).
    52  
    53  ## Single Values as Lists
    54  
    55  Splat expressions have a special behavior when you apply them to a value that
    56  isn't a list, set, or tuple.
    57  
    58  If the value is anything other than a null value then the splat expression will
    59  transform it into a single-element list, or more accurately a single-element
    60  tuple value. If the value is _null_ then the splat expression will return an
    61  empty tuple.
    62  
    63  This special behavior can be useful for modules that accept optional input
    64  variables whose default value is `null` to represent the absense of any value,
    65  to adapt the variable value to work with other Terraform language features that
    66  are designed to work with collections. For example:
    67  
    68  ```
    69  variable "website" {
    70    type = object({
    71      index_document = string
    72      error_document = string
    73    })
    74    default = null
    75  }
    76  
    77  resource "aws_s3_bucket" "example" {
    78    # ...
    79  
    80    dynamic "website" {
    81      for_each = var.website[*]
    82      content {
    83        index_document = website.value.index_document
    84        error_document = website.value.error_document
    85      }
    86    }
    87  }
    88  ```
    89  
    90  The above example uses a [`dynamic` block](dynamic-blocks.html), which
    91  generates zero or more nested blocks based on a collection value. The input
    92  variable `var.website` is defined as a single object that might be null,
    93  so the `dynamic` block's `for_each` expression uses `[*]` to ensure that
    94  there will be one block if the module caller sets the website argument, or
    95  zero blocks if the caller leaves it set to null.
    96  
    97  This special behavior of splat expressions is not obvious to an unfamiliar
    98  reader, so we recommend using it only in `for_each` arguments and similar
    99  situations where the context implies working with a collection. Otherwise,
   100  the meaning of the expression may be unclear to future readers.
   101  
   102  ## Legacy (Attribute-only) Splat Expressions
   103  
   104  Earlier versions of the Terraform language had a slightly different version
   105  of splat expressions, which Terraform continues to support for backward
   106  compatibility. This older variant is less useful than the modern form described
   107  above, and so we recommend against using it in new configurations.
   108  
   109  The legacy "attribute-only" splat expressions use the sequence `.*`, instead of
   110  `[*]`:
   111  
   112  ```
   113  var.list.*.interfaces[0].name
   114  ```
   115  
   116  This form has a subtly different behavior, equivalent to the following
   117  `for` expression:
   118  
   119  ```
   120  [for o in var.list : o.interfaces][0].name
   121  ```
   122  
   123  Notice that with the attribute-only splat expression the index operation
   124  `[0]` is applied to the result of the iteration, rather than as part of
   125  the iteration itself. Only the attribute lookups apply to each element of
   126  the input. This limitation was confusing some people using older versions of
   127  Terraform and so we recommend always using the new-style splat expressions,
   128  with `[*]`, to get the more consistent behavior.