go/hcl
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

specs: zcl -> HCL

Browse Source
This commit is contained in:
Martin Atkins 2017-09-11 16:49:35 -07:00
parent 6c9e11162b
commit a3ec0f1156
3 changed files with 48 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
hcl/hclsyntax/spec.md
View File

@ -1,8 +1,8 @@
# zcl Native Syntax Specification # HCL Native Syntax Specification
This is the specification of the syntax and semantics of the native syntax This is the specification of the syntax and semantics of the native syntax
for hcl. zcl is a system for defining configuration languages for applications. for HCL. HCL is a system for defining configuration languages for applications.
The zcl information model is designed to support multiple concrete syntaxes The HCL information model is designed to support multiple concrete syntaxes
for configuration, but this native syntax is considered the primary format for configuration, but this native syntax is considered the primary format
and is optimized for human authoring and maintenence, as opposed to machine and is optimized for human authoring and maintenence, as opposed to machine
generation of configuration. generation of configuration.
@ -10,7 +10,7 @@ generation of configuration.
The language consists of three integrated sub-languages: The language consists of three integrated sub-languages:
* The _structural_ language defines the overall heirarchical configuration * The _structural_ language defines the overall heirarchical configuration
structure, and is a serialization of zcl bodies, blocks and attributes. structure, and is a serialization of HCL bodies, blocks and attributes.
* The _expression_ language is used to express attribute values, either as * The _expression_ language is used to express attribute values, either as
literals or as derivations of other values. literals or as derivations of other values.
@ -22,7 +22,7 @@ In normal use these three sub-languages are used together within configuration
files to describe an overall configuration, with the structural language files to describe an overall configuration, with the structural language
being used at the top level. The expression and template languages can also being used at the top level. The expression and template languages can also
be used in isolation, to implement features such as REPLs, debuggers, and be used in isolation, to implement features such as REPLs, debuggers, and
integration into more limited zcl syntaxes such as the JSON profile. integration into more limited HCL syntaxes such as the JSON profile.
## Syntax Notation ## Syntax Notation
@ -73,7 +73,7 @@ Whitespace is defined as a sequence of zero or more space characters
are _not_ considered whitespace but are ignored as such in certain contexts. are _not_ considered whitespace but are ignored as such in certain contexts.
Horizontal tab characters (U+0009) are not considered to be whitespace and Horizontal tab characters (U+0009) are not considered to be whitespace and
are not valid within zcl native syntax. are not valid within HCL native syntax.
Comments serve as program documentation and come in two forms: Comments serve as program documentation and come in two forms:
@ -155,7 +155,7 @@ constructs:
* _Body Content_, which consists of a collection of attributes and blocks. * _Body Content_, which consists of a collection of attributes and blocks.
These constructs correspond to the similarly-named concepts in the These constructs correspond to the similarly-named concepts in the
language-agnostic zcl information model. language-agnostic HCL information model.
```ebnf ```ebnf
ConfigFile = Body; ConfigFile = Body;
@ -205,7 +205,7 @@ Expression = (
### Types ### Types
The value types used within the expression language are those defined by the The value types used within the expression language are those defined by the
syntax-agnostic zcl information model. An expression may return any valid syntax-agnostic HCL information model. An expression may return any valid
type, but only a subset of the available types have first-class syntax. type, but only a subset of the available types have first-class syntax.
A calling application may make other types available via _variables_ and A calling application may make other types available via _variables_ and
_functions_. _functions_.
@ -276,7 +276,7 @@ objectelem = (Identifier | Expression) "=" Expression;
Only tuple and object values can be directly constructed via native syntax. Only tuple and object values can be directly constructed via native syntax.
Tuple and object values can in turn be converted to list, set and map values Tuple and object values can in turn be converted to list, set and map values
with other operations, which behaves as defined by the syntax-agnostic zcl with other operations, which behaves as defined by the syntax-agnostic HCL
information model. information model.
When specifying an object element, an identifier is interpreted as a literal When specifying an object element, an identifier is interpreted as a literal
@ -413,7 +413,7 @@ Arguments = (
``` ```
The definition of functions and the semantics of calling them are defined by The definition of functions and the semantics of calling them are defined by
the language-agnostic zcl information model. The given arguments are mapped the language-agnostic HCL information model. The given arguments are mapped
onto the function's _parameters_ and the result of a function call expression onto the function's _parameters_ and the result of a function call expression
is the return value of the named function when given those arguments. is the return value of the named function when given those arguments.
@ -523,7 +523,7 @@ key expression must be an non-negative integer number representing the
zero-based element index to access. If applied to a value of object or map zero-based element index to access. If applied to a value of object or map
type, the key expression must be a string representing the attribute name type, the key expression must be a string representing the attribute name
or element key. If the given key value is not of the appropriate type, a or element key. If the given key value is not of the appropriate type, a
conversion is attempted using the conversion rules from the zcl conversion is attempted using the conversion rules from the HCL
syntax-agnostic information model. syntax-agnostic information model.
An error is produced if the given key expression does not correspond to An error is produced if the given key expression does not correspond to
@ -647,7 +647,7 @@ a != b not equal
``` ```
Two values are equal if the are of identical types and their values are Two values are equal if the are of identical types and their values are
equal as defined in the zcl syntax-agnostic information model. The equality equal as defined in the HCL syntax-agnostic information model. The equality
operators are commutative and opposite, such that `(a == b) == !(a != b)` operators are commutative and opposite, such that `(a == b) == !(a != b)`
and `(a == b) == (b == a)` for all values `a` and `b`. and `(a == b) == (b == a)` for all values `a` and `b`.
@ -713,7 +713,7 @@ expression is the result of the conditional. If the predicate value is
The second and third expressions must be of the same type or must be able to The second and third expressions must be of the same type or must be able to
unify into a common type using the type unification rules defined in the unify into a common type using the type unification rules defined in the
zcl syntax-agnostic information model. This unified type is the result type HCL syntax-agnostic information model. This unified type is the result type
of the conditional, with both expressions converted as necessary to the of the conditional, with both expressions converted as necessary to the
unified type. unified type.
@ -748,8 +748,8 @@ single string to return. If any of the elements produce an unknown string
or a value of the dynamic pseudo-type, the result is an unknown string. or a value of the dynamic pseudo-type, the result is an unknown string.
An important use-case for standalone templates is to enable the use of An important use-case for standalone templates is to enable the use of
expressions in alternative zcl syntaxes where a native expression grammar is expressions in alternative HCL syntaxes where a native expression grammar is
not available. For example, the zcl JSON profile treats the values of JSON not available. For example, the HCL JSON profile treats the values of JSON
strings as standalone templates when attributes are evaluated in expression strings as standalone templates when attributes are evaluated in expression
mode. mode.
@ -857,7 +857,7 @@ with no surrounding literals, directives or other interpolations, is
returned verbatim, without conversion to string. returned verbatim, without conversion to string.
This special case exists primarily to enable the native template language This special case exists primarily to enable the native template language
to be used inside strings in alternative zcl syntaxes that lack a first-class to be used inside strings in alternative HCL syntaxes that lack a first-class
template or expression syntax. Unwrapping allows arbitrary expressions to be template or expression syntax. Unwrapping allows arbitrary expressions to be
used to populate attributes when strings in such languages are interpreted used to populate attributes when strings in such languages are interpreted
as templates. as templates.

42
hcl/json/spec.md
View File

@ -1,7 +1,7 @@
# zcl JSON Syntax Specification # HCL JSON Syntax Specification
This is the specification for the JSON serialization for hcl. zcl is a system This is the specification for the JSON serialization for hcl. HCL is a system
for defining configuration languages for applications. The zcl information for defining configuration languages for applications. The HCL information
model is designed to support multiple concrete syntaxes for configuration, model is designed to support multiple concrete syntaxes for configuration,
and this JSON-based format complements [the native syntax](../zclsyntax/spec.md) and this JSON-based format complements [the native syntax](../zclsyntax/spec.md)
by being easy to machine-generate, whereas the native syntax is oriented by being easy to machine-generate, whereas the native syntax is oriented
@ -10,9 +10,9 @@ towards human authoring and maintenence.
This syntax is defined in terms of JSON as defined in This syntax is defined in terms of JSON as defined in
[RFC7159](https://tools.ietf.org/html/rfc7159). As such it inherits the JSON [RFC7159](https://tools.ietf.org/html/rfc7159). As such it inherits the JSON
grammar as-is, and merely defines a specific methodology for interpreting grammar as-is, and merely defines a specific methodology for interpreting
JSON constructs into zcl structural elements and expressions. JSON constructs into HCL structural elements and expressions.
This mapping is defined such that valid JSON-serialized zcl input can be This mapping is defined such that valid JSON-serialized HCL input can be
produced using standard JSON implementations in various programming languages. produced using standard JSON implementations in various programming languages.
_Parsing_ such JSON has some additional constraints not beyond what is normally _Parsing_ such JSON has some additional constraints not beyond what is normally
supported by JSON parsers, though adaptations are defined to allow processing supported by JSON parsers, though adaptations are defined to allow processing
@ -21,7 +21,7 @@ sections.
## Structural Elements ## Structural Elements
The zcl language-agnostic information model defines a _body_ as an abstract The HCL language-agnostic information model defines a _body_ as an abstract
container for attribute definitions and child blocks. A body is represented container for attribute definitions and child blocks. A body is represented
in JSON as a JSON _object_. in JSON as a JSON _object_.
@ -31,10 +31,10 @@ JSON bodies, the schema is crucial to allow differentiation of attribute
definitions and block definitions, both of which are represented via object definitions and block definitions, both of which are represented via object
properties. properties.
The special property name `"//"`, when used in an object representing a zcl The special property name `"//"`, when used in an object representing a HCL
body, is parsed and ignored. A property with this name can be used to body, is parsed and ignored. A property with this name can be used to
include human-readable comments. (This special property name is _not_ include human-readable comments. (This special property name is _not_
processed in this way for any _other_ zcl constructs that are represented as processed in this way for any _other_ HCL constructs that are represented as
JSON objects.) JSON objects.)
### Attributes ### Attributes
@ -164,16 +164,16 @@ at any other point in the block definition structure.
## Expressions ## Expressions
JSON lacks a native expression syntax, so the zcl JSON syntax instead defines JSON lacks a native expression syntax, so the HCL JSON syntax instead defines
a mapping for each of the JSON value types, including a special mapping for a mapping for each of the JSON value types, including a special mapping for
strings that allows optional use of arbitrary expressions. strings that allows optional use of arbitrary expressions.
### Objects ### Objects
When interpreted as an expression, a JSON object represents a value of a zcl When interpreted as an expression, a JSON object represents a value of a HCL
object type. object type.
Each property of the JSON object represents an attribute of the zcl object type. Each property of the JSON object represents an attribute of the HCL object type.
The object type is constructed by enumerating the JSON object properties, The object type is constructed by enumerating the JSON object properties,
creating for each an attribute whose name exactly matches the property name, creating for each an attribute whose name exactly matches the property name,
and whose type is the result of recursively applying the expression mapping and whose type is the result of recursively applying the expression mapping
@ -188,10 +188,10 @@ JSON object interpreted as an expression.
### Arrays ### Arrays
When interpreted as an expression, a JSON array represents a value of a zcl When interpreted as an expression, a JSON array represents a value of a HCL
tuple type. tuple type.
Each element of the JSON array represents an element of the zcl tuple type. Each element of the JSON array represents an element of the HCL tuple type.
The tuple type is constructed by enumerationg the JSON array elements, creating The tuple type is constructed by enumerationg the JSON array elements, creating
for each an element whose type is the result of recursively applying the for each an element whose type is the result of recursively applying the
expression mapping rules. Correspondance is preserved between the array element expression mapping rules. Correspondance is preserved between the array element
@ -203,16 +203,16 @@ section.
### Numbers ### Numbers
When interpreted as an expression, a JSON number represents a zcl number value. When interpreted as an expression, a JSON number represents a HCL number value.
zcl numbers are arbitrary-precision decimal values, so an ideal implementation HCL numbers are arbitrary-precision decimal values, so an ideal implementation
of this specification will translate exactly the value given to a number of of this specification will translate exactly the value given to a number of
corresponding precision. corresponding precision.
In practice, off-the-shelf JSON parsers often do not support customizing the In practice, off-the-shelf JSON parsers often do not support customizing the
processing of numbers, and instead force processing as 32-bit or 64-bit processing of numbers, and instead force processing as 32-bit or 64-bit
floating point values with a potential loss of precision. It is permissable floating point values with a potential loss of precision. It is permissable
for a zcl JSON parser to pass on such limitations _if and only if_ the for a HCL JSON parser to pass on such limitations _if and only if_ the
available precision and other constraints are defined in its documentation. available precision and other constraints are defined in its documentation.
Calling applications each have differing precision requirements, so calling Calling applications each have differing precision requirements, so calling
applications are free to select an implementation with more limited precision applications are free to select an implementation with more limited precision
@ -221,12 +221,12 @@ capabilities should high precision not be required for that application.
### Boolean Values ### Boolean Values
The JSON boolean values `true` and `false`, when interpreted as expressions, The JSON boolean values `true` and `false`, when interpreted as expressions,
represent the corresponding zcl boolean values. represent the corresponding HCL boolean values.
### The Null Value ### The Null Value
The JSON value `null`, when interpreted as an expression, represents a The JSON value `null`, when interpreted as an expression, represents a
zcl null value of the dynamic pseudo-type. HCL null value of the dynamic pseudo-type.
### Strings ### Strings
@ -234,7 +234,7 @@ When intepreted as an expression, a JSON string may be interpreted in one of
two ways depending on the evaluation mode. two ways depending on the evaluation mode.
If evaluating in literal-only mode (as defined by the syntax-agnostic If evaluating in literal-only mode (as defined by the syntax-agnostic
information model) the literal string is intepreted directly as a zcl string information model) the literal string is intepreted directly as a HCL string
value, by directly using the exact sequence of unicode characters represented. value, by directly using the exact sequence of unicode characters represented.
Template interpolations and directives MUST NOT be processed in this mode, Template interpolations and directives MUST NOT be processed in this mode,
allowing any characters that appear as introduction sequences to pass through allowing any characters that appear as introduction sequences to pass through
@ -246,7 +246,7 @@ literally:
When evaluating in full expression mode (again, as defined by the syntax- When evaluating in full expression mode (again, as defined by the syntax-
agnostic information model) the literal string is instead interpreted as a agnostic information model) the literal string is instead interpreted as a
_standalone template_ in the zcl Native Syntax. The expression evaluation _standalone template_ in the HCL Native Syntax. The expression evaluation
result is then the direct result of evaluating that template with the current result is then the direct result of evaluating that template with the current
variable scope and function table. variable scope and function table.
@ -255,7 +255,7 @@ variable scope and function table.
``` ```
In particular the _Template Interpolation Unwrapping_ requirement from the In particular the _Template Interpolation Unwrapping_ requirement from the
zcl native syntax specification must be implemented, allowing the use of HCL native syntax specification must be implemented, allowing the use of
single-interpolation templates to represent expressions that would not single-interpolation templates to represent expressions that would not
otherwise be representable in JSON, such as the following example where otherwise be representable in JSON, such as the following example where
the result must be a number, rather than a string representation of a number: the result must be a number, rather than a string representation of a number:

22
hcl/spec.md
View File

@ -1,13 +1,13 @@
# zcl Syntax-Agnostic Information Model # HCL Syntax-Agnostic Information Model
This is the specification for the general information model (abstract types and This is the specification for the general information model (abstract types and
semantics) for hcl. zcl is a system for defining configuration languages for semantics) for hcl. HCL is a system for defining configuration languages for
applications. The zcl information model is designed to support multiple applications. The HCL information model is designed to support multiple
concrete syntaxes for configuration, each with a mapping to the model defined concrete syntaxes for configuration, each with a mapping to the model defined
in this specification. in this specification.
The two primary syntaxes intended for use in conjunction with this model are The two primary syntaxes intended for use in conjunction with this model are
[the zcl native syntax](./zclsyntax/spec.md) and [the JSON syntax](./json/spec.md). [the HCL native syntax](./zclsyntax/spec.md) and [the JSON syntax](./json/spec.md).
In principle other syntaxes are possible as long as either their language model In principle other syntaxes are possible as long as either their language model
is sufficiently rich to express the concepts described in this specification is sufficiently rich to express the concepts described in this specification
or the language targets a well-defined subset of the specification. or the language targets a well-defined subset of the specification.
@ -36,8 +36,8 @@ of a particular object.
## Body Content ## Body Content
To support the expression of the zcl concepts in languages whose information To support the expression of the HCL concepts in languages whose information
model is a subset of zcl's, such as JSON, a _body_ is an opaque container model is a subset of HCL's, such as JSON, a _body_ is an opaque container
whose content can only be accessed by providing information on the expected whose content can only be accessed by providing information on the expected
structure of the content. structure of the content.
@ -203,12 +203,12 @@ which is dynamically determined during evaluation. The _variable scope_ in
the evaluation context is a map from variable name to value, using the same the evaluation context is a map from variable name to value, using the same
definition of value. definition of value.
The type system for zcl values is intended to be of a level abstraction The type system for HCL values is intended to be of a level abstraction
suitable for configuration of various applications. A well-defined, suitable for configuration of various applications. A well-defined,
implementation-language-agnostic type system is defined to allow for implementation-language-agnostic type system is defined to allow for
consistent processing of configuration across many implementation languages. consistent processing of configuration across many implementation languages.
Concrete implementations may provide additional functionality to lower Concrete implementations may provide additional functionality to lower
zcl values and types to corresponding native language types, which may then HCL values and types to corresponding native language types, which may then
impose additional constraints on the values outside of the scope of this impose additional constraints on the values outside of the scope of this
specification. specification.
@ -257,7 +257,7 @@ value.
Some syntaxes may be unable to represent numeric literals of arbitrary Some syntaxes may be unable to represent numeric literals of arbitrary
precision. This must be defined in the syntax specification as part of its precision. This must be defined in the syntax specification as part of its
description of mapping numeric literals to zcl values. description of mapping numeric literals to HCL values.
### Structural Types ### Structural Types
@ -355,14 +355,14 @@ The dynamic pseudo-type is identical only to itself.
### Capsule Types ### Capsule Types
A _capsule type_ is a custom type defined by the calling application. A value A _capsule type_ is a custom type defined by the calling application. A value
of a capsule type is considered opaque to zcl, but may be accepted of a capsule type is considered opaque to HCL, but may be accepted
by functions provided by the calling application. by functions provided by the calling application.
A particular capsule type is identical only to itself. The equality of two A particular capsule type is identical only to itself. The equality of two
values of the same capsule type is defined by the calling application. No values of the same capsule type is defined by the calling application. No
other operations are supported for values of capsule types. other operations are supported for values of capsule types.
Support for capsule types in a zcl implementation is optional. Capsule types Support for capsule types in a HCL implementation is optional. Capsule types
are intended to allow calling applications to pass through values that are are intended to allow calling applications to pass through values that are
not part of the standard type system. For example, an application that not part of the standard type system. For example, an application that
deals with raw binary data may define a capsule type representing a byte deals with raw binary data may define a capsule type representing a byte