github.com/hashicorp/packer@v1.14.3/website/content/docs/templates/hcl_templates/syntax.mdx (about)

     1  ---
     2  page_title: HCL syntax reference
     3  description: |-
     4    HCL syntax combines declarative structure with expressions into Packer templates. Learn how to use HCL syntax to define infrastructure as code. 
     5  ---
     6  
     7  # HCL syntax reference
     8  
     9  This topic provides reference information about the native HashiCorp configuration language (HCL) syntax you can use to create Packer templates. For information about HCL constructs in JSON, refer to the [JSON syntax reference](/packer/docs/templates/hcl_templates/syntax-json).
    10  
    11  ## Introduction
    12  
    13  Learning the HCL syntax helps you understand the building blocks that Packer template constructs
    14  are built from. HCL is a rich language designed to be easy for humans to read and write. 
    15  Otherwhich is also used by configuration languages in other applications, and in
    16  particular other HashiCorp products. It is not necessary to know all of the
    17  details of HCL in order to use Packer, and so this page summarizes the most
    18  important details. If you are interested, you can find a full definition of HCL
    19  syntax in [the HCL native syntax
    20  specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
    21  
    22  ## Arguments and Blocks
    23  
    24  HCL syntax is built around two key syntax constructs:
    25  arguments and blocks.
    26  
    27  ### Arguments
    28  
    29  An _argument_ assigns a value to a particular name:
    30  
    31  ```hcl
    32  image_id = "abc123"
    33  ```
    34  
    35  The identifier before the equals sign is the _argument name_, and the expression
    36  after the equals sign is the argument's value.
    37  
    38  The context where the argument appears determines what value types are valid
    39  (for example, each source type has a schema that defines the types of its
    40  arguments), but many arguments accept arbitrary
    41  [expressions](/packer/docs/templates/hcl_templates/expressions), which allow the value to
    42  either be specified literally or generated from other values programmatically.
    43  
    44  ### Blocks
    45  
    46  A _block_ is a container for other content:
    47  
    48  ```hcl
    49  source "amazon-ebs" "example" {
    50    ami_name = "abc123"
    51  
    52    tags = {
    53      # ...
    54    }
    55  }
    56  ```
    57  
    58  A block has a _type_ (`source` in this example). Each block type defines
    59  how many _labels_ must follow the type keyword. The `source` block type
    60  expects two labels, which are `amazon-ebs` and `example` in the example above.
    61  A particular block type may have any number of required labels, or it may
    62  require none as with the nested `tags` block type.
    63  
    64  After the block type keyword and any labels, the block _body_ is delimited
    65  by the `{` and `}` characters. Within the block body, further arguments
    66  and blocks may be nested, creating a hierarchy of blocks and their associated
    67  arguments.
    68  
    69  HCL uses a limited number of _top-level block types,_ which
    70  are blocks that can appear outside of any other block in a configuration file.
    71  Most of Packer's features (including resources, input variables, output
    72  values, data sources, etc.) are implemented as top-level blocks.
    73  
    74  ## Identifiers
    75  
    76  Argument names, block type names, and the names of most Packer-specific
    77  constructs like resources, input variables, etc. are all _identifiers_.
    78  
    79  Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
    80  The first character of an identifier must not be a digit, to avoid ambiguity
    81  with literal numbers.
    82  
    83  For complete identifier rules, Packer implements
    84  [the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
    85  include the ASCII hyphen character `-`.
    86  
    87  ## Comments
    88  
    89  HCL supports three different syntaxes for comments:
    90  
    91  - `#` begins a single-line comment, ending at the end of the line.
    92  - `//` also begins a single-line comment, as an alternative to `#`.
    93  - `/*` and `*/` are start and end delimiters for a comment that might span
    94    over multiple lines.
    95  
    96  The `#` single-line comment style is the default comment style and should be
    97  used in most cases. Automatic configuration formatting tools may automatically
    98  transform `//` comments into `#` comments, since the double-slash style is
    99  not idiomatic.
   100  
   101  ## Character Encoding and Line Endings
   102  
   103  Packer configuration files must always be UTF-8 encoded. While the
   104  delimiters of the language are all ASCII characters, Packer accepts
   105  non-ASCII characters in identifiers, comments, and string values.
   106  
   107  Packer accepts configuration files with either Unix-style line endings
   108  (LF only) or Windows-style line endings (CR then LF), but the idiomatic style
   109  is to use the Unix convention, and so automatic configuration formatting tools
   110  may automatically transform CRLF endings to LF.