gozcl

Documentation

Overview

Package gozcl allows decoding zcl configurations into Go data structures.

It provides a convenient and concise way of describing the schema for configuration and then accessing the resulting data via native Go types.

A struct field tag scheme is used, similar to other decoding and unmarshalling libraries. The tags are formatted as in the following example:

ThingType string `zcl:"thing_type,attr"`

Within each tag there are two comma-separated tokens. The first is the name of the corresponding construct in configuration, while the second is a keyword giving the kind of construct expected. The following kind keywords are supported:

attr (the default) indicates that the value is to be populated from an attribute
block indicates that the value is to populated from a block
label indicates that the value is to populated from a block label
remain indicates that the value is to be populated from the remaining body after populating other fields

"attr" fields may either be of type *zcl.Expression, in which case the raw expression is assigned, or of any type accepted by gocty, in which case gocty will be used to assign the value to a native Go type.

"block" fields may be of type *zcl.Block or zcl.Body, in which case the corresponding raw value is assigned, or may be a struct that recursively uses the same tags. Block fields may also be slices of any of these types, in which case multiple blocks of the corresponding type are decoded into the slice.

"label" fields are considered only in a struct used as the type of a field marked as "block", and are used sequentially to capture the labels of the blocks being decoded. In this case, the name token is used only as an identifier for the label in diagnostic messages.

"remain" can be placed on a single field that may be either of type zcl.Body or zcl.Attributes, in which case any remaining body content is placed into this field for delayed processing. If no "remain" field is present then any attributes or blocks not matched by another valid tag will cause an error diagnostic.

Broadly-speaking this package deals with two types of error. The first is errors in the configuration itself, which are returned as diagnostics written with the configuration author as the target audience. The second is bugs in the calling program, such as invalid struct tags, which are surfaced via panics since there can be no useful runtime handling of such errors and they should certainly not be returned to the user as diagnostics.

Index

• func DecodeBody(body zcl.Body, ctx *zcl.EvalContext, val interface{}) zcl.Diagnostics
• func DecodeExpression(expr zcl.Expression, ctx *zcl.EvalContext, val interface{}) zcl.Diagnostics
• func ImpliedBodySchema(val interface{}) (schema *zcl.BodySchema, partial bool)

Functions

func DecodeBody

func DecodeBody(body zcl.Body, ctx *zcl.EvalContext, val interface{}) zcl.Diagnostics

DecodeBody extracts the configuration within the given body into the given value. This value must be a non-nil pointer to either a struct or a map, where in the former case the configuration will be decoded using struct tags and in the latter case only attributes are allowed and their values are decoded into the map.

The given EvalContext is used to resolve any variables or functions in expressions encountered while decoding. This may be nil to require only constant values, for simple applications that do not support variables or functions.

The returned diagnostics should be inspected with its HasErrors method to determine if the populated value is valid and complete. If error diagnostics are returned then the given value may have been partially-populated but may still be accessed by a careful caller for static analysis and editor integration use-cases.

func DecodeExpression

func DecodeExpression(expr zcl.Expression, ctx *zcl.EvalContext, val interface{}) zcl.Diagnostics

DecodeExpression extracts the value of the given expression into the given value. This value must be something that gocty is able to decode into, since the final decoding is delegated to that package.

The given EvalContext is used to resolve any variables or functions in expressions encountered while decoding. This may be nil to require only constant values, for simple applications that do not support variables or functions.

The returned diagnostics should be inspected with its HasErrors method to determine if the populated value is valid and complete. If error diagnostics are returned then the given value may have been partially-populated but may still be accessed by a careful caller for static analysis and editor integration use-cases.

func ImpliedBodySchema

func ImpliedBodySchema(val interface{}) (schema *zcl.BodySchema, partial bool)

ImpliedBodySchema produces a zcl.BodySchema derived from the type of the given value, which must be a struct value or a pointer to one. If an inappropriate value is passed, this function will panic.

The second return argument indicates whether the given struct includes a "remain" field, and thus the returned schema is non-exhaustive.

This uses the tags on the fields of the struct to discover how each field's value should be expressed within configuration. If an invalid mapping is attempted, this function will panic.