vendor/github.com/hashicorp/hcl2/gohcl/doc.go

   1 // Package gohcl allows decoding HCL configurations into Go data structures.
   2 //
   3 // It provides a convenient and concise way of describing the schema for
   4 // configuration and then accessing the resulting data via native Go
   5 // types.
   6 //
   7 // A struct field tag scheme is used, similar to other decoding and
   8 // unmarshalling libraries. The tags are formatted as in the following example:
   9 //
  10 //    ThingType string `hcl:"thing_type,attr"`
  11 //
  12 // Within each tag there are two comma-separated tokens. The first is the
  13 // name of the corresponding construct in configuration, while the second
  14 // is a keyword giving the kind of construct expected. The following
  15 // kind keywords are supported:
  16 //
  17 //    attr (the default) indicates that the value is to be populated from an attribute
  18 //    block indicates that the value is to populated from a block
  19 //    label indicates that the value is to populated from a block label
  20 //    remain indicates that the value is to be populated from the remaining body after populating other fields
  21 //
  22 // "attr" fields may either be of type *hcl.Expression, in which case the raw
  23 // expression is assigned, or of any type accepted by gocty, in which case
  24 // gocty will be used to assign the value to a native Go type.
  25 //
  26 // "block" fields may be of type *hcl.Block or hcl.Body, in which case the
  27 // corresponding raw value is assigned, or may be a struct that recursively
  28 // uses the same tags. Block fields may also be slices of any of these types,
  29 // in which case multiple blocks of the corresponding type are decoded into
  30 // the slice.
  31 //
  32 // "label" fields are considered only in a struct used as the type of a field
  33 // marked as "block", and are used sequentially to capture the labels of
  34 // the blocks being decoded. In this case, the name token is used only as
  35 // an identifier for the label in diagnostic messages.
  36 //
  37 // "remain" can be placed on a single field that may be either of type
  38 // hcl.Body or hcl.Attributes, in which case any remaining body content is
  39 // placed into this field for delayed processing. If no "remain" field is
  40 // present then any attributes or blocks not matched by another valid tag
  41 // will cause an error diagnostic.
  42 //
  43 // Only a subset of this tagging/typing vocabulary is supported for the
  44 // "Encode" family of functions. See the EncodeIntoBody docs for full details
  45 // on the constraints there.
  46 //
  47 // Broadly-speaking this package deals with two types of error. The first is
  48 // errors in the configuration itself, which are returned as diagnostics
  49 // written with the configuration author as the target audience. The second
  50 // is bugs in the calling program, such as invalid struct tags, which are
  51 // surfaced via panics since there can be no useful runtime handling of such
  52 // errors and they should certainly not be returned to the user as diagnostics.
  53 package gohcl