github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/job-specification/hcl2/syntax.mdx (about)

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