Commit Graph

22 Commits

Author SHA1 Message Date
Nick Fagerlund 2c50808bbb website: Version notes: Add new -> old links to 0.12 language docs (function pages) 2019-02-01 17:20:54 -08:00
Martin Atkins 954d38e870 lang: New file-hashing functions
In prior versions, we recommended using hash functions in conjunction with
the file function as an idiom for detecting changes to upstream blobs
without fetching and comparing the whole blob.

That approach relied on us being able to return raw binary data from
file(...). Since Terraform strings pass through intermediate
representations that are not binary-safe (e.g. the JSON state), there was
a risk of string corruption in prior versions which we have avoided for
0.12 by requiring that file(...) be used only with UTF-8 text files.

The specific case of returning a string and immediately passing it into
another function was not actually subject to that corruption risk, since
the HIL interpreter would just pass the string through verbatim, but this
is still now forbidden as a result of the stricter handling of file(...).

To avoid breaking these use-cases, here we introduce variants of the hash
functions a with "file" prefix that take a filename for a disk file to
hash rather than hashing the given string directly. The configuration
upgrade tool also now includes a rule to detect the documented idiom and
rewrite it into a single function call for one of these new functions.

This does cause a bit of function sprawl, but that seems preferable to
introducing more complex rules for when file(...) can and cannot read
binary files, making the behavior of these various functions easier to
understand in isolation.
2019-01-25 10:18:44 -08:00
Martin Atkins 2f8f7d6f4d 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 10:01:47 -08:00
Martin Atkins da51e72cbb lang/functions: set functions from cty
The sethaselement, setintersection, and setunion functions are defined in
the cty stdlib. Making them available in Terraform will make it easier to
work with sets, and complement the currently-Terraform-specific setproduct
function.

In the long run setproduct should probably move into the cty stdlib too,
but since it was submitted as a Terraform function originally we'll leave
it here now for simplicity's sake and reorganize later.
2019-01-16 09:57:16 -08:00
Martin Atkins edb5f82de1 lang/funcs: Convert the "setproduct" function to the new approach
In our new world it produces either a set of a tuple type or a list of a
tuple type, depending on the given argument types.

The resulting collection's element tuple type is decided by the element
types of the given collections, allowing type information to propagate
even if unknown values are present.
2019-01-16 09:57:16 -08:00
Martin Atkins d0e6a4c69a lang: Add "formatdate" function
We missed this one on a previous pass of bringing in most of the cty
stdlib functions.

This will resolve #17625 by allowing conversion from Terraform's
conventional RFC 3339 timestamps into various other formats.
2019-01-07 09:10:14 -08:00
Martin Atkins c753df6a93 lang/funcs: templatefile function
This function is similar to the template_file data source offered by the
template provider, but having it built in to the language makes it more
convenient to use, allowing templates to be rendered from files anywhere
an inline template would normally be allowed:

    user_data = templatefile("${path.module}/userdata.tmpl", {
      hostname = format("petserver%02d", count.index)
    })

Unlike the template_file data source, this function allows values of any
type in its variables map, passing them through verbatim to the template.
Its tighter integration with Terraform also allows it to return better
error messages with source location information from the template itself.

The template_file data source was originally created to work around the
fact that HIL didn't have any support for map values at the time, and
even once map support was added it wasn't very usable. With HCL2
expressions, there's little reason left to use a data source to render
a template; the only remaining reason left to use template_file is to
render a template that is constructed dynamically during the Terraform
run, which is a very rare need.
2018-12-21 08:06:14 -08:00
Nick Fagerlund 17873ae61b website: Update functions section page titles 2018-12-20 14:20:42 -08:00
Nick Fagerlund d2abdc23ac website: Structural edit of configuration language docs
This commit is a wide-ranging set of edits to the pages under
/docs/configuration. Among other things, it

- Separates style conventions out into their own page.
- Separates type constraints and conversion info into their own page.
- Conflates similar complex types a little more freely, since the distinction is
  only relevant when restricting inputs for a reusable module or resource.
- Clarifies several concepts that confused me during edits.
2018-12-20 14:20:42 -08:00
Radek Simko edaa4bbc82
lang: Add fileexists function 2018-10-17 10:18:07 +01:00
Martin Atkins 1360948a41 website: document the functions "keys", "lookup", and "values"
I missed these on the first pass because in the legacy function table they
are, for some reason, added in a different place than the others.
2018-10-16 18:49:20 -07:00
Kristin Laemmert b6d3d69d3a port cidr functions 2018-10-16 18:49:20 -07:00
Kristin Laemmert 602b59cdc4 porting functions 2018-10-16 18:49:20 -07:00
Kristin Laemmert 9aa9b18658 porting crypto functions 2018-10-16 18:49:20 -07:00
Kristin Laemmert 1a5299efcb porting encoding functions 2018-10-16 18:49:20 -07:00
Martin Atkins 83a16e3deb website: Docs for all of the IP address calculation functions 2018-10-16 18:47:33 -07:00
Martin Atkins 7cb1de9f30 website: Docs for all of the hash/crypto functions 2018-10-16 18:47:33 -07:00
Martin Atkins 46f8208727 website: Docs for all of the Date and Time functions 2018-10-16 18:47:33 -07:00
Martin Atkins a35c0f3cbf website: Docs for all of the "filesystem" functions 2018-10-16 18:47:33 -07:00
Martin Atkins a491013054 website: Docs for all of the "encoding" functions 2018-10-16 18:47:33 -07:00
Martin Atkins e7d71995f6 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-10-16 18:47:33 -07:00
Martin Atkins 48d940323e 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.
2018-10-16 18:47:33 -07:00