diff --git a/website/docs/configuration/functions/chunklist.html.md b/website/docs/configuration/functions/chunklist.html.md new file mode 100644 index 000000000..0d5832454 --- /dev/null +++ b/website/docs/configuration/functions/chunklist.html.md @@ -0,0 +1,54 @@ +--- +layout: "functions" +page_title: "chunklist function" +sidebar_current: "docs-funcs-collection-chunklist" +description: |- + The chunklist function splits a single list into fixed-size chunks, returning + a list of lists. +--- + +# `chunklist` Function + +`chunklist` splits a single list into fixed-size chunks, returning a list +of lists. + +```hcl +chunklist(list, chunk_size) +``` + +## Examples + +``` +> chunklist(["a", "b", "c", "d", "e"], 2) +[ + [ + "a", + "b", + ], + [ + "c", + "d", + ], + [ + "e", + ], +] +> chunklist(["a", "b", "c", "d", "e"], 1) +[ + [ + "a", + ], + [ + "b", + ], + [ + "c", + ], + [ + "d", + ], + [ + "e", + ], +] +``` diff --git a/website/docs/configuration/functions/coalesce.html.md b/website/docs/configuration/functions/coalesce.html.md new file mode 100644 index 000000000..d92fd7ddd --- /dev/null +++ b/website/docs/configuration/functions/coalesce.html.md @@ -0,0 +1,35 @@ +--- +layout: "functions" +page_title: "coalesce function" +sidebar_current: "docs-funcs-collection-coalesce-x" +description: |- + The coalesce function takes any number of string arguments and returns the + first one that isn't empty. +--- + +# `coalesce` Function + +`coalesce` takes any number of string arguments and returns the first one +that isn't empty. + +## Examples + +``` +> coalesce("a", "b") +a +> coalesce("", "b") +b +``` + +To perform the `coalesce` operation with a list of strings, use the `...` +symbol to expand the list as arguments: + +``` +> coalesce(["", "b"]...) +b +``` + +## Related Functions + +* [`coalescelist`](./coalescelist.html) performs a similar operation with + list arguments rather than string arguments. diff --git a/website/docs/configuration/functions/coalescelist.html.md b/website/docs/configuration/functions/coalescelist.html.md new file mode 100644 index 000000000..5af14c22c --- /dev/null +++ b/website/docs/configuration/functions/coalescelist.html.md @@ -0,0 +1,44 @@ +--- +layout: "functions" +page_title: "coalescelist function" +sidebar_current: "docs-funcs-collection-coalescelist" +description: |- + The coalescelist function takes any number of list arguments and returns the + first one that isn't empty. +--- + +# `coalescelist` Function + +`coalescelist` takes any number of list arguments and returns the first one +that isn't empty. + +## Examples + +``` +> coalesce(["a", "b"], ["c", "d"]) +[ + "a", + "b", +] +> coalesce([], ["c", "d"]) +[ + "c", + "d", +] +``` + +To perform the `coalesce` operation with a list of lists, use the `...` +symbol to expand the outer list as arguments: + +``` +> coalesce([[], ["c", "d"]]...) +[ + "c", + "d", +] +``` + +## Related Functions + +* [`coalesce`](./coalesce.html) performs a similar operation with string + arguments rather than list arguments. diff --git a/website/docs/configuration/functions/compact.html.md b/website/docs/configuration/functions/compact.html.md new file mode 100644 index 000000000..aa2c18009 --- /dev/null +++ b/website/docs/configuration/functions/compact.html.md @@ -0,0 +1,23 @@ +--- +layout: "functions" +page_title: "compact function" +sidebar_current: "docs-funcs-collection-compact" +description: |- + The compact function removes empty string elements from a list. +--- + +# `compact` Function + +`compact` takes a list of strings and returns a new list with any empty string +elements removed. + +## Examples + +``` +> compact(["a", "", "b", "c"]) +[ + "a", + "b", + "c", +] +``` diff --git a/website/docs/configuration/functions/contains.html.md b/website/docs/configuration/functions/contains.html.md new file mode 100644 index 000000000..5201a081a --- /dev/null +++ b/website/docs/configuration/functions/contains.html.md @@ -0,0 +1,25 @@ +--- +layout: "functions" +page_title: "contains function" +sidebar_current: "docs-funcs-collection-contains" +description: |- + The contains function determines whether a list contains a given value. +--- + +# `contains` Function + +`contains` determines whether a given list contains a given single value +as one of its elements. + +```hcl +contains(list, value) +``` + +## Examples + +``` +> contains(["a", "b", "c"], "a") +true +> contains(["a", "b", "c"], "d") +false +``` diff --git a/website/docs/configuration/functions/distinct.html.md b/website/docs/configuration/functions/distinct.html.md new file mode 100644 index 000000000..d65bd9cac --- /dev/null +++ b/website/docs/configuration/functions/distinct.html.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "distinct function" +sidebar_current: "docs-funcs-collection-distinct" +description: |- + The distinct function removes duplicate elements from a list. +--- + +# `distinct` Function + +`distinct` takes a list and returns a new list with any duplicate elements +removed. + +The first occurence of each value is retained and the relative ordering of +these elements is preserved. + +## Examples + +``` +> distinct(["a", "b", "a", "c", "d", "b"]) +[ + "a", + "b", + "c", + "d", +] +``` diff --git a/website/docs/configuration/functions/element.html.md b/website/docs/configuration/functions/element.html.md new file mode 100644 index 000000000..f1b799137 --- /dev/null +++ b/website/docs/configuration/functions/element.html.md @@ -0,0 +1,40 @@ +--- +layout: "functions" +page_title: "element function" +sidebar_current: "docs-funcs-collection-element" +description: |- + The element function retrieves a single element from a list. +--- + +# `element` Function + +`element` retrieves a single element from a list. + +```hcl +element(list, index) +``` + +The index is zero-based. This function produces an error if used with an +empty list. + +Use the built-in index syntax `list[index]` in most cases. Use this function +only for the special additional "wrap-around" behavior described below. + +## Examples + +``` +> element(["a", "b", "c"], 1) +b +``` + +If the given index is greater than the length of the list then the index is +"wrapped around" by taking the index modulo the length of the list: + +``` +> element(["a", "b", "c"], 3) +a +``` + +## Related Functions + +* [`index`](./index.html) finds the index for a particular element value. diff --git a/website/docs/configuration/functions/flatten.html.md b/website/docs/configuration/functions/flatten.html.md new file mode 100644 index 000000000..c306dc024 --- /dev/null +++ b/website/docs/configuration/functions/flatten.html.md @@ -0,0 +1,29 @@ +--- +layout: "functions" +page_title: "flatten function" +sidebar_current: "docs-funcs-collection-flatten" +description: |- + The flatten function eliminates nested lists from a list. +--- + +# `flatten` Function + +`flatten` takes a list and replaces any elements that are lists with a +flattened sequence of the list contents. + +## Examples + +``` +> flatten([["a", "b"], [], ["c"]]) +["a", "b", "c"] +``` + +If any of the nested lists also contain directly-nested lists, these too are +flattened recursively: + +``` +> flatten([[["a", "b"], []], ["c"]]) +["a", "b", "c"] +``` + +Indirectly-nested lists, such as those in maps, are _not_ flattened. diff --git a/website/docs/configuration/functions/index.html.md b/website/docs/configuration/functions/index.html.md new file mode 100644 index 000000000..702ead188 --- /dev/null +++ b/website/docs/configuration/functions/index.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "index function" +sidebar_current: "docs-funcs-collection-index" +description: |- + The index function finds the element index for a given value in a list. +--- + +# `index` Function + +`index` finds the element index for a given value in a list. + +```hcl +index(list, value) +``` + +The returned index is zero-based. This function produces an error if the given +value is not present in the list. + +## Examples + +``` +> index(["a", "b", "c"], "b") +1 +``` + +## Related Functions + +* [`element`](./element.html) retrieves a particular element from a list given + its index. diff --git a/website/docs/configuration/functions/join.md b/website/docs/configuration/functions/join.html.md similarity index 100% rename from website/docs/configuration/functions/join.md rename to website/docs/configuration/functions/join.html.md diff --git a/website/docs/configuration/functions/length.html.md b/website/docs/configuration/functions/length.html.md new file mode 100644 index 000000000..6c0ac4a02 --- /dev/null +++ b/website/docs/configuration/functions/length.html.md @@ -0,0 +1,42 @@ +--- +layout: "functions" +page_title: "length function" +sidebar_current: "docs-funcs-collection-length" +description: |- + The length function determines the length of a collection or string. +--- + +# `length` Function + +`length` determines the length of a given list, map, or string. + +If given a list or map, the result is the number of elements in that collection. +If given a string, the result is the number of characters in the string. + +## Examples + +``` +> length([]) +0 +> length(["a", "b"]) +2 +> length({"a" = "b"}) +1 +> length("hello") +5 +``` + +When given a string, the result is the number of characters, rather than the +number of bytes or Unicode sequences that form them: + +``` +> length("👾🕹️") +2 +``` + +A "character" is a _grapheme cluster_, as defined by +[Unicode Standard Annex #29](http://unicode.org/reports/tr29/). Note that +remote APIs may have a different definition of "character" for the purpose of +length limits on string arguments; a Terraform provider is responsible for +translating Terraform's string representation into that used by its respective +remote system and applying any additional validation rules to it. diff --git a/website/docs/configuration/functions/list.html.md b/website/docs/configuration/functions/list.html.md new file mode 100644 index 000000000..e02d98bd4 --- /dev/null +++ b/website/docs/configuration/functions/list.html.md @@ -0,0 +1,40 @@ +--- +layout: "functions" +page_title: "list function" +sidebar_current: "docs-funcs-collection-list" +description: |- + The list function constructs a list from some given elements. +--- + +# `list` Function + +~> **This function is deprecated.** From Terraform v0.12, the Terraform +language has built-in syntax for creating lists using the `[` and `]` +delimiters. Use the built-in syntax instead. The `list` function will be +removed in a future version of Terraform. + +`list` takes an arbitrary number of arguments and returns a list containing +those values in the same order. + +## Examples + +``` +> list("a", "b", "c") +[ + "a", + "b", + "c", +] +``` + +Do not use the above form in Terraform v0.12 or above. Instead, use the +built-in list construction syntax, which achieves the same result: + +``` +> ["a", "b", "c"] +[ + "a", + "b", + "c", +] +``` diff --git a/website/docs/configuration/functions/lower.md b/website/docs/configuration/functions/lower.html.md similarity index 100% rename from website/docs/configuration/functions/lower.md rename to website/docs/configuration/functions/lower.html.md diff --git a/website/docs/configuration/functions/map.html.md b/website/docs/configuration/functions/map.html.md new file mode 100644 index 000000000..6a0ad9a07 --- /dev/null +++ b/website/docs/configuration/functions/map.html.md @@ -0,0 +1,38 @@ +--- +layout: "functions" +page_title: "map function" +sidebar_current: "docs-funcs-collection-map" +description: |- + The map function constructs a map from some given elements. +--- + +# `map` Function + +~> **This function is deprecated.** From Terraform v0.12, the Terraform +language has built-in syntax for creating maps using the `{` and `}` +delimiters. Use the built-in syntax instead. The `map` function will be +removed in a future version of Terraform. + +`map` takes an even number of arguments and returns a map whose elements +are constructed from consecutive pairs of arguments. + +## Examples + +``` +> map("a", "b", "c", "d") +{ + "a" = "b" + "c" = "d" +] +``` + +Do not use the above form in Terraform v0.12 or above. Instead, use the +built-in map construction syntax, which achieves the same result: + +``` +> {"a" = "b", "c" = "d"} +{ + "a" = "b" + "c" = "d" +] +``` diff --git a/website/docs/configuration/functions/matchkeys.html.md b/website/docs/configuration/functions/matchkeys.html.md new file mode 100644 index 000000000..f04e8d2b6 --- /dev/null +++ b/website/docs/configuration/functions/matchkeys.html.md @@ -0,0 +1,72 @@ +--- +layout: "functions" +page_title: "list function" +sidebar_current: "docs-funcs-collection-matchkeys" +description: |- + The matchkeys function takes a subset of elements from one list by matching + corresponding indexes in another list. +--- + +# `matchkeys` Function + +`matchkeys` constructs a new list by taking a subset of elements from one +list whose indexes match the corresponding indexes of values in another +list. + +```hcl +matchkeys(valueslist, keyslist, searchset) +``` + +`matchkeys` identifies the indexes in `keyslist` that are equal to elements of +`searchset`, and then constructs a new list by taking those same indexes from +`valueslist`. Both `valueslist` and `keyslist` must be the same length. + +The ordering of the values in `valueslist` is preserved in the result. + +## Examples + +``` +> matchkeys(["i-123", "i-abc", "i-def"], ["us-west", "us-east", "us-east"], ["us-east"]) +[ + "i-abc", + "i-def", +] +``` + +If the result ordering is not significant, you can achieve a similar result +using a `for` expression with a map: + +``` +> [for i, z in {"i-123"="us-west","i-abc"="us-east","i-def"="us-east"}: i if z == "us-east"] +[ + "i-def", + "i-abc", +] +``` + +If the keys and values of interest are attributes of objects in a list of +objects then you can also achieve a similar result using a `for` expression +with that list: + +``` +> [for x in [{id="i-123",zone="us-west"},{id="i-abc",zone="us-east"}]: x.id if x.zone == "us-east"] +[ + "i-abc", +] +``` + +For example, the previous form can be used with the list of resource instances +produced by a `resource` block with the `count` meta-attribute set, to filter +the instances by matching one of the resource attributes: + +``` +> [for x in aws_instance.example: x.id if x.availability_zone == "us-east-1a"] +[ + "i-abc123", + "i-def456", +] +``` + +Since the signature of `matchkeys` is complicated and not immediately clear to +the reader when used in configuration, prefer to use `for` expressions where +possible to maximize readability. diff --git a/website/docs/configuration/functions/merge.html.md b/website/docs/configuration/functions/merge.html.md new file mode 100644 index 000000000..bbc6c73aa --- /dev/null +++ b/website/docs/configuration/functions/merge.html.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "merge function" +sidebar_current: "docs-funcs-collection-merge" +description: |- + The merge function takes an arbitrary number of maps and returns a single + map after merging the keys from each argument. +--- + +# `merge` Function + +`merge` takes an arbitrary number of maps and returns a single map that +contains a merged set of elements from all of the maps. + +If more than one given map defines the same key then the one that is later +in the argument sequence takes precedence. + +## Examples + +``` +> merge({"a"="b", "c"="d"}, {"e"="f", "c"="z"}) +{ + "a" = "b" + "c" = "z" + "e" = "f" +} +``` diff --git a/website/docs/configuration/functions/replace.md b/website/docs/configuration/functions/replace.html.md similarity index 100% rename from website/docs/configuration/functions/replace.md rename to website/docs/configuration/functions/replace.html.md diff --git a/website/docs/configuration/functions/slice.html.md b/website/docs/configuration/functions/slice.html.md new file mode 100644 index 000000000..a146436b7 --- /dev/null +++ b/website/docs/configuration/functions/slice.html.md @@ -0,0 +1,34 @@ +--- +layout: "functions" +page_title: "slice function" +sidebar_current: "docs-funcs-collection-slice" +description: |- + The slice function extracts some consecutive elements from within a list. +--- + +# `slice` Function + +`slice` extracts some consecutive elements from within a list. + +```hcl +slice(list, startindex, endindex) +``` + +`startindex` is inclusive, while `endindex` is exclusive. This function returns +an error if either index is outside the bounds of valid indices for the given +list. + +## Examples + +``` +> slice(["a", "b", "c", "d"], 1, 3) +[ + "b", + "c", +] +``` + +## Related Functions + +* [`substr`](./substr.html) performs a similar function for characters in a + string, although it uses a length instead of an end index. diff --git a/website/docs/configuration/functions/sort.html.md b/website/docs/configuration/functions/sort.html.md new file mode 100644 index 000000000..a5ed0ae57 --- /dev/null +++ b/website/docs/configuration/functions/sort.html.md @@ -0,0 +1,28 @@ +--- +layout: "functions" +page_title: "sort function" +sidebar_current: "docs-funcs-collection-sort" +description: |- + The sort function takes a list of strings and returns a new list with those + strings sorted lexicographically. +--- + +# `sort` Function + +`sort` takes a list of strings and returns a new list with those strings +sorted lexicographically. + +The sort is in terms of Unicode codepoints, with higher codepoints appearing +after lower ones in the result. + +## Examples + +``` +> sort(["e", "d", "a", "x"]) +[ + "a", + "d", + "e", + "x", +] +``` diff --git a/website/docs/configuration/functions/split.md b/website/docs/configuration/functions/split.html.md similarity index 100% rename from website/docs/configuration/functions/split.md rename to website/docs/configuration/functions/split.html.md diff --git a/website/docs/configuration/functions/substr.md b/website/docs/configuration/functions/substr.html.md similarity index 100% rename from website/docs/configuration/functions/substr.md rename to website/docs/configuration/functions/substr.html.md diff --git a/website/docs/configuration/functions/title.md b/website/docs/configuration/functions/title.html.md similarity index 100% rename from website/docs/configuration/functions/title.md rename to website/docs/configuration/functions/title.html.md diff --git a/website/docs/configuration/functions/transpose.html.md b/website/docs/configuration/functions/transpose.html.md new file mode 100644 index 000000000..44a5c777c --- /dev/null +++ b/website/docs/configuration/functions/transpose.html.md @@ -0,0 +1,31 @@ +--- +layout: "functions" +page_title: "transpose function" +sidebar_current: "docs-funcs-collection-transpose" +description: |- + The transpose function takes a map of lists of strings and swaps the keys + and values. +--- + +# `transpose` Function + +`transpose` takes a map of lists of strings and swaps the keys and values +to produce a new map of lists of strings. + +## Examples + +``` +> transpose({"a" = ["1", "2"], "b" = ["2", "3"]}) +{ + "1" = [ + "a", + ], + "2" = [ + "a", + "b", + ], + "3" = [ + "b", + ], +} +``` diff --git a/website/docs/configuration/functions/trimspace.md b/website/docs/configuration/functions/trimspace.html.md similarity index 100% rename from website/docs/configuration/functions/trimspace.md rename to website/docs/configuration/functions/trimspace.html.md diff --git a/website/docs/configuration/functions/upper.md b/website/docs/configuration/functions/upper.html.md similarity index 100% rename from website/docs/configuration/functions/upper.md rename to website/docs/configuration/functions/upper.html.md diff --git a/website/docs/configuration/functions/zipmap.html.md b/website/docs/configuration/functions/zipmap.html.md new file mode 100644 index 000000000..360f11b34 --- /dev/null +++ b/website/docs/configuration/functions/zipmap.html.md @@ -0,0 +1,35 @@ +--- +layout: "functions" +page_title: "zipmap function" +sidebar_current: "docs-funcs-collection-zipmap" +description: |- + The zipmap function constructs a map from a list of keys and a corresponding + list of values. +--- + +# `zipmap` Function + +`zipmap` constructs a map from a list of keys and a corresponding list of +values. + +```hcl +zipmap(keyslist, valueslist) +``` + +Both `keyslist` and `valueslist` must be of the same length. `keyslist` must +be a list of strings, while `valueslist` can be a list of any type. + +Each pair of elements with the same index from the two lists will be used +as the key and value of an element in the resulting map. If the same value +appears multiple times in `keyslist` then the value with the highest index +is used in the resulting map. + +## Examples + +``` +> zipmap(["a", "b"], [1, 2]) +{ + "a" = 1, + "b" = 2, +} +```