diff --git a/website/docs/configuration/functions.html.md b/website/docs/configuration/functions.html.md new file mode 100644 index 000000000..d9d95f636 --- /dev/null +++ b/website/docs/configuration/functions.html.md @@ -0,0 +1,39 @@ +--- +layout: "functions" +page_title: "Configuration Functions" +sidebar_current: "docs-config-functions" +description: |- + The Terraform language has a number of built-in functions that can be called + from within expressions to transform and combine values. +--- + +# Built-in Functions + +The Terraform language includes a number of built-in functions that you can +call from within expressions to transform and combine values. The general +syntax for function calls is a function name followed by comma-separated +arguments in parentheses: + +```hcl +max(5, 12, 9) +``` + +For more details on syntax, see +[_Function Calls_](/docs/configuration/expressions.html#function-calls) +on the Expressions page. + +The Terraform language does not support user-defined functions, and so only +the functions built in to the language are available for use. The navigation +includes a list of all of the available built-in functions. + +You can experiment with the behavior of Terraform's built-in functions from +the Terraform expression console, by running +[the `terraform console` command](/docs/commands/console.html): + +``` +> max(5, 12, 9) +12 +``` + +The examples in the documentation for each function use console output to +illustrate the result of calling the function with different parameters. diff --git a/website/docs/configuration/functions/abs.html.md b/website/docs/configuration/functions/abs.html.md new file mode 100644 index 000000000..b0766e078 --- /dev/null +++ b/website/docs/configuration/functions/abs.html.md @@ -0,0 +1,24 @@ +--- +layout: "functions" +page_title: "abs function" +sidebar_current: "docs-funcs-numeric-abs" +description: |- + The abs function returns the absolute value of the given number. +--- + +# `abs` Function + +`abs` returns the absolute value of the given number. In other words, if the +number is zero or positive then it is returned as-is, but if it is negative +then it is multiplied by -1 to make it positive before returning it. + +## Examples + +``` +> abs(23) +23 +> abs(0) +0 +> abs(-12.4) +12.4 +``` diff --git a/website/docs/configuration/functions/ceil.html.md b/website/docs/configuration/functions/ceil.html.md new file mode 100644 index 000000000..af922259c --- /dev/null +++ b/website/docs/configuration/functions/ceil.html.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "ceil function" +sidebar_current: "docs-funcs-numeric-ceil" +description: |- + The ceil function returns the closest whole number greater than or equal to + the given value. +--- + +# `ceil` Function + +`ceil` returns the closest whole number that is greater than or equal to the +given value, which may be a fraction. + +## Examples + +``` +> ceil(5) +5 +> ceil(5.1) +6 +``` + +## Related Functions + +* [`floor`](./floor.html), which rounds to the nearest whole number _less than_ + or equal. diff --git a/website/docs/configuration/functions/chomp.html.md b/website/docs/configuration/functions/chomp.html.md new file mode 100644 index 000000000..4fe115c58 --- /dev/null +++ b/website/docs/configuration/functions/chomp.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "chomp function" +sidebar_current: "docs-funcs-string-chomp" +description: |- + The chomp function removes newline characters at the end of a string. +--- + +# `chomp` Function + +`chomp` removes newline characters at the end of a string. + +This can be useful if, for example, the string was read from a file that has +a newline character at the end. + +## Examples + +``` +> chomp("hello\n") +hello +> chomp("hello\r\n") +hello +> chomp("hello\n\n") +hello +``` + +## Related Functions + +* [`trimspace`](./trimspace.html), which removes all types of whitespace from + both the start and the end of a string. diff --git a/website/docs/configuration/functions/floor.html.md b/website/docs/configuration/functions/floor.html.md new file mode 100644 index 000000000..00408434e --- /dev/null +++ b/website/docs/configuration/functions/floor.html.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "floor function" +sidebar_current: "docs-funcs-numeric-floor" +description: |- + The floor function returns the closest whole number less than or equal to + the given value. +--- + +# `floor` Function + +`floor` returns the closest whole number that is less than or equal to the +given value, which may be a fraction. + +## Examples + +``` +> floor(5) +5 +> floor(4.9) +4 +``` + +## Related Functions + +* [`ceil`](./ceil.html), which rounds to the nearest whole number _greater than_ + or equal. diff --git a/website/docs/configuration/functions/format.html.md b/website/docs/configuration/functions/format.html.md new file mode 100644 index 000000000..86900e14f --- /dev/null +++ b/website/docs/configuration/functions/format.html.md @@ -0,0 +1,119 @@ +--- +layout: "functions" +page_title: "format function" +sidebar_current: "docs-funcs-string-format-x" +description: |- + The format function produces a string by formatting a number of other values + according to a specification string. +--- + +# `format` Function + +`format` produces a string by formatting a number of other values according +to a specification string. It is similar to the `printf` function in C, and +other similar functions in other programming languages. + +```hcl +format(spec, values...) +``` + +## Examples + +``` +> format("Hello, %s!", "Ander") +Hello, Ander! +> format("There are %d lights", 4) +There are 4 lights +``` + +Simple format verbs like `%s` and `%d` behave similarly to template +interpolation syntax, which is often more readable: + +``` +> format("Hello, %s!", var.name) +Hello, Valentina! +> "Hello, ${var.name}!" +Hello, Valentina! +``` + +The `format` function is therefore more useful when you use more complex format +specifications, as described in the following section. + +## Specification Syntax + +The specification is a string that includes formatting verbs that are introduced +with the `%` character. The function call must then have one additional argument +for each verb sequence in the specification. The verbs are matched with +consecutive arguments and formatted as directed, as long as each given argument +is convertible to the type required by the format verb. + +The specification may contain the following verbs: + +| Verb | Result | +| ----- | ----------------------------------------------------------------------------------------- | +| `%%` | Literal percent sign, consuming no value. | +| `%v` | Default formatting based on the value type, as described below. | +| `%#v` | JSON serialization of the value, as with `jsonencode`. | +| `%t` | Convert to boolean and produce `true` or `false`. | +| `%b` | Convert to integer number and produce binary representation. | +| `%d` | Convert to integer number and produce decimal representation. | +| `%o` | Convert to integer number and produce octal representation. | +| `%x` | Convert to integer number and produce hexadecimal representation with lowercase letters. | +| `%X` | Like `%x`, but use uppercase letters. | +| `%e` | Convert to number and produce scientific notation, like `-1.234456e+78`. | +| `%E` | Like `%e`, but use an uppercase `E` to introduce the exponent. | +| `%f` | Convert to number and produce decimal fraction notation with no exponent, like `123.456`. | +| `%g` | Like `%e` for large exponents or like `%f` otherwise. | +| `%G` | Like `%E` for large exponents or like `%f` otherwise. | +| `%s` | Convert to string and insert the string's characters. | +| `%q` | Convert to string and produce a JSON quoted string representation. | + +When `%v` is used, one of the following format verbs is chosen based on the value type: + +| Type | Verb | +| --------- | ----- | +| `string` | `%s` | +| `number` | `%g` | +| `bool` | `%t` | +| any other | `%#v` | + +Null values produce the string `null` if formatted with `%v` or `%#v`, and +cause an error for other verbs. + +A width modifier can be included with an optional decimal number immediately +preceding the verb letter, to specify how many characters will be used to +represent the value. Precision can be specified after the (optional) width +with a period (`.`) followed by a decimal number. If width or precision are +omitted then default values are selected based on the given value. For example: + +| Sequence | Result | +| -------- | ---------------------------- | +| `%f` | Default width and precision. | +| `%9f` | Width 9, default precision. | +| `%.2f` | Default width, precision 2. | +| `%9.2f` | Width 9, precision 2. | + +The following additional symbols can be used immediately after the `%` symbol +to set additoinal flags: + +| Symbol | Result | +| ------ | -------------------------------------------------------------- | +| space | Leave a space where the sign would be if a number is positive. | +| `+` | Show the sign of a number even if it is positive. | +| `-` | Pad the width with spaces on the left rather than the right. | +| `0` | Pad the width with zeros rather than spaces. | + +By default, `%` sequences consume successive arguments starting with the first. +Introducing a `[n]` sequence immediately before the verb letter, where `n` is a +decimal integer, explicitly chooses a particular value argument by its +one-based index. Subsequent calls without an explicit index will then proceed +with `n`+1, `n`+2, etc. + +The function produces an error if the format string requests an impossible +conversion or access more arguments than are given. An error is produced also +for an unsupported format verb. + +## Related Functions + +* [`formatlist`](./formatlist.html) uses the same specification syntax to + produce a list of strings. diff --git a/website/docs/configuration/functions/formatlist.html.md b/website/docs/configuration/functions/formatlist.html.md new file mode 100644 index 000000000..8ad3dccac --- /dev/null +++ b/website/docs/configuration/functions/formatlist.html.md @@ -0,0 +1,51 @@ +--- +layout: "functions" +page_title: "formatlist function" +sidebar_current: "docs-funcs-string-formatlist" +description: |- + The formatlist function produces a list of strings by formatting a number of + other values according to a specification string. +--- + +# `formatlist` Function + +`formatlist` produces a list of strings by formatting a number of other +values according to a specification string. + +```hcl +formatlist(spec, values...) +``` + +The specification string uses +[the same syntax as `format`](./format.html#specification-syntax). + +The given values can be a mixture of list and non-list arguments. Any given +lists must be the same length, which decides the length of the resulting list. + +The list arguments are iterated together in order by index, while the non-list +arguments are used repeatedly for each iteration. The format string is evaluated +once per element of the list arguments. + +## Examples + +``` +> formatlist("Hello, %s!", ["Valentina", "Ander", "Olivia", "Sam"]) +[ + "Hello, Valentina!", + "Hello, Ander!", + "Hello, Olivia!", + "Hello, Sam!", +] +> formatlist("%s, %s!", "Salutations", ["Valentina", "Ander", "Olivia", "Sam"]) +[ + "Salutations, Valentina!", + "Salutations, Ander!", + "Salutations, Olivia!", + "Salutations, Sam!", +] +``` + +## Related Functions + +* [`format`](./format.html) defines the specification syntax used by this + function and produces a single string as its result. diff --git a/website/docs/configuration/functions/indent.html.md b/website/docs/configuration/functions/indent.html.md new file mode 100644 index 000000000..6ea79fedc --- /dev/null +++ b/website/docs/configuration/functions/indent.html.md @@ -0,0 +1,33 @@ +--- +layout: "functions" +page_title: "indent function" +sidebar_current: "docs-funcs-string-indent" +description: |- + The indent function adds a number of spaces to the beginnings of all but the + first line of a given multi-line string. +--- + +# `indent` Function + +`indent` adds a given number of spaces to the beginnings of all but the first +line in a given multi-line string. + +```hcl +indent(num_spaces, string) +``` + +## Examples + +This function is useful for inserting a multi-line string into an +already-indented context in another string: + +``` +> " items: %{indent(2, "[\n foo,\n bar,\n]\n")}" + items: [ + foo, + bar, + ] +``` + +The first line of the string is not indented so that, as above, it can be +placed after an introduction sequence that has already begun the line. diff --git a/website/docs/configuration/functions/join.md b/website/docs/configuration/functions/join.md new file mode 100644 index 000000000..e7dfa4c6e --- /dev/null +++ b/website/docs/configuration/functions/join.md @@ -0,0 +1,31 @@ +--- +layout: "functions" +page_title: "join function" +sidebar_current: "docs-funcs-string-join" +description: |- + The join function produces a string by concatenating the elements of a list + with a given delimiter. +--- + +# `join` Function + +`join` produces a string by concatenating together all elements of a given +list of strings with the given delimiter. + +```hcl +join(separator, list) +``` + +## Examples + +``` +> join(", ", ["foo", "bar", "baz"]) +foo, bar, baz +> join(", ", ["foo"]) +foo +``` + +## Related Functions + +* [`split`](./split.html) performs the opposite operation: producing a list + by separating a single string using a given delimiter. diff --git a/website/docs/configuration/functions/log.html.md b/website/docs/configuration/functions/log.html.md new file mode 100644 index 000000000..3869b5fe6 --- /dev/null +++ b/website/docs/configuration/functions/log.html.md @@ -0,0 +1,37 @@ +--- +layout: "functions" +page_title: "log function" +sidebar_current: "docs-funcs-numeric-log" +description: |- + The log function returns the closest whole number less than or equal to + the given value. +--- + +# `log` Function + +`log` returns the the logarithm of a given number in a given base. + +```hcl +log(number, base) +``` + +## Examples + +``` +> log(50, 10) +1.6989700043360185 +> log(16, 2) +4 +``` + +`log` and `ceil` can be used together to find the minimum number of binary +digits required to represent a given number of distinct values: + +``` +> ceil(log(15, 2)) +4 +> ceil(log(16, 2)) +4 +> ceil(log(17, 2)) +5 +``` diff --git a/website/docs/configuration/functions/lower.md b/website/docs/configuration/functions/lower.md new file mode 100644 index 000000000..9e73fe91b --- /dev/null +++ b/website/docs/configuration/functions/lower.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "lower function" +sidebar_current: "docs-funcs-string-lower" +description: |- + The lower function converts all cased letters in the given string to lowercase. +--- + +# `lower` Function + +`lower` converts all cased letters in the given string to lowercase. + +## Examples + +``` +> lower("HELLO") +hello +> lower("АЛЛО!") +алло! +``` + +This function uses Unicode's definition of letters and of upper- and lowercase. + +## Related Functions + +* [`upper`](./upper.html) converts letters in a string to _uppercase_. +* [`title`](./title.html) converts the first letter of each word in a string to uppercase. diff --git a/website/docs/configuration/functions/max.html.md b/website/docs/configuration/functions/max.html.md new file mode 100644 index 000000000..c8813325e --- /dev/null +++ b/website/docs/configuration/functions/max.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "max function" +sidebar_current: "docs-funcs-numeric-max" +description: |- + The max function takes one or more numbers and returns the greatest number. +--- + +# `max` Function + +`max` takes one or more numbers and returns the greatest number from the set. + +## Examples + +``` +> max(12, 54, 3) +54 +``` + +If the numbers are in a list or set value, use `...` to expand the collection +to individual arguments: + +``` +> max([12, 54, 3]...) +54 +``` + +## Related Functions + +* [`min`](./min.html), which returns the _smallest_ number from a set. diff --git a/website/docs/configuration/functions/min.html.md b/website/docs/configuration/functions/min.html.md new file mode 100644 index 000000000..52791c068 --- /dev/null +++ b/website/docs/configuration/functions/min.html.md @@ -0,0 +1,30 @@ +--- +layout: "functions" +page_title: "min function" +sidebar_current: "docs-funcs-numeric-min" +description: |- + The min function takes one or more numbers and returns the smallest number. +--- + +# `min` Function + +`min` takes one or more numbers and returns the smallest number from the set. + +## Examples + +``` +> min(12, 54, 3) +3 +``` + +If the numbers are in a list or set value, use `...` to expand the collection +to individual arguments: + +``` +> min([12, 54, 3]...) +3 +``` + +## Related Functions + +* [`max`](./max.html), which returns the _greatest_ number from a set. diff --git a/website/docs/configuration/functions/pow.html.md b/website/docs/configuration/functions/pow.html.md new file mode 100644 index 000000000..284f905d7 --- /dev/null +++ b/website/docs/configuration/functions/pow.html.md @@ -0,0 +1,20 @@ +--- +layout: "functions" +page_title: "pow function" +sidebar_current: "docs-funcs-numeric-pow" +description: |- + The pow function raises a number to a power. +--- + +# `pow` Function + +`pow` raises a number to a given power. That is, it calcluates the exponent. + +## Examples + +``` +> pow(3, 2) +9 +> pow(4, 0) +1 +``` diff --git a/website/docs/configuration/functions/replace.md b/website/docs/configuration/functions/replace.md new file mode 100644 index 000000000..3dfaa2b42 --- /dev/null +++ b/website/docs/configuration/functions/replace.md @@ -0,0 +1,24 @@ +--- +layout: "functions" +page_title: "replace function" +sidebar_current: "docs-funcs-string-replace" +description: |- + The replace function searches a given string for another given substring, + and replaces all occurences with a given replacement string. +--- + +# `replace` Function + +`replace` searches a given string for another given substring, and replaces +each occurence with a given replacement string. + +```hcl +replace(string, substring, replacement) +``` + +## Examples + +``` +> replace("1 + 2 + 3", "+", "-") +1 - 2 - 3 +``` diff --git a/website/docs/configuration/functions/signum.html.md b/website/docs/configuration/functions/signum.html.md new file mode 100644 index 000000000..37472501a --- /dev/null +++ b/website/docs/configuration/functions/signum.html.md @@ -0,0 +1,23 @@ +--- +layout: "functions" +page_title: "signum function" +sidebar_current: "docs-funcs-numeric-signum" +description: |- + The signum function determines the sign of a number. +--- + +# `signum` Function + +`signum` determines the sign of a number, returning a number between -1 and +1 to represent the sign. + +## Examples + +``` +> signum(-13) +-1 +> signum(0) +0 +> signum(344) +1 +``` diff --git a/website/docs/configuration/functions/split.md b/website/docs/configuration/functions/split.md new file mode 100644 index 000000000..4ed7c17dc --- /dev/null +++ b/website/docs/configuration/functions/split.md @@ -0,0 +1,41 @@ +--- +layout: "functions" +page_title: "split function" +sidebar_current: "docs-funcs-string-split" +description: |- + The split function produces a list by dividing a given string at all + occurences of a given separator. +--- + +# `split` Function + +`split` produces a list by dividing a given string at all occurences of a +given separator. + +```hcl +split(separator, string) +``` + +## Examples + +``` +> split(",", "foo,bar,baz") +[ + "foo", + "bar", + "baz", +] +> split(",", "foo") +[ + "foo", +] +> split(",", "") +[ + "", +] +``` + +## Related Functions + +* [`join`](./join.html) performs the opposite operation: producing a string + joining together a list of strings with a given separator. diff --git a/website/docs/configuration/functions/substr.md b/website/docs/configuration/functions/substr.md new file mode 100644 index 000000000..e45b363d0 --- /dev/null +++ b/website/docs/configuration/functions/substr.md @@ -0,0 +1,31 @@ +--- +layout: "functions" +page_title: "substr function" +sidebar_current: "docs-funcs-string-substr" +description: |- + The substr function extracts a substring from a given string by offset and + length. +--- + +# `substr` Function + +`substr` extracts a substring from a given string by offset and length. + +```hcl +substr(string, offset, length) +``` + +## Examples + +``` +> substr("hello world", 1, 4) +ello +``` + +The offset and length are both counted in _unicode characters_ rather than +bytes: + +``` +> substr("🤔🤷", 0, 1) +🤔 +``` diff --git a/website/docs/configuration/functions/title.md b/website/docs/configuration/functions/title.md new file mode 100644 index 000000000..c0e5ff6f8 --- /dev/null +++ b/website/docs/configuration/functions/title.md @@ -0,0 +1,26 @@ +--- +layout: "functions" +page_title: "title function" +sidebar_current: "docs-funcs-string-title" +description: |- + The title function converts the first letter of each word in a given string + to uppercase. +--- + +# `title` Function + +`title` converts the first letter of each word in the given string to uppercase. + +## Examples + +``` +> title("hello world") +Hello World +``` + +This function uses Unicode's definition of letters and of upper- and lowercase. + +## Related Functions + +* [`upper`](./upper.html) converts _all_ letters in a string to uppercase. +* [`lower`](./lower.html) converts all letters in a string to lowercase. diff --git a/website/docs/configuration/functions/trimspace.md b/website/docs/configuration/functions/trimspace.md new file mode 100644 index 000000000..b704bbfdf --- /dev/null +++ b/website/docs/configuration/functions/trimspace.md @@ -0,0 +1,29 @@ +--- +layout: "functions" +page_title: "trimspace function" +sidebar_current: "docs-funcs-string-trimspace" +description: |- + The trimspace function removes space characters from the start and end of + a given string. +--- + +# `trimspace` Function + +`trimspace` removes any space characters from the start and end of the given +string. + +This function follows the Unicode definition of "space", which includes +regular spaces, tabs, newline characters, and various other space-like +characters. + +## Examples + +``` +> trimspace(" hello\n\n") +hello +``` + +## Related Functions + +* [`chomp`](./chomp.html) removes just line ending characters from the _end_ of + a string. diff --git a/website/docs/configuration/functions/upper.md b/website/docs/configuration/functions/upper.md new file mode 100644 index 000000000..cfede515e --- /dev/null +++ b/website/docs/configuration/functions/upper.md @@ -0,0 +1,27 @@ +--- +layout: "functions" +page_title: "upper function" +sidebar_current: "docs-funcs-string-upper" +description: |- + The upper function converts all cased letters in the given string to uppercase. +--- + +# `upper` Function + +`upper` converts all cased letters in the given string to uppercase. + +## Examples + +``` +> upper("hello") +HELLO +> upper("алло!") +АЛЛО! +``` + +This function uses Unicode's definition of letters and of upper- and lowercase. + +## Related Functions + +* [`lower`](./lower.html) converts letters in a string to _lowercase_. +* [`title`](./title.html) converts the first letter of each word in a string to uppercase. diff --git a/website/docs/configuration/index.html.md b/website/docs/configuration/index.html.md index 72074e16f..a7dc5abf1 100644 --- a/website/docs/configuration/index.html.md +++ b/website/docs/configuration/index.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "Configuration" -sidebar_current: "docs-config" +sidebar_current: "docs-config-index" description: |- Terraform uses text files to describe infrastructure and to set variables. These text files are called Terraform _configurations_ and are diff --git a/website/layouts/functions.erb b/website/layouts/functions.erb new file mode 100644 index 000000000..74c248a78 --- /dev/null +++ b/website/layouts/functions.erb @@ -0,0 +1,112 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> + <% end %> + \ No newline at end of file