mirror of
https://github.com/opentofu/opentofu.git
synced 2025-02-25 18:45:20 -06:00
Update website/docs/language/syntax (#238)
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń
GitHub
parent
9387ddb23f
commit
acef30c7b7
@ -1,35 +1,35 @@
|
||||
---
|
||||
page_title: Syntax - Configuration Language
|
||||
description: >-
|
||||
Key constructs of the native Terraform language syntax, including identifiers,
|
||||
Key constructs of the native OpenTF language syntax, including identifiers,
|
||||
arguments, blocks, and comments.
|
||||
---
|
||||
|
||||
# Configuration Syntax
|
||||
|
||||
Other pages in this section have described various configuration constructs
|
||||
that can appear in the Terraform language. This page describes the lower-level
|
||||
that can appear in the OpenTF language. This page describes the lower-level
|
||||
syntax of the language in more detail, revealing the building blocks that
|
||||
those constructs are built from.
|
||||
|
||||
This page describes the _native syntax_ of the Terraform language, which is
|
||||
This page describes the _native syntax_ of the OpenTF language, which is
|
||||
a rich language designed to be relatively easy for humans to read and write.
|
||||
The constructs in the Terraform language can also be expressed in
|
||||
[JSON syntax](/terraform/language/syntax/json), which is harder for humans
|
||||
The constructs in the OpenTF language can also be expressed in
|
||||
[JSON syntax](/opentf/language/syntax/json), which is harder for humans
|
||||
to read and edit but easier to generate and parse programmatically.
|
||||
|
||||
This low-level syntax of the Terraform language is defined in terms of a
|
||||
This low-level syntax of the OpenTF language is defined in terms of a
|
||||
syntax called _HCL_, which is also used by configuration languages in
|
||||
other applications, and in particular other HashiCorp products.
|
||||
It is not necessary to know all of the details of HCL syntax in
|
||||
order to use Terraform, and so this page summarizes the most important
|
||||
order to use OpenTF, and so this page summarizes the most important
|
||||
details. If you are interested, you can find a full definition of HCL
|
||||
syntax in
|
||||
[the HCL native syntax specification](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md).
|
||||
|
||||
## Arguments and Blocks
|
||||
|
||||
The Terraform language syntax is built around two key syntax constructs:
|
||||
The OpenTF language syntax is built around two key syntax constructs:
|
||||
arguments and blocks.
|
||||
|
||||
### Arguments
|
||||
@ -46,17 +46,17 @@ after the equals sign is the argument's value.
|
||||
The context where the argument appears determines what value types are valid
|
||||
(for example, each resource type has a schema that defines the types of its
|
||||
arguments), but many arguments accept arbitrary
|
||||
[expressions](/terraform/language/expressions), which allow the value to
|
||||
[expressions](/opentf/language/expressions), which allow the value to
|
||||
either be specified literally or generated from other values programmatically.
|
||||
|
||||
-> **Note:** Terraform's configuration language is based on a more general
|
||||
-> **Note:** OpenTF's configuration language is based on a more general
|
||||
language called HCL, and HCL's documentation usually uses the word "attribute"
|
||||
instead of "argument." These words are similar enough to be interchangeable in
|
||||
this context, and experienced Terraform users might use either term in casual
|
||||
conversation. But because Terraform also interacts with several _other_ things
|
||||
called "attributes" (in particular, Terraform resources have attributes like
|
||||
this context, and experienced OpenTF users might use either term in casual
|
||||
conversation. But because OpenTF also interacts with several _other_ things
|
||||
called "attributes" (in particular, OpenTF resources have attributes like
|
||||
`id` that can be referenced from expressions but can't be assigned values in
|
||||
configuration), we've chosen to use "argument" in the Terraform documentation
|
||||
configuration), we've chosen to use "argument" in the OpenTF documentation
|
||||
when referring to this syntax construct.
|
||||
|
||||
### Blocks
|
||||
@ -84,27 +84,27 @@ by the `{` and `}` characters. Within the block body, further arguments
|
||||
and blocks may be nested, creating a hierarchy of blocks and their associated
|
||||
arguments.
|
||||
|
||||
The Terraform language uses a limited number of _top-level block types,_ which
|
||||
The OpenTF language uses a limited number of _top-level block types,_ which
|
||||
are blocks that can appear outside of any other block in a configuration file.
|
||||
Most of Terraform's features (including resources, input variables, output
|
||||
Most of OpenTF's features (including resources, input variables, output
|
||||
values, data sources, etc.) are implemented as top-level blocks.
|
||||
|
||||
## Identifiers
|
||||
|
||||
Argument names, block type names, and the names of most Terraform-specific
|
||||
Argument names, block type names, and the names of most OpenTF-specific
|
||||
constructs like resources, input variables, etc. are all _identifiers_.
|
||||
|
||||
Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
|
||||
The first character of an identifier must not be a digit, to avoid ambiguity
|
||||
with literal numbers.
|
||||
|
||||
For complete identifier rules, Terraform implements
|
||||
For complete identifier rules, OpenTF implements
|
||||
[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
|
||||
include the ASCII hyphen character `-`.
|
||||
|
||||
## Comments
|
||||
|
||||
The Terraform language supports three different syntaxes for comments:
|
||||
The OpenTF language supports three different syntaxes for comments:
|
||||
|
||||
* `#` begins a single-line comment, ending at the end of the line.
|
||||
* `//` also begins a single-line comment, as an alternative to `#`.
|
||||
@ -118,11 +118,11 @@ not idiomatic.
|
||||
|
||||
## Character Encoding and Line Endings
|
||||
|
||||
Terraform configuration files must always be UTF-8 encoded. While the
|
||||
delimiters of the language are all ASCII characters, Terraform accepts
|
||||
OpenTF configuration files must always be UTF-8 encoded. While the
|
||||
delimiters of the language are all ASCII characters, OpenTF accepts
|
||||
non-ASCII characters in identifiers, comments, and string values.
|
||||
|
||||
Terraform accepts configuration files with either Unix-style line endings
|
||||
OpenTF accepts configuration files with either Unix-style line endings
|
||||
(LF only) or Windows-style line endings (CR then LF), but the idiomatic style
|
||||
is to use the Unix convention, and so automatic configuration formatting tools
|
||||
may automatically transform CRLF endings to LF.
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
page_title: Syntax Overview - Configuration Language
|
||||
description: >-
|
||||
Terraform language syntax for both the native and JSON variants. Also learn
|
||||
formatting conventions that you can enforce with terraform fmt.
|
||||
OpenTF language syntax for both the native and JSON variants. Also learn
|
||||
formatting conventions that you can enforce with opentf fmt.
|
||||
---
|
||||
|
||||
# Syntax
|
||||
|
||||
The majority of the Terraform language documentation focuses on the practical
|
||||
The majority of the OpenTF language documentation focuses on the practical
|
||||
uses of the language and the specific constructs it uses. The pages in this
|
||||
section offer a more abstract view of the Terraform language.
|
||||
section offer a more abstract view of the OpenTF language.
|
||||
|
||||
- [Configuration Syntax](/terraform/language/syntax/configuration) describes the native
|
||||
grammar of the Terraform language.
|
||||
- [JSON Configuration Syntax](/terraform/language/syntax/json) documents
|
||||
how to represent Terraform language constructs in the pure JSON variant of the
|
||||
Terraform language. Terraform's JSON syntax is unfriendly to humans, but can
|
||||
- [Configuration Syntax](/opentf/language/syntax/configuration) describes the native
|
||||
grammar of the OpenTF language.
|
||||
- [JSON Configuration Syntax](/opentf/language/syntax/json) documents
|
||||
how to represent OpenTF language constructs in the pure JSON variant of the
|
||||
OpenTF language. OpenTF's JSON syntax is unfriendly to humans, but can
|
||||
be very useful when generating infrastructure as code with other systems that
|
||||
don't have a readily available HCL library.
|
||||
- [Style Conventions](/terraform/language/syntax/style) documents some commonly
|
||||
accepted formatting guidelines for Terraform code. These conventions can be
|
||||
enforced automatically with [`terraform fmt`](/terraform/cli/commands/fmt).
|
||||
- [Style Conventions](/opentf/language/syntax/style) documents some commonly
|
||||
accepted formatting guidelines for OpenTF code. These conventions can be
|
||||
enforced automatically with [`opentf fmt`](/opentf/cli/commands/fmt).
|
||||
|
||||
@ -7,11 +7,11 @@ description: >-
|
||||
|
||||
# JSON Configuration Syntax
|
||||
|
||||
Most Terraform configurations are written in
|
||||
[the native Terraform language syntax](/terraform/language/syntax/configuration), which is designed to be
|
||||
Most OpenTF configurations are written in
|
||||
[the native OpenTF language syntax](/opentf/language/syntax/configuration), which is designed to be
|
||||
relatively easy for humans to read and update.
|
||||
|
||||
Terraform also supports an alternative syntax that is JSON-compatible. This
|
||||
OpenTF also supports an alternative syntax that is JSON-compatible. This
|
||||
syntax is useful when generating portions of a configuration programmatically,
|
||||
since existing JSON libraries can be used to prepare the generated
|
||||
configuration files.
|
||||
@ -21,21 +21,21 @@ be expressed in native syntax can also be expressed in JSON syntax, but some
|
||||
constructs are more complex to represent in JSON due to limitations of the
|
||||
JSON grammar.
|
||||
|
||||
Terraform expects native syntax for files named with a `.tf` suffix, and
|
||||
OpenTF expects native syntax for files named with a `.tf` suffix, and
|
||||
JSON syntax for files named with a `.tf.json` suffix.
|
||||
|
||||
The low-level JSON syntax, just as with the native syntax, is defined in terms
|
||||
of a specification called _HCL_. It is not necessary to know all of the details
|
||||
of HCL syntax or its JSON mapping in order to use Terraform, and so this page
|
||||
of HCL syntax or its JSON mapping in order to use OpenTF, and so this page
|
||||
summarizes the most important differences between native and JSON syntax.
|
||||
If you are interested, you can find a full definition of HCL's JSON syntax
|
||||
in [its specification](https://github.com/hashicorp/hcl/blob/main/json/spec.md).
|
||||
|
||||
## JSON File Structure
|
||||
|
||||
At the root of any JSON-based Terraform configuration is a JSON object. The
|
||||
At the root of any JSON-based OpenTF configuration is a JSON object. The
|
||||
properties of this object correspond to the top-level block types of the
|
||||
Terraform language. For example:
|
||||
OpenTF language. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -92,7 +92,7 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti
|
||||
correspond either to argument names or to nested block type names.
|
||||
|
||||
* Where a property corresponds to an argument that accepts
|
||||
[arbitrary expressions](/terraform/language/expressions) in the native syntax, the
|
||||
[arbitrary expressions](/opentf/language/expressions) in the native syntax, the
|
||||
property value is mapped to an expression as described under
|
||||
[_Expression Mapping_](#expression-mapping) below. For arguments that
|
||||
do _not_ accept arbitrary expressions, the interpretation of the property
|
||||
@ -108,11 +108,11 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti
|
||||
|
||||
## Expression Mapping
|
||||
|
||||
Since JSON grammar is not able to represent all of the Terraform language
|
||||
[expression syntax](/terraform/language/expressions), JSON values interpreted as expressions
|
||||
Since JSON grammar is not able to represent all of the OpenTF language
|
||||
[expression syntax](/opentf/language/expressions), JSON values interpreted as expressions
|
||||
are mapped as follows:
|
||||
|
||||
| JSON | Terraform Language Interpretation |
|
||||
| JSON | OpenTF Language Interpretation |
|
||||
| ------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Boolean | A literal `bool` value. |
|
||||
| Number | A literal `number` value. |
|
||||
@ -121,7 +121,7 @@ are mapped as follows:
|
||||
| Array | Each element is mapped per this table, producing a `tuple(...)` value with suitable element types. |
|
||||
| Null | A literal `null`. |
|
||||
|
||||
[string template]: /terraform/language/expressions/strings#string-templates
|
||||
[string template]: /opentf/language/expressions/strings#string-templates
|
||||
|
||||
When a JSON string is encountered in a location where arbitrary expressions are
|
||||
expected, its value is first parsed as a [string template][]
|
||||
@ -279,7 +279,7 @@ block bodies using a special property name:
|
||||
```
|
||||
|
||||
In any object that represents a block body, properties named `"//"` are
|
||||
ignored by Terraform entirely. This exception does _not_ apply to objects
|
||||
ignored by OpenTF entirely. This exception does _not_ apply to objects
|
||||
that are being [interpreted as expressions](#expression-mapping), where this
|
||||
would be interpreted as an object type attribute named `"//"`.
|
||||
|
||||
@ -303,7 +303,7 @@ configuration file. This can be useful to note which program created the file.
|
||||
[inpage-block]: #block-type-specific-exceptions
|
||||
|
||||
Certain arguments within specific block types are processed in a special way
|
||||
by Terraform, and so their mapping to the JSON syntax does not follow the
|
||||
by OpenTF, and so their mapping to the JSON syntax does not follow the
|
||||
general rules described above. The following sub-sections describe the special
|
||||
mapping rules that apply to each top-level block type.
|
||||
|
||||
@ -461,7 +461,7 @@ a single property whose name represents the backend type.
|
||||
"backend": {
|
||||
"s3": {
|
||||
"region": "us-west-2",
|
||||
"bucket": "acme-terraform-states"
|
||||
"bucket": "acme-opentf-states"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
page_title: Style Conventions - Configuration Language
|
||||
description: >-
|
||||
Learn recommended formatting conventions for the Terraform language and a
|
||||
Learn recommended formatting conventions for the OpenTF language and a
|
||||
command to automatically enforce them.
|
||||
---
|
||||
|
||||
# Style Conventions
|
||||
|
||||
The Terraform parser allows you some flexibility in how you lay out the
|
||||
elements in your configuration files, but the Terraform language also has some
|
||||
The OpenTF parser allows you some flexibility in how you lay out the
|
||||
elements in your configuration files, but the OpenTF language also has some
|
||||
idiomatic style conventions which we recommend users always follow
|
||||
for consistency between files and modules written by different teams.
|
||||
Automatic source code formatting tools may apply these conventions
|
||||
automatically.
|
||||
|
||||
-> **Note**: You can enforce these conventions automatically by running [`terraform fmt`](/terraform/cli/commands/fmt).
|
||||
-> **Note**: You can enforce these conventions automatically by running [`opentf fmt`](/opentf/cli/commands/fmt).
|
||||
|
||||
* Indent two spaces for each nesting level.
|
||||
|
||||
@ -34,7 +34,7 @@ automatically.
|
||||
* Use empty lines to separate logical groups of arguments within a block.
|
||||
|
||||
* For blocks that contain both arguments and "meta-arguments" (as defined by
|
||||
the Terraform language semantics), list meta-arguments first
|
||||
the OpenTF language semantics), list meta-arguments first
|
||||
and separate them from other arguments with one blank line. Place
|
||||
meta-argument blocks _last_ and separate them from other blocks with
|
||||
one blank line.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user