ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/configuration/functions/list.html.md

34 lines
1.1 KiB
Markdown
Raw Normal View History

website: Document the remaining "collection" functions This also renames some of the existing function pages whose source filenames were not matching the usual naming scheme (.html.md).
2018-05-12 18:39:29 +02:00
---
website: Adopt a ton of pages into the "language" layout As of this commit, that layout doesn't exist yet, but I'm isolating the one-line changes to their own commit to try and keep your eyes from glazing over.
2020-08-15 03:51:06 +02:00
layout: "language"
website: Update functions section page titles
2018-12-20 05:35:11 +01:00
page_title: "list - Functions - Configuration Language"
website: Document the remaining "collection" functions This also renames some of the existing function pages whose source filenames were not matching the usual naming scheme (.html.md).
2018-05-12 18:39:29 +02:00
sidebar_current: "docs-funcs-collection-list"
description: |-
The list function constructs a list from some given elements.
---
# `list` Function
website: Version notes: Add new -> old links to 0.12 language docs (function pages)
2019-01-17 01:33:57 +01:00
-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
earlier, see
[0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
lang/funcs: Remove the deprecated "list" and "map" functions Prior to Terraform 0.12 these two functions were the only way to construct literal lists and maps (respectively) in HIL expressions. Terraform 0.12, by switching to HCL 2, introduced first-class syntax for constructing tuple and object values, which can then be converted into list and map values using the tolist and tomap type conversion functions. We marked both of these functions as deprecated in the Terraform v0.12 release and have since then mentioned in the docs that they will be removed in a future Terraform version. The "terraform 0.12upgrade" tool from Terraform v0.12 also included a rule to automatically rewrite uses of these functions into equivalent new syntax. The main motivation for removing these now is just to get this change made prior to Terraform 1.0. as we'll be doing with various other deprecations. However, a specific reason for these two functions in particular is that their existence is what caused us to invent the idea of a "type expression" as a distinct kind of expression in Terraform v0.12, and so removing them now would allow potentially unifying type expressions with value expressions in a future release. We do not have any current specific plans to make that change, but one potential motivation for doing so would be to take another attempt at a generalized "convert" function which takes a type as one of its arguments. Our previous attempt to implement such a function was foiled by the fact that Terraform's expression validator doesn't have any way to know to treat one argument of a particular function as special, and so it was generating incorrect error messages. We won't necessarily do that, but having these "list" and "map" functions out of the way leaves the option open.
2020-11-04 22:18:44 +01:00
The `list` function is no longer available. Prior to Terraform v0.12 it was
the only available syntax for writing a literal list inside an expression,
but Terraform v0.12 introduced a new first-class syntax.
website: Document the remaining "collection" functions This also renames some of the existing function pages whose source filenames were not matching the usual naming scheme (.html.md).
2018-05-12 18:39:29 +02:00
lang/funcs: Remove the deprecated "list" and "map" functions Prior to Terraform 0.12 these two functions were the only way to construct literal lists and maps (respectively) in HIL expressions. Terraform 0.12, by switching to HCL 2, introduced first-class syntax for constructing tuple and object values, which can then be converted into list and map values using the tolist and tomap type conversion functions. We marked both of these functions as deprecated in the Terraform v0.12 release and have since then mentioned in the docs that they will be removed in a future Terraform version. The "terraform 0.12upgrade" tool from Terraform v0.12 also included a rule to automatically rewrite uses of these functions into equivalent new syntax. The main motivation for removing these now is just to get this change made prior to Terraform 1.0. as we'll be doing with various other deprecations. However, a specific reason for these two functions in particular is that their existence is what caused us to invent the idea of a "type expression" as a distinct kind of expression in Terraform v0.12, and so removing them now would allow potentially unifying type expressions with value expressions in a future release. We do not have any current specific plans to make that change, but one potential motivation for doing so would be to take another attempt at a generalized "convert" function which takes a type as one of its arguments. Our previous attempt to implement such a function was foiled by the fact that Terraform's expression validator doesn't have any way to know to treat one argument of a particular function as special, and so it was generating incorrect error messages. We won't necessarily do that, but having these "list" and "map" functions out of the way leaves the option open.
2020-11-04 22:18:44 +01:00
To update an expression like `list(a, b, c)`, write the following instead:
website: Document the remaining "collection" functions This also renames some of the existing function pages whose source filenames were not matching the usual naming scheme (.html.md).
2018-05-12 18:39:29 +02:00
```
lang/funcs: Remove the deprecated "list" and "map" functions Prior to Terraform 0.12 these two functions were the only way to construct literal lists and maps (respectively) in HIL expressions. Terraform 0.12, by switching to HCL 2, introduced first-class syntax for constructing tuple and object values, which can then be converted into list and map values using the tolist and tomap type conversion functions. We marked both of these functions as deprecated in the Terraform v0.12 release and have since then mentioned in the docs that they will be removed in a future Terraform version. The "terraform 0.12upgrade" tool from Terraform v0.12 also included a rule to automatically rewrite uses of these functions into equivalent new syntax. The main motivation for removing these now is just to get this change made prior to Terraform 1.0. as we'll be doing with various other deprecations. However, a specific reason for these two functions in particular is that their existence is what caused us to invent the idea of a "type expression" as a distinct kind of expression in Terraform v0.12, and so removing them now would allow potentially unifying type expressions with value expressions in a future release. We do not have any current specific plans to make that change, but one potential motivation for doing so would be to take another attempt at a generalized "convert" function which takes a type as one of its arguments. Our previous attempt to implement such a function was foiled by the fact that Terraform's expression validator doesn't have any way to know to treat one argument of a particular function as special, and so it was generating incorrect error messages. We won't necessarily do that, but having these "list" and "map" functions out of the way leaves the option open.
2020-11-04 22:18:44 +01:00
tolist([a, b, c])
website: Document the remaining "collection" functions This also renames some of the existing function pages whose source filenames were not matching the usual naming scheme (.html.md).
2018-05-12 18:39:29 +02:00
```
lang/funcs: Remove the deprecated "list" and "map" functions Prior to Terraform 0.12 these two functions were the only way to construct literal lists and maps (respectively) in HIL expressions. Terraform 0.12, by switching to HCL 2, introduced first-class syntax for constructing tuple and object values, which can then be converted into list and map values using the tolist and tomap type conversion functions. We marked both of these functions as deprecated in the Terraform v0.12 release and have since then mentioned in the docs that they will be removed in a future Terraform version. The "terraform 0.12upgrade" tool from Terraform v0.12 also included a rule to automatically rewrite uses of these functions into equivalent new syntax. The main motivation for removing these now is just to get this change made prior to Terraform 1.0. as we'll be doing with various other deprecations. However, a specific reason for these two functions in particular is that their existence is what caused us to invent the idea of a "type expression" as a distinct kind of expression in Terraform v0.12, and so removing them now would allow potentially unifying type expressions with value expressions in a future release. We do not have any current specific plans to make that change, but one potential motivation for doing so would be to take another attempt at a generalized "convert" function which takes a type as one of its arguments. Our previous attempt to implement such a function was foiled by the fact that Terraform's expression validator doesn't have any way to know to treat one argument of a particular function as special, and so it was generating incorrect error messages. We won't necessarily do that, but having these "list" and "map" functions out of the way leaves the option open.
2020-11-04 22:18:44 +01:00
The `[ ... ]` brackets construct a tuple value, and then the `tolist` function
then converts it to a list. For more information on the value types in the
Terraform language, see [Type Constraints](../types.html).
lang/funcs: Type conversion functions It's not normally necessary to make explicit type conversions in Terraform because the language implicitly converts as necessary, but explicit conversions are useful in a few specialized cases: - When defining output values for a reusable module, it may be desirable to force a "cleaner" output type than would naturally arise from a computation, such as forcing a string containing digits into a number. - Our 0.12upgrade mechanism will use some of these to replace use of the undocumented, hidden type conversion functions in HIL, and force particular type interpretations in some tricky cases. - We've found that type conversion functions can be useful as _temporary_ workarounds for bugs in Terraform and in providers where implicit type conversion isn't working correctly or a type constraint isn't specified precisely enough for the automatic conversion behavior. These all follow the same convention of being named "to" followed by a short type name. Since we've had a long-standing convention of running all the words together in lowercase in function names, we stick to that here even though some of these names are quite strange, because these should be rarely-used functions anyway.
2019-01-17 18:11:48 +01:00
## Related Functions
lang/funcs: Remove the deprecated "list" and "map" functions Prior to Terraform 0.12 these two functions were the only way to construct literal lists and maps (respectively) in HIL expressions. Terraform 0.12, by switching to HCL 2, introduced first-class syntax for constructing tuple and object values, which can then be converted into list and map values using the tolist and tomap type conversion functions. We marked both of these functions as deprecated in the Terraform v0.12 release and have since then mentioned in the docs that they will be removed in a future Terraform version. The "terraform 0.12upgrade" tool from Terraform v0.12 also included a rule to automatically rewrite uses of these functions into equivalent new syntax. The main motivation for removing these now is just to get this change made prior to Terraform 1.0. as we'll be doing with various other deprecations. However, a specific reason for these two functions in particular is that their existence is what caused us to invent the idea of a "type expression" as a distinct kind of expression in Terraform v0.12, and so removing them now would allow potentially unifying type expressions with value expressions in a future release. We do not have any current specific plans to make that change, but one potential motivation for doing so would be to take another attempt at a generalized "convert" function which takes a type as one of its arguments. Our previous attempt to implement such a function was foiled by the fact that Terraform's expression validator doesn't have any way to know to treat one argument of a particular function as special, and so it was generating incorrect error messages. We won't necessarily do that, but having these "list" and "map" functions out of the way leaves the option open.
2020-11-04 22:18:44 +01:00
* [`concat`](./concat.html) produces a new list by concatenating together the
elements from other lists.
* [`tolist`](./tolist.html) converts a set or tuple value to a list.