diff --git a/lang/functions.go b/lang/functions.go index 3ca7943a7..b116708dd 100644 --- a/lang/functions.go +++ b/lang/functions.go @@ -58,6 +58,7 @@ func (s *Scope) Functions() map[string]function.Function { "flatten": funcs.FlattenFunc, "floor": funcs.FloorFunc, "format": stdlib.FormatFunc, + "formatdate": stdlib.FormatDateFunc, "formatlist": stdlib.FormatListFunc, "indent": funcs.IndentFunc, "index": funcs.IndexFunc, diff --git a/website/docs/configuration/functions/format.html.md b/website/docs/configuration/functions/format.html.md index 8a62d009e..611b94d19 100644 --- a/website/docs/configuration/functions/format.html.md +++ b/website/docs/configuration/functions/format.html.md @@ -115,5 +115,7 @@ for an unsupported format verb. ## Related Functions +* [`formatdate`](./formatdate.html) is a specialized formatting function for + human-readable timestamps. * [`formatlist`](./formatlist.html) uses the same specification syntax to produce a list of strings. diff --git a/website/docs/configuration/functions/formatdate.html.md b/website/docs/configuration/functions/formatdate.html.md new file mode 100644 index 000000000..9add98fe3 --- /dev/null +++ b/website/docs/configuration/functions/formatdate.html.md @@ -0,0 +1,108 @@ +--- +layout: "functions" +page_title: "formatdate - Functions - Configuration Language" +sidebar_current: "docs-funcs-string-formatdate-x" +description: |- + The formatdate function converts a timestamp into a different time format. +--- + +# `formatdate` Function + +`formatdate` converts a timestamp into a different time format. + +```hcl +format(spec, timestamp) +``` + +In the Terraform language, timestamps are conventionally represented as +strings using [RFC 3339](https://tools.ietf.org/html/rfc3339) +"Date and Time format" syntax. `formatdate` requires the `timestamp` argument +to be a string conforming to this syntax. + +## Examples + +``` +> formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z") +02 Jan 2018 23:12 UTC +> formatdate("EEEE, DD-MMM-YY hh:mm:ss ZZZ", "2018-01-02T23:12:01Z") +Tuesday, 02-Jan-18 23:12:01 UTC +> formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZ", "2018-01-02T23:12:01-08:00") +Tue, 02 Jan 2018 23:12:01 -0800 +> formatdate("MMM DD, YYYY", "2018-01-02T23:12:01Z") +Jan 02, 2018 +> formatdate("HH:MMaa", "2018-01-02T23:12:01Z") +11:01pm +``` + +## Specification Syntax + +The format specification is a string that includes formatting sequences from +the following table. This function is intended for producing common +_machine-oriented_ timestamp formats such as those defined in RFC822, RFC850, +and RFC1123. It is not suitable for truly human-oriented date formatting +because it is not locale-aware. In particular, it can produce month and day +names only in English. + +The specification may contain the following sequences: + +| Sequence | Result | +| --------- | ------------------------------------------------------------------------ | +| `YYYY` | Four (or more) digit year, like "2006". | +| `YY` | The year modulo 100, zero padded to at least two digits, like "06". | +| `MMMM` | English month name unabbreviated, like "January". | +| `MMM` | English month name abbreviated to three letters, like "Jan". | +| `MM` | Month number zero-padded to two digits, like "01" for January. | +| `M` | Month number with no padding, like "1" for January. | +| `DD` | Day of month number zero-padded to two digits, like "02". | +| `D` | Day of month number with no padding, like "2". | +| `EEEE` | English day of week name unabbreviated, like "Monday". | +| `EEE` | English day of week name abbreviated to three letters, like "Mon". | +| `hh` | 24-hour number zero-padded to two digits, like "02". | +| `h` | 24-hour number unpadded, like "2". | +| `HH` | 12-hour number zero-padded to two digits, like "02". | +| `H` | 12-hour number unpadded, like "2". | +| `AA` | Hour AM/PM marker in uppercase, like "AM". | +| `aa` | Hour AM/PM marker in lowercase, like "am". | +| `mm` | Minute within hour zero-padded to two digits, like "05". | +| `m` | Minute within hour unpadded, like "5". | +| `ss` | Second within minute zero-padded to two digits, like "09". | +| `s` | Second within minute, like "9". | +| `ZZZZZ` | Timezone offset with colon separating hours and minutes, like "-08:00". | +| `ZZZZ` | Timezone offset with just sign and digit, like "-0800". | +| `ZZZ` | Like `ZZZZ` but with a special case "UTC" for UTC. | +| `Z` | Like `ZZZZZ` but with a special case "Z" for UTC. | + +Any non-letter characters, such as punctuation, are reproduced verbatim in the +output. To include literal letters in the format string, enclose them in single +quotes `'`. To include a literal quote, escape it by doubling the quotes. + +``` +> formatdate("h'h'mm", "2018-01-02T23:12:01-08:00") +23h12 +> formatdate("H 'o''clock'", "2018-01-02T23:12:01-08:00") +11 o'clock +``` + +This format specification syntax is intended to make it easy for a reader +to guess which format will result even if they are not experts on the syntax. +Therefore there are no predefined shorthands for common formats, but format +strings for various RFC-specified formats are given below to be copied into your +configuration as needed: + +- [RFC 822](https://tools.ietf.org/html/rfc822#section-5) and + [RFC RFC 2822](https://tools.ietf.org/html/rfc2822#section-3.3): + `"DD MMM YYYY hh:mm ZZZ"` +- [RFC 850](https://tools.ietf.org/html/rfc850#section-2.1.4): + `"EEEE, DD-MMM-YY hh:mm:ss ZZZ"` +- [RFC 1123](https://tools.ietf.org/html/rfc1123#section-5.2.14): + `"EEE, DD MMM YYYY hh:mm:ss ZZZ"` +- [RFC 3339](https://tools.ietf.org/html/rfc3339): + `"YYYY-MM-DD'T'hh:mm:ssZ"` (but this is also the input format, so such a + conversion is redundant.) + +## Related Functions + +* [`format`](./format.html) is a more general formatting function for arbitrary + data. +* [`timestamp`](./timestamp.html) returns the current date and time in a format + suitable for input to `formatdate`. diff --git a/website/docs/configuration/functions/timestamp.html.md b/website/docs/configuration/functions/timestamp.html.md index c07c19070..da99f2511 100644 --- a/website/docs/configuration/functions/timestamp.html.md +++ b/website/docs/configuration/functions/timestamp.html.md @@ -33,3 +33,8 @@ taken only once the plan is being applied. > timestamp() 2018-05-13T07:44:12Z ``` + +## Related Functions + +* [`formatdate`](./formatdate.html) can convert the resulting timestamp to + other date and time formats.