resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: Beginnings of "Functions" configuration section 

Previously we just listed out all of the functions in alphabetical order
inside the "Interpolation Syntax" page, but that format doesn't leave much
room for details and usage examples.

Now we give each function its own page, and categorize them for easier
navigation. While many functions are very simple and don't really warrant
a full page, certain functions do have additional details that are worth
mentioning and this structure scales better for those more complicated
functions.

So far this includes only the numeric and string functions. Other
categories will follow in subsequent commits.
This commit is contained in:
Martin Atkins 2018-05-06 18:32:16 -07:00
parent 39579e8d0f
commit 48d940323e
23 changed files with 839 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
website/docs/configuration/functions.html.md Normal file
View File

@ -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.

24
website/docs/configuration/functions/abs.html.md Normal file
View File

@ -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
```

27
website/docs/configuration/functions/ceil.html.md Normal file
View File

@ -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.

30
website/docs/configuration/functions/chomp.html.md Normal file
View File

@ -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.

27
website/docs/configuration/functions/floor.html.md Normal file
View File

@ -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.

119
website/docs/configuration/functions/format.html.md Normal file
View File

@ -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.

51
website/docs/configuration/functions/formatlist.html.md Normal file
View File

@ -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.

33
website/docs/configuration/functions/indent.html.md Normal file
View File

@ -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.

31
website/docs/configuration/functions/join.md Normal file
View File

@ -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.

37
website/docs/configuration/functions/log.html.md Normal file
View File

@ -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
```

27
website/docs/configuration/functions/lower.md Normal file
View File

@ -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.

30
website/docs/configuration/functions/max.html.md Normal file
View File

@ -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.

30
website/docs/configuration/functions/min.html.md Normal file
View File

@ -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.

20
website/docs/configuration/functions/pow.html.md Normal file
View File

@ -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
```

24
website/docs/configuration/functions/replace.md Normal file
View File

@ -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
```

23
website/docs/configuration/functions/signum.html.md Normal file
View File

@ -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
```

41
website/docs/configuration/functions/split.md Normal file
View File

@ -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.

31
website/docs/configuration/functions/substr.md Normal file
View File

@ -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)
🤔
```

26
website/docs/configuration/functions/title.md Normal file
View File

@ -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.

29
website/docs/configuration/functions/trimspace.md Normal file
View File

@ -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.

27
website/docs/configuration/functions/upper.md Normal file
View File

@ -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.

2
website/docs/configuration/index.html.md
View File

@ -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

112
website/layouts/functions.erb Normal file
View File

@ -0,0 +1,112 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("docs-config-index") %>>
<a href="/docs/configuration/index.html">Terraform Language</a>
</li>
<li<%= sidebar_current("docs-config-functions") %>>
<a href="/docs/configuration/functions.html">Functions</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric") %>>
<a href="#">Numeric Functions</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-funcs-numeric-abs") %>>
<a href="/docs/configuration/functions/abs.html">abs</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-ceil") %>>
<a href="/docs/configuration/functions/ceil.html">ceil</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-floor") %>>
<a href="/docs/configuration/functions/floor.html">floor</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-log") %>>
<a href="/docs/configuration/functions/log.html">log</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-max") %>>
<a href="/docs/configuration/functions/max.html">max</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-min") %>>
<a href="/docs/configuration/functions/min.html">min</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-pow") %>>
<a href="/docs/configuration/functions/pow.html">pow</a>
</li>
<li<%= sidebar_current("docs-funcs-numeric-signum") %>>
<a href="/docs/configuration/functions/signum.html">signum</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-funcs-string") %>>
<a href="#">String Functions</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-funcs-string-chomp") %>>
<a href="/docs/configuration/functions/chomp.html">chomp</a>
</li>
<li<%= sidebar_current("docs-funcs-string-format-x") %>>
<a href="/docs/configuration/functions/format.html">format</a>
</li>
<li<%= sidebar_current("docs-funcs-string-formatlist") %>>
<a href="/docs/configuration/functions/formatlist.html">formatlist</a>
</li>
<li<%= sidebar_current("docs-funcs-string-indent") %>>
<a href="/docs/configuration/functions/indent.html">indent</a>
</li>
<li<%= sidebar_current("docs-funcs-string-join") %>>
<a href="/docs/configuration/functions/join.html">join</a>
</li>
<li<%= sidebar_current("docs-funcs-string-lower") %>>
<a href="/docs/configuration/functions/lower.html">lower</a>
</li>
<li<%= sidebar_current("docs-funcs-string-replace") %>>
<a href="/docs/configuration/functions/replace.html">replace</a>
</li>
<li<%= sidebar_current("docs-funcs-string-split") %>>
<a href="/docs/configuration/functions/split.html">split</a>
</li>
<li<%= sidebar_current("docs-funcs-string-substr") %>>
<a href="/docs/configuration/functions/substr.html">substr</a>
</li>
<li<%= sidebar_current("docs-funcs-string-title") %>>
<a href="/docs/configuration/functions/title.html">title</a>
</li>
<li<%= sidebar_current("docs-funcs-string-trimspace") %>>
<a href="/docs/configuration/functions/trimspace.html">trimspace</a>
</li>
<li<%= sidebar_current("docs-funcs-string-upper") %>>
<a href="/docs/configuration/functions/upper.html">upper</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>
<%= yield %>
<% end %>