Documentation
¶
Overview ¶
Package zcldec provides a higher-level API for unpacking the content of zcl bodies, implemented in terms of the low-level "Content" API exposed by the bodies themselves.
It allows decoding an entire nested configuration in a single operation by providing a description of the intended structure.
For some applications it may be more convenient to use the "gozcl" package, which has a similar purpose but decodes directly into native Go data types. zcldec instead targets the cty type system, and thus allows a cty-driven application to remain within that type system.
Index ¶
- func Decode(body zcl.Body, spec Spec, ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
- func ImpliedSchema(spec Spec) *zcl.BodySchema
- func PartialDecode(body zcl.Body, spec Spec, ctx *zcl.EvalContext) (cty.Value, zcl.Body, zcl.Diagnostics)
- func SourceRange(body zcl.Body, spec Spec) zcl.Range
- func Variables(body zcl.Body, spec Spec) []zcl.Traversal
- type AttrSpec
- type BlockLabelSpec
- type BlockListSpec
- type BlockMapSpec
- type BlockSetSpec
- type BlockSpec
- type ExprSpec
- type LiteralSpec
- type ObjectSpec
- type Spec
- type TupleSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
func Decode(body zcl.Body, spec Spec, ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
Decode interprets the given body using the given specification and returns the resulting value. If the given body is not valid per the spec, error diagnostics are returned and the returned value is likely to be incomplete.
The ctx argument may be nil, in which case any references to variables or functions will produce error diagnostics.
func ImpliedSchema ¶
func ImpliedSchema(spec Spec) *zcl.BodySchema
ImpliedSchema returns the *zcl.BodySchema implied by the given specification. This is the schema that the Decode function will use internally to access the content of a given body.
func PartialDecode ¶
func PartialDecode(body zcl.Body, spec Spec, ctx *zcl.EvalContext) (cty.Value, zcl.Body, zcl.Diagnostics)
PartialDecode is like Decode except that it permits "leftover" items in the top-level body, which are returned as a new body to allow for further processing.
Any descendent block bodies are _not_ decoded partially and thus must be fully described by the given specification.
func SourceRange ¶
SourceRange interprets the given body using the given specification and then returns the source range of the value that would be used to fulfill the spec.
This can be used if application-level validation detects value errors, to obtain a reasonable SourceRange to use for generated diagnostics. It works best when applied to specific body items (e.g. using AttrSpec, BlockSpec, ...) as opposed to entire bodies using ObjectSpec, TupleSpec. The result will be less useful the broader the specification, so e.g. a spec that returns the entirety of all of the blocks of a given type is likely to be _particularly_ arbitrary and useless.
If the given body is not valid per the given spec, the result is best-effort and may not actually be something ideal. It's expected that an application will already have used Decode or PartialDecode earlier and thus had an opportunity to detect and report spec violations.
func Variables ¶
Variables processes the given body with the given spec and returns a list of the variable traversals that would be required to decode the same pairing of body and spec.
This can be used to conditionally populate the variables in the EvalContext passed to Decode, for applications where a static scope is insufficient.
If the given body is not compliant with the given schema, the result may be incomplete, but that's assumed to be okay because the eventual call to Decode will produce error diagnostics anyway.
Types ¶
type AttrSpec ¶
An AttrSpec is a Spec that evaluates a particular attribute expression in the body and returns its resulting value converted to the requested type, or produces a diagnostic if the type is incorrect.
type BlockLabelSpec ¶
A BlockLabelSpec is a Spec that returns a cty.String representing the label of the block its given body belongs to, if indeed its given body belongs to a block. It is a programming error to use this in a non-block context, so this spec will panic in that case.
This spec only works in the nested spec within a BlockSpec, BlockListSpec, BlockSetSpec or BlockMapSpec.
The full set of label specs used against a particular block must have a consecutive set of indices starting at zero. The maximum index found defines how many labels the corresponding blocks must have in cty source.
type BlockListSpec ¶
A BlockListSpec is a Spec that produces a cty list of the results of decoding all of the nested blocks of a given type, using a nested spec.
type BlockMapSpec ¶
A BlockMapSpec is a Spec that produces a cty map of the results of decoding all of the nested blocks of a given type, using a nested spec.
One level of map structure is created for each of the given label names. There must be at least one given label name.
type BlockSetSpec ¶
A BlockSetSpec is a Spec that produces a cty set of the results of decoding all of the nested blocks of a given type, using a nested spec.
type BlockSpec ¶
A BlockSpec is a Spec that produces a cty.Value by decoding the contents of a single nested block of a given type, using a nested spec.
If the Required flag is not set, the nested block may be omitted, in which case a null value is produced. If it _is_ set, an error diagnostic is produced if there are no nested blocks of the given type.
type ExprSpec ¶
type ExprSpec struct {
Expr zcl.Expression
}
An ExprSpec is a Spec that evaluates the given expression, ignoring the given body.
type LiteralSpec ¶
A LiteralSpec is a Spec that produces the given literal value, ignoring the given body.
type ObjectSpec ¶
An ObjectSpec is a Spec that produces a cty.Value of an object type whose attributes correspond to the keys of the spec map.
type Spec ¶
type Spec interface {
// contains filtered or unexported methods
}
A Spec is a description of how to decode a zcl.Body to a cty.Value.
The various other types in this package whose names end in "Spec" are the spec implementations. The most common top-level spec is ObjectSpec, which decodes body content into a cty.Value of an object type.
Source Files