Commit Graph

87 Commits

Author SHA1 Message Date
Arthur Burkart 6ed47c7241
lang/funcs: Add "alltrue" function (#25656)
This commit adds an `alltrue` function to Terraform configuration. A
reason we might want this function is because it will enable more
powerful custom variable validations. For example:

```hcl
variable "amis" {
  type = list(object({
    id = string
  }))

  validation {
    condition = (alltrue([
      for a in var.amis : length(a.id) > 4 && substr(a.id, 0, 4) == "ami-"
    ]))
    error_message = "The ID of at least one AMI was invalid."
  }
}
```
2020-09-22 09:06:42 -04:00
Brian Flad db2b710776
docs/function/timestamp: Mention Time Provider (#26232)
This utility Terraform Provider has resources designed to handle and store time information by participating normally in the graph.
2020-09-14 16:40:36 -04:00
Jon "The Nice Guy" Spriggs 6f9ce7310c
Website: Add map example to templatefile function docs (#26126)
This change adds an example of using a map with a few keys and shows how it runs it.

Co-authored-by: Nick Fagerlund <nick@hashicorp.com>
2020-09-09 12:30:06 -07:00
Alisdair McDiarmid 9f19034fee website: Document jsonencode entity escaping 2020-09-04 09:18:52 -04:00
Pam Selle f2d213c461
Merge pull request #25657 from pdecat/typo_hierarchical
Typo: heirarchical => hierarchical
2020-08-28 12:37:49 -04:00
Nicolas Vogel 8f42f0fa77
Fix documentation example for the indent function
We must use interpolation, using the %{} directive will trigger the following error  "indent" is not a valid template control keyword
2020-08-10 11:45:28 +02:00
Patrick Decat 062865735f Typo: heirarchical => hierarchical 2020-07-23 15:09:22 +02:00
Kristin Laemmert c4ce84269a
website/docs: document difference in formatting strings with width and precision (#25499) 2020-07-07 14:09:39 -04:00
Alisdair McDiarmid c093c50c80
Merge pull request #25255 from unki/patch-1
fix yamldecode()-example, missing a file() call
2020-06-24 10:31:08 -04:00
jessica-ritter edbf59ed4c
what happens when prefix is not in string
https://github.com/hashicorp/terraform/blob/master/lang/functions.go#L126 shows that Terraform's Trimprefix comes directly from the standard go library. 
When prefix is absent in the go standard library, the original string is returned; https://golang.org/pkg/strings/#TrimPrefix.
2020-06-22 11:31:08 -07:00
unki 214009e0f3
fix yamldecode()-example, missing a file() call 2020-06-16 09:56:03 +02:00
Martin Atkins d1bc412220 configs: Custom variable validation is no longer experimental
All of the feedback from the experiment described enhancements that can
potentially be added later without breaking changes, so this change simply
removes the experiment gate from the feature as originally implemented
with no changes to its functionality.

Further enhancements may follow in later releases, but the goal of this
change is just to ship the feature exactly as it was under the experiment.

Most of the changes here are cleaning up the experiment opt-ins from our
test cases. The most important parts are in configs/experiments.go and in
experiments/experiment.go .
2020-05-28 16:07:59 -07:00
Daniel Dreier 44e3d99409
Merge pull request #24659 from hashicorp/timestamp-doc
specify that `timestamp` returns UTC
2020-05-21 14:30:16 -07:00
Daniel Dreier 5e35dedc2a
Update website/docs/configuration/functions/timestamp.html.md
Co-authored-by: Matthew Sanabria <24284972+sudomateo@users.noreply.github.com>
2020-05-21 14:29:38 -07:00
Daniel Dreier 7aa97f415d
Fix "additoinal" typo in web site
Fixes 24769
2020-04-27 10:14:27 -07:00
Noah Mercado d4d8812afa
Feature: Sum Function (#24666)
The sum function takes a list or set of numbers and returns the sum of those
numbers.
2020-04-15 14:27:06 -04:00
Namho Kim 9cc658b491 specify that `timestamp` returns UTC 2020-04-13 18:09:05 -07:00
Eduard Tamsa 534ba630e4
docs(flatten): Fix typos (#24492) 2020-04-10 08:59:17 -04:00
Adam Leskis 4f85a1a6ba
website: fix simple typo (#24415) 2020-03-23 08:55:08 -04:00
Martin Atkins 67d95b97ce lang/funcs: templatefile requires valid variable names
Previously the templatefile function would permit any arbitrary string as
a variable name, but due to the HCL template syntax it would be impossible
to refer to one that isn't a valid HCL identifier without causing an
HCL syntax error.

The HCL syntax errors are correct, but don't really point to the root
cause of the problem. Instead, we'll pre-verify that the variable names
are valid before we even try to render the template, and given a
specialized error message that refers to the vars argument expression as
the problematic part, which will hopefully make the resolution path
clearer for a user encountering this situation.

The syntax error still remains for situations where all of the variable
names are correct but e.g. the user made a typo referring to one, which
makes sense because in that case the problem _is_ inside the template.
2020-02-25 10:19:46 -05:00
James Bardin 4185aa93f5 doc typo 2020-02-13 21:27:35 -05:00
James Bardin a765d69fb0
Merge pull request #24032 from hashicorp/jbardin/map-funcs
make the merge function more precise
2020-02-12 10:51:05 -05:00
James Goodhouse 25bfe7337b
lang: add setsubtract function (#23424)
* add setdifference and setsubtract functions and docs
* remove setdifference as it is not implemented correct in underlying lib

* Update setintersection.html.md
* Update setproduct.html.md
* Update setunion.html.md
2020-02-06 12:49:11 -05:00
James Bardin 529271e0be update merge docs to match behavior 2020-02-05 15:47:36 -05:00
ZMI-RyanMann 66411b5ca0 website/docs: Updated documentation for range function pseudocode (#23823) 2020-01-13 09:17:47 -05:00
Martin Atkins ff4ea042c2 config: Allow module authors to specify validation rules for variables
The existing "type" argument allows specifying a type constraint that
allows for some basic validation, but often there are more constraints on
a variable value than just its type.

This new feature (requiring an experiment opt-in for now, while we refine
it) allows specifying arbitrary validation rules for any variable which
can then cause custom error messages to be returned when a caller provides
an inappropriate value.

    variable "example" {
      validation {
        condition = var.example != "nope"
        error_message = "Example value must not be \"nope\"."
      }
    }

The core parts of this are designed to do as little new work as possible
when no validations are specified, and thus the main new checking codepath
here can therefore only run when the experiment is enabled in order to
permit having validations.
2020-01-10 15:23:25 -08:00
Martin Atkins 02576988c1 lang: "try" and "can" functions
These are intended to make it easier to work with arbitrary data
structures whose shape might not be known statically, such as the result
of jsondecode(...) or yamldecode(...) of data from a separate system.

For example, in an object value which has attributes that may or may not
be set we can concisely provide a fallback value to use when the attribute
isn't set:

    try(local.example.foo, "fallback-foo")

Using a "try to evaluate" model rather than explicit testing fits better
with the usual programming model of the Terraform language where values
are normally automatically converted to the necessary type where possible:
the given expression is subject to all of the same normal type conversions,
which avoids inadvertently creating a more restrictive evaluation model
as might happen if this were handled using checks like a hypothetical
isobject(...) function, etc.
2020-01-10 15:23:25 -08:00
Martin Atkins bfbd00a23c website: Note about using jsonencode/yamlencode in templatefile
It's a common source of errors to try to produce JSON or YAML syntax
using string concatenation via our template language but to miss some
details like correct string escaping, quoting, required commas, etc.

The jsonencode and yamlencode functions are a better way to generate JSON
and YAML, but it's not immediately obvious that both of these functions
are available for use in external templates (via templatefile) too.

Given that questions related to this come up a lot in our community forum
and elsewhere, it seems worth having a documentation section to show the
pattern of having a template that consists only of a single function call.
2019-12-11 12:57:01 -08:00
Graham Davison e32641c9ce website/docs: Corrects function name in `cidrsubnets` function documentation (#23473) 2019-11-26 07:50:32 -05:00
George Christou 91100c003c lang/funcs: Add more `trim*` functions (#23016)
* lang/funcs: Add `trim*` functions
2019-11-18 08:31:44 -05:00
Yuki Ito 72c910cebc website: Fix typographical errors in the docs for base64sha256/512 2019-11-08 09:43:27 -08:00
Martin Atkins 047733d20c website: Full examples for for_each with flatten and setproduct
A very common question since we launched the two repetition constructs
is how to deal with situations where the input data structure doesn't
match one-to-one with the desired configuration.

This adds some full worked examples of two common situations that have
come up in questions. To avoid adding a lot of extra content to the
already-large "expressions" and "resources" pages, the main bulk of this
new content lives with the relevant functions themselves as a full example
of one thing they are good for, and then we'll link to them from the two
general documentation sections where folks are likely to be reading when
they encounter the problem.
2019-10-11 13:41:58 -07:00
Martin Atkins 25222fccd5 website: Link to hashicorp/subnets/cidr for cidrsubnets docs
The cidrsubnets function signature is intentionally very low-level and
focused on the core requirement of generating addresses. This registry
module then wraps it with some additional functionality to make it more
convenient to generate and use subnet address ranges.
2019-09-23 13:15:44 -07:00
Martin Atkins f84ab99b7d lang/funcs: cidrsubnets function
This is a companion to cidrsubnet that allows bulk-allocation of multiple
subnet addresses at once, with automatic numbering.

Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a
different prefix length, and will pack the networks consecutively into the
given address space. cidrsubnets can potentially create more complicated
addressing schemes than cidrsubnet alone can, because it's able to take
into account the full set of requested prefix lengths rather than just
one at a time.
2019-09-20 15:58:01 -07:00
Jeet Parekh bcc69c05bb lang/funcs: parseint function 2019-09-17 15:33:22 -07:00
Pam Selle f9ebae749c
Merge pull request #22707 from vsimon/spell
docs: Minor spelling and typo fixes
2019-09-06 11:46:01 -04:00
Vicken Simonian 853a0e0677 docs: Minor spelling and typo fixes 2019-09-05 10:08:34 -07:00
Brian Flad 19cf34114f
lang/funcs: Switch fileset() function glob implementation to github.com/bmatcuk/doublestar to support additional glob patterns
This allows the usage of the glob patterns `**` and `{alternative1,...}` to simplify Terraform configuration logic for more complex file matching.
2019-08-30 20:22:03 -04:00
Brian Flad af7f6ef441
lang/funcs: Update fileset() function to include path as separate first argument, automatically trim the path argument from results, and ensure results are always canonical with forward slash path separators
Reference: https://github.com/hashicorp/terraform/pull/22523#pullrequestreview-279694703

These changes center around better function usability and consistency with other functions. The function has not yet been released, so these breaking changes can be applied safely.
2019-08-30 20:19:44 -04:00
Pam Selle 6e614f3465 Fix docs mistake/misleading 2019-08-28 11:38:26 -04:00
Brian Flad d48d9ed766
lang/funcs: Add fileset function
Reference: https://github.com/hashicorp/terraform/issues/16697

Enumerates a set of regular file names from a given glob pattern. Implemented via the Go stdlib `path/filepath.Glob()` functionality. Notably, stdlib does not support `**` or `{}` extended patterns. See also: https://github.com/golang/go/issues/11862

To support the extended glob patterns, it will require adding a dependency on a third party library or adding our own matching code.
2019-08-20 04:50:01 -04:00
Martin Atkins 135afaeb9c lang: "regex" and "regexall" functions
These existing upstream cty functions allow matching strings against
regular expression patterns, which can be useful if you need to consume
a non-standard string format that Terraform doesn't (and can't) have a
built-in function for.
2019-08-06 11:52:14 -07:00
Martin Atkins 5cb80c43c1 website: example of csvdecode with for_each
We added the csvdecode function originally with the intent of it being
used with for_each, but because csvdecode was released first we had a
section in its documentation warning about the downsides of using it with
"count", since that seemed like something people would be likely to try.

With resource "for_each" now merged, we can replace that scary section
with a more positive example of using these two features together.

We still include a paragraph noting that "count" _could_ be used here, but
with a caution against doing so. This is in the hope of helping users
understand the difference between these two patterns and why for_each is
the superior choice for most situations.
2019-07-31 12:43:16 -07:00
Chris Arcand 275ecf96f2
Merge pull request #22042 from hashicorp/012-replace-regex-docs
Added regex details to replace() docs
2019-07-12 12:46:31 -05:00
Pam Selle 5cd551f716
Merge pull request #21887 from jmcgeheeiv/patch-1
Add "leading zeros" for the sake of SEO
2019-07-12 13:42:55 -04:00
Chris Arcand 22385c3198 Added regex details to replace() docs 2019-07-12 11:42:20 -05:00
Andreas Sommer 042aead714 lang/funcs: add "abspath" function (#21409) 2019-07-02 08:30:30 -04:00
John McGehee 4bb6f0dff2
Add "leading zeros" for the sake of SEO
The search "terraform leading zero" does not find the `format()`
function, which is perfectly capable of adding leading zeros.
Thus I have added this one word to help people find `format()`.
2019-06-25 16:13:05 -07:00
Lars Eric Scheidler aa07806bfc lang/funcs: New "uuidv5" function
This generates name-based uuids, rather than pseudorandom uuids as with the
"uuid" function.
2019-06-07 14:38:22 -07:00
Martin Atkins 382e1ca821 lang: yamldecode and yamlencode functions
These follow the same principle as jsondecode and jsonencode, but use
YAML instead of JSON.

YAML has a much more complex information model than JSON, so we can only
support a subset of it during decoding, but hopefully the subset supported
here is a useful one.

Because there are many different ways to _generate_ YAML, the yamlencode
function is forced to make some decisions, and those decisions are likely
to affect compatibility with other real-world YAML parsers. Although the
format here is intended to be generic and compatible, we may find that
there are problems with it that'll we'll want to adjust for in a future
release, so yamlencode is therefore marked as experimental for now until
the underlying library is ready to commit to ongoing byte-for-byte
compatibility in serialization.

The main use-case here is met by yamldecode, which will allow reading in
files written in YAML format by humans for use in Terraform modules, in
situations where a higher-level input format than direct Terraform
language declarations is helpful.
2019-06-04 16:24:09 -07:00