vendor/github.com/hashicorp/hcl2/hcl/structure.go

   1 package hcl
   2
   3 import (
   4         "github.com/zclconf/go-cty/cty"
   5 )
   6
   7 // File is the top-level node that results from parsing a HCL file.
   8 type File struct {
   9         Body  Body
  10         Bytes []byte
  11
  12         // Nav is used to integrate with the "hcled" editor integration package,
  13         // and with diagnostic information formatters. It is not for direct use
  14         // by a calling application.
  15         Nav interface{}
  16 }
  17
  18 // Block represents a nested block within a Body.
  19 type Block struct {
  20         Type   string
  21         Labels []string
  22         Body   Body
  23
  24         DefRange    Range   // Range that can be considered the "definition" for seeking in an editor
  25         TypeRange   Range   // Range for the block type declaration specifically.
  26         LabelRanges []Range // Ranges for the label values specifically.
  27 }
  28
  29 // Blocks is a sequence of Block.
  30 type Blocks []*Block
  31
  32 // Attributes is a set of attributes keyed by their names.
  33 type Attributes map[string]*Attribute
  34
  35 // Body is a container for attributes and blocks. It serves as the primary
  36 // unit of heirarchical structure within configuration.
  37 //
  38 // The content of a body cannot be meaningfully intepreted without a schema,
  39 // so Body represents the raw body content and has methods that allow the
  40 // content to be extracted in terms of a given schema.
  41 type Body interface {
  42         // Content verifies that the entire body content conforms to the given
  43         // schema and then returns it, and/or returns diagnostics. The returned
  44         // body content is valid if non-nil, regardless of whether Diagnostics
  45         // are provided, but diagnostics should still be eventually shown to
  46         // the user.
  47         Content(schema *BodySchema) (*BodyContent, Diagnostics)
  48
  49         // PartialContent is like Content except that it permits the configuration
  50         // to contain additional blocks or attributes not specified in the
  51         // schema. If any are present, the returned Body is non-nil and contains
  52         // the remaining items from the body that were not selected by the schema.
  53         PartialContent(schema *BodySchema) (*BodyContent, Body, Diagnostics)
  54
  55         // JustAttributes attempts to interpret all of the contents of the body
  56         // as attributes, allowing for the contents to be accessed without a priori
  57         // knowledge of the structure.
  58         //
  59         // The behavior of this method depends on the body's source language.
  60         // Some languages, like JSON, can't distinguish between attributes and
  61         // blocks without schema hints, but for languages that _can_ error
  62         // diagnostics will be generated if any blocks are present in the body.
  63         //
  64         // Diagnostics may be produced for other reasons too, such as duplicate
  65         // declarations of the same attribute.
  66         JustAttributes() (Attributes, Diagnostics)
  67
  68         // MissingItemRange returns a range that represents where a missing item
  69         // might hypothetically be inserted. This is used when producing
  70         // diagnostics about missing required attributes or blocks. Not all bodies
  71         // will have an obvious single insertion point, so the result here may
  72         // be rather arbitrary.
  73         MissingItemRange() Range
  74 }
  75
  76 // BodyContent is the result of applying a BodySchema to a Body.
  77 type BodyContent struct {
  78         Attributes Attributes
  79         Blocks     Blocks
  80
  81         MissingItemRange Range
  82 }
  83
  84 // Attribute represents an attribute from within a body.
  85 type Attribute struct {
  86         Name string
  87         Expr Expression
  88
  89         Range     Range
  90         NameRange Range
  91 }
  92
  93 // Expression is a literal value or an expression provided in the
  94 // configuration, which can be evaluated within a scope to produce a value.
  95 type Expression interface {
  96         // Value returns the value resulting from evaluating the expression
  97         // in the given evaluation context.
  98         //
  99         // The context may be nil, in which case the expression may contain
 100         // only constants and diagnostics will be produced for any non-constant
 101         // sub-expressions. (The exact definition of this depends on the source
 102         // language.)
 103         //
 104         // The context may instead be set but have either its Variables or
 105         // Functions maps set to nil, in which case only use of these features
 106         // will return diagnostics.
 107         //
 108         // Different diagnostics are provided depending on whether the given
 109         // context maps are nil or empty. In the former case, the message
 110         // tells the user that variables/functions are not permitted at all,
 111         // while in the latter case usage will produce a "not found" error for
 112         // the specific symbol in question.
 113         Value(ctx *EvalContext) (cty.Value, Diagnostics)
 114
 115         // Variables returns a list of variables referenced in the receiving
 116         // expression. These are expressed as absolute Traversals, so may include
 117         // additional information about how the variable is used, such as
 118         // attribute lookups, which the calling application can potentially use
 119         // to only selectively populate the scope.
 120         Variables() []Traversal
 121
 122         Range() Range
 123         StartRange() Range
 124 }
 125
 126 // OfType filters the receiving block sequence by block type name,
 127 // returning a new block sequence including only the blocks of the
 128 // requested type.
 129 func (els Blocks) OfType(typeName string) Blocks {
 130         ret := make(Blocks, 0)
 131         for _, el := range els {
 132                 if el.Type == typeName {
 133                         ret = append(ret, el)
 134                 }
 135         }
 136         return ret
 137 }
 138
 139 // ByType transforms the receiving block sequence into a map from type
 140 // name to block sequences of only that type.
 141 func (els Blocks) ByType() map[string]Blocks {
 142         ret := make(map[string]Blocks)
 143         for _, el := range els {
 144                 ty := el.Type
 145                 if ret[ty] == nil {
 146                         ret[ty] = make(Blocks, 0, 1)
 147                 }
 148                 ret[ty] = append(ret[ty], el)
 149         }
 150         return ret
 151 }