github.com/myhau/pulumi/pkg/v3@v3.70.2-0.20221116134521-f2775972e587/codegen/hcl2/model/spec.md (about)

     1  # HCL Syntax-Agnostic Information Model Extensions
     2  
     3  This document describes extensions to the HCL Syntax-Agnostic Information
     4  Model that are implemented by this package. The original specification can be
     5  found [here](https://github.com/hashicorp/hcl/blob/v2.3.0/spec.md).
     6  
     7  ## Extended Types
     8  
     9  ### Primitive Types
    10  
    11  The extended type system two additional primitive types, _int_.
    12  
    13  An _int_ is an arbitrary-precision integer value. An implementation _must_ make
    14  the full-precision values available to the calling application for
    15  interpretation into any suitable integer representation. An implementation may
    16  in practice implement ints with limited precision so long as the following
    17  constraints are met:
    18  
    19  - Integers are represented with at least 256 bits.
    20  - An error is produced if an integer value given in source cannot be
    21    represented precisely.
    22  
    23  Two int values are equal if they are numerically equal to the precision
    24  associated with the number.
    25  
    26  Some syntaxes may be unable to represent integer literals of arbitrary
    27  precision. This must be defined in the syntax specification as part of its
    28  description of mapping numeric literals to HCL values.
    29  
    30  ### Structural Types
    31  
    32  The extended type system adds a new structural type kind, _union_.
    33  
    34  A _union type_ is constructed of a set of types. A union type is assignable
    35  from any type that is assignable to one of its element types.
    36  
    37  A union type is traversed by traversing each of its element types. The result
    38  of the traversal is the union of the results of the traversals that succeed.
    39  When traversing a union with an element type of none, the traversal of none
    40  successfully results in none; this allows a traversal of an optional value to
    41  return an optional value of the appropriate type.
    42  
    43  ### Eventual Types
    44  
    45  The extended type system adds two _eventual type kinds_, _promise_ and
    46  _output_. These types represent values that are only available asynchronously,
    47  and can be used by applications that produce such values to more accurately
    48  track which values are available promptly and which are not.
    49  
    50  A _promise_ type represents an eventual value of a particular type with no
    51  additional associated information. A promise type is assignable from itself
    52  or from its element type. Traversing a promise type returns the traversal of
    53  its element type wrapped in a promise.
    54  
    55  An _output_ type represents an eventual value of a particular type that carries
    56  additional application-specific information. An output type is assignable from
    57  itself, its corresponding promise type, or its element type. Traversing an
    58  output type returns the traversal of its element type wrapped in an output.
    59  
    60  ### Null values
    61  
    62  The extended type system includes a first-class representation for the null
    63  value, the _none_ type. In the extended type system, the null value is only
    64  assignable to the none type. Optional values of type T are represented by
    65  the type `union(T, none)`.
    66  
    67  ## Type Conversions and Unification
    68  
    69  ### Primitive Type Conversions
    70  
    71  Bidirectional conversions are available between the string and int types and
    72  the number and int types. Conversion from int to string or number is safe,
    73  while the converse of either is unsafe.
    74  
    75  ### Collection and Structural Type Conversions
    76  
    77  Conversion from a type T to a union type is permitted if there is a conversion
    78  from T to at least one of the union's element types. If there is a safe
    79  conversion from T to at least one of the union's element types, the conversion
    80  is safe. Otherwise, the conversion is unsafe.
    81  
    82  ### Eventual Type Conversions
    83  
    84  Conversion from a type T to a promise with element type U is permitted if T is
    85  a promise with element type V where V is convertible to U or if T is
    86  convertible to U. The safety of this conversion depends on the safety of the
    87  conversion from V or T to U.
    88  
    89  Conversion from a type T to an output with element type U is permitted if T is
    90  an output or promise with element type V where V is convertible to U or if T is
    91  convertible to U. The safety of this conversion depends on the safety of the
    92  conversion from V or T to U.
    93  
    94  ### Type Unification
    95  
    96  The int type unifies with number by preferring number, and unifies with string
    97  by preferring string.
    98  
    99  Two union types unify by producing a new union type whose elements are the
   100  concatenation of those of the two input types.
   101  
   102  A union type unifies with another type by producing a new union whose element
   103  types are the unification of the other type with each of the input union's
   104  element types.
   105  
   106  A promise type unifies with an output type by producing a new output type whose
   107  element type is the unification of the output type's element type and the promise
   108  type's element types.
   109  
   110  Two promise types unify by producing a new promise type whose element type is the
   111  unification of the element types of the two promise types.
   112  
   113  Two output types unify by producing a new promise type whose element type is the
   114  unification of the element types of the two output types.