From abae2232a9ff3b0c9411e52b8b7bf8a25eeeb7dc Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Fri, 17 Feb 2023 13:43:25 +0000 Subject: [PATCH 1/4] backport of commit 9c98d662a9f5e052ceeae49f79b5494d507146cb --- website/docs/internals/metadata-functions.mdx | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 website/docs/internals/metadata-functions.mdx diff --git a/website/docs/internals/metadata-functions.mdx b/website/docs/internals/metadata-functions.mdx new file mode 100644 index 000000000000..39ee05946c3b --- /dev/null +++ b/website/docs/internals/metadata-functions.mdx @@ -0,0 +1,101 @@ +--- +page_title: 'Command: metadata functions' +description: >- + The `terraform metadata functions` command prints signatures for all the + functions available in the current Terraform version. +--- + +# Command: terraform metadata functions + +The `terraform metadata functions` command is used to print signatures for the functions available in the current Terraform version. + +-> `terraform metadata functions` requires **Terraform v1.4 or later**. + +## Usage + +Usage: `terraform metadata functions [options]` + +The following flags are available: + +- `-json` - Displays the function signatures in a machine-readable, JSON format. + +Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. + +The output includes a `format_version` key, which as of Terraform 1.4.0 has +value `"1.0"`. The semantics of this version are: + +- We will increment the minor version, e.g. `"1.1"`, for backward-compatible + changes or additions. Ignore any object properties with unrecognized names to + remain forward-compatible with future minor versions. +- We will increment the major version, e.g. `"2.0"`, for changes that are not + backward-compatible. Reject any input which reports an unsupported major + version. + +We will introduce new major versions only within the bounds of +[the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises). + +## Format Summary + +The following sections describe the JSON output format by example, using a pseudo-JSON notation. +Important elements are described with comments, which are prefixed with //. +To avoid excessive repetition, we've split the complete format into several discrete sub-objects, described under separate headers. References wrapped in angle brackets (like ``) are placeholders which, in the real output, would be replaced by an instance of the specified sub-object. + +The JSON output format consists of the following objects and sub-objects: + +- [Function Signature Representation](#function-signature-representation) - the top-level object returned by `terraform metadata functions -json` +- [Parameter Representation](#parameter-representation) - a sub-object of signatures that describes their parameters + +## Function Signature Representation + +```javascript +{ + "format_version": "1.0", + + // "function_signatures" describes the signatures for all + // available functions. + "function_signatures": { + // keys in this map are the function names, such as "abs" + "example_function": { + // "description" is an English-language description of + // the purpose and usage of the function in Markdown. + "description": "string", + + // "return_type" is a representation of a type specification + // that the function returns. + "return_type": "string", + + // "parameters" is an optional list of the positional parameters + // that the function accepts. + "parameters": [ + , + … + ], + + // "variadic_parameter" is an optional representation of the + // additional arguments that the function accepts after those + // matching with the fixed parameters. + "variadic_parameter": + }, + "example_function_two": { … } + } +} +``` + +## Parameter Representation + +A parameter representation describes a parameter to a function. + +```javascript +{ + // "name" is the internal name of the parameter + "name": "string", + + // "description" is an optional English-language description of + // the purpose and usage of the parameter in Markdown. + "description": "string", + + // "type" is a representation of a type specification + // that the parameters's value must conform to. + "type": "string" +} +``` From bf533c5c57ab3ce955243c32ed3d97cbd0811e8a Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Fri, 17 Feb 2023 14:13:38 +0000 Subject: [PATCH 2/4] backport of commit 532b75895edc7db6625cf8face75a00ff591401e --- website/data/internals-nav-data.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/data/internals-nav-data.json b/website/data/internals-nav-data.json index 5da67d0a28ce..f676abb2e1ff 100644 --- a/website/data/internals-nav-data.json +++ b/website/data/internals-nav-data.json @@ -44,6 +44,10 @@ "title": "Provider Metadata", "path": "provider-meta" }, + { + "title": "Metadata Functions", + "path": "metadata-functions" + }, { "title": "Machine Readable UI", "path": "machine-readable-ui", From 4bcfe7e8e9c54b2d8865537df408dbd2dd64ba9e Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Fri, 17 Feb 2023 15:35:23 +0000 Subject: [PATCH 3/4] backport of commit 837b88ce8980a5d7a83a5618ab9a73a2ea0c9737 --- website/data/internals-nav-data.json | 4 ++-- .../{metadata-functions.mdx => functions-meta.mdx} | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) rename website/docs/internals/{metadata-functions.mdx => functions-meta.mdx} (95%) diff --git a/website/data/internals-nav-data.json b/website/data/internals-nav-data.json index f676abb2e1ff..025ac6a4e155 100644 --- a/website/data/internals-nav-data.json +++ b/website/data/internals-nav-data.json @@ -45,8 +45,8 @@ "path": "provider-meta" }, { - "title": "Metadata Functions", - "path": "metadata-functions" + "title": "Functions Metadata", + "path": "functions-meta" }, { "title": "Machine Readable UI", diff --git a/website/docs/internals/metadata-functions.mdx b/website/docs/internals/functions-meta.mdx similarity index 95% rename from website/docs/internals/metadata-functions.mdx rename to website/docs/internals/functions-meta.mdx index 39ee05946c3b..6444f49fd62e 100644 --- a/website/docs/internals/metadata-functions.mdx +++ b/website/docs/internals/functions-meta.mdx @@ -1,5 +1,5 @@ --- -page_title: 'Command: metadata functions' +page_title: Functions Metadata description: >- The `terraform metadata functions` command prints signatures for all the functions available in the current Terraform version. @@ -37,7 +37,7 @@ We will introduce new major versions only within the bounds of ## Format Summary The following sections describe the JSON output format by example, using a pseudo-JSON notation. -Important elements are described with comments, which are prefixed with //. +Important elements are described with comments, which are prefixed with `//`. To avoid excessive repetition, we've split the complete format into several discrete sub-objects, described under separate headers. References wrapped in angle brackets (like ``) are placeholders which, in the real output, would be replaced by an instance of the specified sub-object. The JSON output format consists of the following objects and sub-objects: @@ -87,7 +87,7 @@ A parameter representation describes a parameter to a function. ```javascript { - // "name" is the internal name of the parameter + // "name" is the internal name of the parameter "name": "string", // "description" is an optional English-language description of @@ -95,7 +95,7 @@ A parameter representation describes a parameter to a function. "description": "string", // "type" is a representation of a type specification - // that the parameters's value must conform to. + // that the parameter's value must conform to. "type": "string" } ``` From 1547c529ef9373372d0a18d4430937b7ff7df329 Mon Sep 17 00:00:00 2001 From: Daniel Banck Date: Fri, 17 Feb 2023 15:40:51 +0000 Subject: [PATCH 4/4] backport of commit 5c0310c18bd408e34a93a8177e7cdb747db75bb9 --- website/docs/internals/functions-meta.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/internals/functions-meta.mdx b/website/docs/internals/functions-meta.mdx index 6444f49fd62e..1f96ebde43a5 100644 --- a/website/docs/internals/functions-meta.mdx +++ b/website/docs/internals/functions-meta.mdx @@ -5,7 +5,7 @@ description: >- functions available in the current Terraform version. --- -# Command: terraform metadata functions +# Functions Metadata The `terraform metadata functions` command is used to print signatures for the functions available in the current Terraform version.