From a3ec0f1156c66a7f925087f8be249d00cefed94a Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Mon, 11 Sep 2017 16:49:35 -0700 Subject: [PATCH] specs: zcl -> HCL --- hcl/hclsyntax/spec.md | 32 ++++++++++++++++---------------- hcl/json/spec.md | 42 +++++++++++++++++++++--------------------- hcl/spec.md | 22 +++++++++++----------- 3 files changed, 48 insertions(+), 48 deletions(-) diff --git a/hcl/hclsyntax/spec.md b/hcl/hclsyntax/spec.md index 67e955e..faf2791 100644 --- a/hcl/hclsyntax/spec.md +++ b/hcl/hclsyntax/spec.md @@ -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 -for hcl. zcl is a system for defining configuration languages for applications. -The zcl information model is designed to support multiple concrete syntaxes +for HCL. HCL is a system for defining configuration languages for applications. +The HCL information model is designed to support multiple concrete syntaxes for configuration, but this native syntax is considered the primary format and is optimized for human authoring and maintenence, as opposed to machine generation of configuration. @@ -10,7 +10,7 @@ generation of configuration. The language consists of three integrated sub-languages: * 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 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 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 -integration into more limited zcl syntaxes such as the JSON profile. +integration into more limited HCL syntaxes such as the JSON profile. ## 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. 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: @@ -155,7 +155,7 @@ constructs: * _Body Content_, which consists of a collection of attributes and blocks. These constructs correspond to the similarly-named concepts in the -language-agnostic zcl information model. +language-agnostic HCL information model. ```ebnf ConfigFile = Body; @@ -205,7 +205,7 @@ Expression = ( ### Types 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. A calling application may make other types available via _variables_ and _functions_. @@ -276,7 +276,7 @@ objectelem = (Identifier | Expression) "=" Expression; 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 -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. 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 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 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 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 -conversion is attempted using the conversion rules from the zcl +conversion is attempted using the conversion rules from the HCL syntax-agnostic information model. 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 -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)` 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 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 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. An important use-case for standalone templates is to enable the use of -expressions in alternative zcl syntaxes where a native expression grammar is -not available. For example, the zcl JSON profile treats the values of JSON +expressions in alternative HCL syntaxes where a native expression grammar is +not available. For example, the HCL JSON profile treats the values of JSON strings as standalone templates when attributes are evaluated in expression mode. @@ -857,7 +857,7 @@ with no surrounding literals, directives or other interpolations, is returned verbatim, without conversion to string. 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 used to populate attributes when strings in such languages are interpreted as templates. diff --git a/hcl/json/spec.md b/hcl/json/spec.md index fb0b125..d6e8bf6 100644 --- a/hcl/json/spec.md +++ b/hcl/json/spec.md @@ -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 -for defining configuration languages for applications. The zcl information +This is the specification for the JSON serialization for hcl. HCL is a system +for defining configuration languages for applications. The HCL information model is designed to support multiple concrete syntaxes for configuration, and this JSON-based format complements [the native syntax](../zclsyntax/spec.md) 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 [RFC7159](https://tools.ietf.org/html/rfc7159). As such it inherits the JSON 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. _Parsing_ such JSON has some additional constraints not beyond what is normally supported by JSON parsers, though adaptations are defined to allow processing @@ -21,7 +21,7 @@ sections. ## 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 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 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 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.) ### Attributes @@ -164,16 +164,16 @@ at any other point in the block definition structure. ## 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 strings that allows optional use of arbitrary expressions. ### 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. -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, creating for each an attribute whose name exactly matches the property name, and whose type is the result of recursively applying the expression mapping @@ -188,10 +188,10 @@ JSON object interpreted as an expression. ### 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. -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 for each an element whose type is the result of recursively applying the expression mapping rules. Correspondance is preserved between the array element @@ -203,16 +203,16 @@ section. ### 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 corresponding precision. 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 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. Calling applications each have differing precision requirements, so calling 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 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 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 @@ -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. 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. Template interpolations and directives MUST NOT be processed in this mode, 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- 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 variable scope and function table. @@ -255,7 +255,7 @@ variable scope and function table. ``` 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 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: diff --git a/hcl/spec.md b/hcl/spec.md index 91bc615..db4e9ef 100644 --- a/hcl/spec.md +++ b/hcl/spec.md @@ -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 -semantics) for hcl. zcl is a system for defining configuration languages for -applications. The zcl information model is designed to support multiple +semantics) for hcl. HCL is a system for defining configuration languages for +applications. The HCL information model is designed to support multiple concrete syntaxes for configuration, each with a mapping to the model defined in this specification. 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 is sufficiently rich to express the concepts described in this specification or the language targets a well-defined subset of the specification. @@ -36,8 +36,8 @@ of a particular object. ## Body Content -To support the expression of the zcl concepts in languages whose information -model is a subset of zcl's, such as JSON, a _body_ is an opaque container +To support the expression of the HCL concepts in languages whose information +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 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 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, implementation-language-agnostic type system is defined to allow for consistent processing of configuration across many implementation languages. 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 specification. @@ -257,7 +257,7 @@ value. Some syntaxes may be unable to represent numeric literals of arbitrary 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 @@ -355,14 +355,14 @@ The dynamic pseudo-type is identical only to itself. ### Capsule Types 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. 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 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 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