Documentation
¶
Overview ¶
Package zclsyntax contains the parser, AST, etc for zcl's native language, as opposed to the JSON variant and the HCL/HIL shim.
In normal use applications should rarely depend on this package directly, instead preferring the higher-level interface of the main zcl page and its companion zclparse.
line 1 "scan_tokens.rl"
Index ¶
- Variables
- func ParseConfig(src []byte, filename string, start zcl.Pos) (*zcl.File, zcl.Diagnostics)
- func ParseTraversalAbs(src []byte, filename string, start zcl.Pos) (zcl.Traversal, zcl.Diagnostics)
- func Variables(expr Expression) []zcl.Traversal
- func VisitAll(node Node, f VisitFunc) zcl.Diagnostics
- func Walk(node Node, w Walker) zcl.Diagnostics
- type AnonSymbolExpr
- type Attribute
- type Attributes
- type BinaryOpExpr
- type Block
- type Blocks
- type Body
- func (b *Body) Content(schema *zcl.BodySchema) (*zcl.BodyContent, zcl.Diagnostics)
- func (b *Body) JustAttributes() (zcl.Attributes, zcl.Diagnostics)
- func (b *Body) MissingItemRange() zcl.Range
- func (b *Body) PartialContent(schema *zcl.BodySchema) (*zcl.BodyContent, zcl.Body, zcl.Diagnostics)
- func (b *Body) Range() zcl.Range
- type ChildScope
- type ConditionalExpr
- type Expression
- type File
- type ForExpr
- type FunctionCallExpr
- type IndexExpr
- type Keyword
- type LiteralValueExpr
- type Node
- type ObjectConsExpr
- type ObjectConsItem
- type Operation
- type RelativeTraversalExpr
- type ScopeTraversalExpr
- type SplatExpr
- type TemplateExpr
- type TemplateJoinExpr
- type TemplateWrapExpr
- type Token
- type TokenType
- type Tokens
- type Transformer
- type TupleConsExpr
- type UnaryOpExpr
- type VisitFunc
- type Walker
Constants ¶
This section is empty.
Variables ¶
var ( OpLogicalOr = &Operation{ Impl: stdlib.OrFunc, Type: cty.Bool, } OpLogicalAnd = &Operation{ Impl: stdlib.AndFunc, Type: cty.Bool, } OpLogicalNot = &Operation{ Impl: stdlib.NotFunc, Type: cty.Bool, } OpEqual = &Operation{ Impl: stdlib.EqualFunc, Type: cty.Bool, } OpNotEqual = &Operation{ Impl: stdlib.NotEqualFunc, Type: cty.Bool, } OpGreaterThan = &Operation{ Impl: stdlib.GreaterThanFunc, Type: cty.Bool, } OpGreaterThanOrEqual = &Operation{ Impl: stdlib.GreaterThanOrEqualToFunc, Type: cty.Bool, } OpLessThan = &Operation{ Impl: stdlib.LessThanFunc, Type: cty.Bool, } OpLessThanOrEqual = &Operation{ Impl: stdlib.LessThanOrEqualToFunc, Type: cty.Bool, } OpAdd = &Operation{ Impl: stdlib.AddFunc, Type: cty.Number, } OpSubtract = &Operation{ Impl: stdlib.SubtractFunc, Type: cty.Number, } OpMultiply = &Operation{ Impl: stdlib.MultiplyFunc, Type: cty.Number, } OpDivide = &Operation{ Impl: stdlib.DivideFunc, Type: cty.Number, } OpModulo = &Operation{ Impl: stdlib.ModuloFunc, Type: cty.Number, } OpNegate = &Operation{ Impl: stdlib.NegateFunc, Type: cty.Number, } )
Functions ¶
func ParseConfig ¶
ParseConfig parses the given buffer as a whole zcl config file, returning a *zcl.File representing its contents. If HasErrors called on the returned diagnostics returns true, the returned body is likely to be incomplete and should therefore be used with care.
The body in the returned file has dynamic type *zclsyntax.Body, so callers may freely type-assert this to get access to the full zclsyntax API in situations where detailed access is required. However, most common use-cases should be served using the zcl.Body interface to ensure compatibility with other configurationg syntaxes, such as JSON.
func ParseTraversalAbs ¶
ParseTraversalAbs parses the given buffer as a standalone absolute traversal.
Parsing as a traversal is more limited than parsing as an expession since it allows only attribute and indexing operations on variables. Traverals are useful as a syntax for referring to objects without necessarily evaluating them.
func Variables ¶
func Variables(expr Expression) []zcl.Traversal
Variables returns all of the variables referenced within a given experssion.
This is the implementation of the "Variables" method on every native expression.
func VisitAll ¶
func VisitAll(node Node, f VisitFunc) zcl.Diagnostics
VisitAll is a basic way to traverse the AST beginning with a particular node. The given function will be called once for each AST node in depth-first order, but no context is provided about the shape of the tree.
The VisitFunc may return diagnostics, in which case they will be accumulated and returned as a single set.
Types ¶
type AnonSymbolExpr ¶
AnonSymbolExpr is used as a placeholder for a value in an expression that can be applied dynamically to any value at runtime.
This is a rather odd, synthetic expression. It is used as part of the representation of splat expressions as a placeholder for the current item being visited in the splat evaluation.
AnonSymbolExpr cannot be evaluated in isolation. If its Value is called directly then cty.DynamicVal will be returned. Instead, it is evaluated in terms of another node (i.e. a splat expression) which temporarily assigns it a value.
func (*AnonSymbolExpr) Range ¶
func (e *AnonSymbolExpr) Range() zcl.Range
func (*AnonSymbolExpr) StartRange ¶
func (e *AnonSymbolExpr) StartRange() zcl.Range
func (*AnonSymbolExpr) Value ¶
func (e *AnonSymbolExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*AnonSymbolExpr) Variables ¶
func (e *AnonSymbolExpr) Variables() []zcl.Traversal
type Attribute ¶
type Attribute struct { Name string Expr Expression SrcRange zcl.Range NameRange zcl.Range EqualsRange zcl.Range }
Attribute represents a single attribute definition within a body.
func (*Attribute) AsZCLAttribute ¶
AsZCLAttribute returns the block data expressed as a *zcl.Attribute.
type Attributes ¶
Attributes is the collection of attribute definitions within a body.
func (Attributes) Range ¶
func (a Attributes) Range() zcl.Range
Range returns the range of some arbitrary point within the set of attributes, or an invalid range if there are no attributes.
This is provided only to complete the Node interface, but has no practical use.
type BinaryOpExpr ¶
type BinaryOpExpr struct { LHS Expression Op *Operation RHS Expression SrcRange zcl.Range }
func (*BinaryOpExpr) Range ¶
func (e *BinaryOpExpr) Range() zcl.Range
func (*BinaryOpExpr) StartRange ¶
func (e *BinaryOpExpr) StartRange() zcl.Range
func (*BinaryOpExpr) Value ¶
func (e *BinaryOpExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*BinaryOpExpr) Variables ¶
func (e *BinaryOpExpr) Variables() []zcl.Traversal
type Block ¶
type Block struct { Type string Labels []string Body *Body TypeRange zcl.Range LabelRanges []zcl.Range OpenBraceRange zcl.Range CloseBraceRange zcl.Range }
Block represents a nested block structure
func (*Block) AsZCLBlock ¶
AsZCLBlock returns the block data expressed as a *zcl.Block.
type Body ¶
type Body struct { Attributes Attributes Blocks Blocks SrcRange zcl.Range EndRange zcl.Range // Final token of the body, for reporting missing items // contains filtered or unexported fields }
Body is the implementation of zcl.Body for the zcl native syntax.
func (*Body) Content ¶
func (b *Body) Content(schema *zcl.BodySchema) (*zcl.BodyContent, zcl.Diagnostics)
func (*Body) JustAttributes ¶
func (b *Body) JustAttributes() (zcl.Attributes, zcl.Diagnostics)
func (*Body) MissingItemRange ¶
func (*Body) PartialContent ¶
func (b *Body) PartialContent(schema *zcl.BodySchema) (*zcl.BodyContent, zcl.Body, zcl.Diagnostics)
type ChildScope ¶
type ChildScope struct { LocalNames map[string]struct{} Expr *Expression // pointer because it can be replaced on walk }
ChildScope is a synthetic AST node that is visited during a walk to indicate that its descendent will be evaluated in a child scope, which may mask certain variables from the parent scope as locals.
ChildScope nodes don't really exist in the AST, but are rather synthesized on the fly during walk. Therefore it doesn't do any good to transform them; instead, transform either parent node that created a scope or the expression that the child scope struct wraps.
func (ChildScope) Range ¶
func (e ChildScope) Range() zcl.Range
Range returns the range of the expression that the ChildScope is encapsulating. It isn't really very useful to call Range on a ChildScope.
type ConditionalExpr ¶
type ConditionalExpr struct { Condition Expression TrueResult Expression FalseResult Expression SrcRange zcl.Range }
func (*ConditionalExpr) Range ¶
func (e *ConditionalExpr) Range() zcl.Range
func (*ConditionalExpr) StartRange ¶
func (e *ConditionalExpr) StartRange() zcl.Range
func (*ConditionalExpr) Value ¶
func (e *ConditionalExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*ConditionalExpr) Variables ¶
func (e *ConditionalExpr) Variables() []zcl.Traversal
type Expression ¶
type Expression interface { Node Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics) Variables() []zcl.Traversal StartRange() zcl.Range }
Expression is the abstract type for nodes that behave as zcl expressions.
func ParseExpression ¶
func ParseExpression(src []byte, filename string, start zcl.Pos) (Expression, zcl.Diagnostics)
ParseExpression parses the given buffer as a standalone zcl expression, returning it as an instance of Expression.
func ParseTemplate ¶
func ParseTemplate(src []byte, filename string, start zcl.Pos) (Expression, zcl.Diagnostics)
ParseTemplate parses the given buffer as a standalone zcl template, returning it as an instance of Expression.
type ForExpr ¶
type ForExpr struct { KeyVar string // empty if ignoring the key ValVar string CollExpr Expression KeyExpr Expression // nil when producing a tuple ValExpr Expression CondExpr Expression // null if no "if" clause is present Group bool // set if the ellipsis is used on the value in an object for SrcRange zcl.Range OpenRange zcl.Range CloseRange zcl.Range }
ForExpr represents iteration constructs:
tuple = [for i, v in list: upper(v) if i > 2] object = {for k, v in map: k => upper(v)} object_of_tuples = {for v in list: v.key: v...}
func (*ForExpr) StartRange ¶
func (*ForExpr) Value ¶
func (e *ForExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
type FunctionCallExpr ¶
type FunctionCallExpr struct { Name string Args []Expression // If true, the final argument should be a tuple, list or set which will // expand to be one argument per element. ExpandFinal bool NameRange zcl.Range OpenParenRange zcl.Range CloseParenRange zcl.Range }
FunctionCallExpr is an Expression that calls a function from the EvalContext and returns its result.
func (*FunctionCallExpr) Range ¶
func (e *FunctionCallExpr) Range() zcl.Range
func (*FunctionCallExpr) StartRange ¶
func (e *FunctionCallExpr) StartRange() zcl.Range
func (*FunctionCallExpr) Value ¶
func (e *FunctionCallExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*FunctionCallExpr) Variables ¶
func (e *FunctionCallExpr) Variables() []zcl.Traversal
type IndexExpr ¶
type IndexExpr struct { Collection Expression Key Expression SrcRange zcl.Range OpenRange zcl.Range }
func (*IndexExpr) StartRange ¶
func (*IndexExpr) Value ¶
func (e *IndexExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
type LiteralValueExpr ¶
LiteralValueExpr is an expression that just always returns a given value.
func (*LiteralValueExpr) Range ¶
func (e *LiteralValueExpr) Range() zcl.Range
func (*LiteralValueExpr) StartRange ¶
func (e *LiteralValueExpr) StartRange() zcl.Range
func (*LiteralValueExpr) Value ¶
func (e *LiteralValueExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*LiteralValueExpr) Variables ¶
func (e *LiteralValueExpr) Variables() []zcl.Traversal
type Node ¶
Node is the abstract type that every AST node implements.
This is a closed interface, so it cannot be implemented from outside of this package.
func Transform ¶
func Transform(node Node, t Transformer) (Node, zcl.Diagnostics)
Transform allows for in-place transformations of an AST starting with a particular node. The provider Transformer implementation drives the transformation process. The return value is the node that replaced the given top-level node.
type ObjectConsExpr ¶
type ObjectConsExpr struct { Items []ObjectConsItem SrcRange zcl.Range OpenRange zcl.Range }
func (*ObjectConsExpr) Range ¶
func (e *ObjectConsExpr) Range() zcl.Range
func (*ObjectConsExpr) StartRange ¶
func (e *ObjectConsExpr) StartRange() zcl.Range
func (*ObjectConsExpr) Value ¶
func (e *ObjectConsExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*ObjectConsExpr) Variables ¶
func (e *ObjectConsExpr) Variables() []zcl.Traversal
type ObjectConsItem ¶
type ObjectConsItem struct { KeyExpr Expression ValueExpr Expression }
type RelativeTraversalExpr ¶
type RelativeTraversalExpr struct { Source Expression Traversal zcl.Traversal SrcRange zcl.Range }
RelativeTraversalExpr is an Expression that retrieves a value from another value using a _relative_ traversal.
func (*RelativeTraversalExpr) Range ¶
func (e *RelativeTraversalExpr) Range() zcl.Range
func (*RelativeTraversalExpr) StartRange ¶
func (e *RelativeTraversalExpr) StartRange() zcl.Range
func (*RelativeTraversalExpr) Value ¶
func (e *RelativeTraversalExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*RelativeTraversalExpr) Variables ¶
func (e *RelativeTraversalExpr) Variables() []zcl.Traversal
type ScopeTraversalExpr ¶
ScopeTraversalExpr is an Expression that retrieves a value from the scope using a traversal.
func (*ScopeTraversalExpr) Range ¶
func (e *ScopeTraversalExpr) Range() zcl.Range
func (*ScopeTraversalExpr) StartRange ¶
func (e *ScopeTraversalExpr) StartRange() zcl.Range
func (*ScopeTraversalExpr) Value ¶
func (e *ScopeTraversalExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*ScopeTraversalExpr) Variables ¶
func (e *ScopeTraversalExpr) Variables() []zcl.Traversal
type SplatExpr ¶
type SplatExpr struct { Source Expression Each Expression Item *AnonSymbolExpr SrcRange zcl.Range MarkerRange zcl.Range }
func (*SplatExpr) StartRange ¶
func (*SplatExpr) Value ¶
func (e *SplatExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
type TemplateExpr ¶
type TemplateExpr struct { Parts []Expression SrcRange zcl.Range }
func (*TemplateExpr) Range ¶
func (e *TemplateExpr) Range() zcl.Range
func (*TemplateExpr) StartRange ¶
func (e *TemplateExpr) StartRange() zcl.Range
func (*TemplateExpr) Value ¶
func (e *TemplateExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*TemplateExpr) Variables ¶
func (e *TemplateExpr) Variables() []zcl.Traversal
type TemplateJoinExpr ¶
type TemplateJoinExpr struct {
Tuple Expression
}
TemplateJoinExpr is used to convert tuples of strings produced by template constructs (i.e. for loops) into flat strings, by converting the values tos strings and joining them. This AST node is not used directly; it's produced as part of the AST of a "for" loop in a template.
func (*TemplateJoinExpr) Range ¶
func (e *TemplateJoinExpr) Range() zcl.Range
func (*TemplateJoinExpr) StartRange ¶
func (e *TemplateJoinExpr) StartRange() zcl.Range
func (*TemplateJoinExpr) Value ¶
func (e *TemplateJoinExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*TemplateJoinExpr) Variables ¶
func (e *TemplateJoinExpr) Variables() []zcl.Traversal
type TemplateWrapExpr ¶
type TemplateWrapExpr struct { Wrapped Expression SrcRange zcl.Range }
TemplateWrapExpr is used instead of a TemplateExpr when a template consists _only_ of a single interpolation sequence. In that case, the template's result is the single interpolation's result, verbatim with no type conversions.
func (*TemplateWrapExpr) Range ¶
func (e *TemplateWrapExpr) Range() zcl.Range
func (*TemplateWrapExpr) StartRange ¶
func (e *TemplateWrapExpr) StartRange() zcl.Range
func (*TemplateWrapExpr) Value ¶
func (e *TemplateWrapExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*TemplateWrapExpr) Variables ¶
func (e *TemplateWrapExpr) Variables() []zcl.Traversal
type Token ¶
Token represents a sequence of bytes from some zcl code that has been tagged with a type and its range within the source file.
type TokenType ¶
type TokenType rune
TokenType is an enumeration used for the Type field on Token.
const ( TokenOBrace TokenType = '{' TokenCBrace TokenType = '}' TokenOBrack TokenType = '[' TokenCBrack TokenType = ']' TokenOParen TokenType = '(' TokenCParen TokenType = ')' TokenOQuote TokenType = '«' TokenCQuote TokenType = '»' TokenOHeredoc TokenType = 'H' TokenCHeredoc TokenType = 'h' TokenStar TokenType = '*' TokenSlash TokenType = '/' TokenPlus TokenType = '+' TokenMinus TokenType = '-' TokenPercent TokenType = '%' TokenEqual TokenType = '=' TokenEqualOp TokenType = '≔' TokenNotEqual TokenType = '≠' TokenLessThan TokenType = '<' TokenLessThanEq TokenType = '≤' TokenGreaterThan TokenType = '>' TokenGreaterThanEq TokenType = '≥' TokenAnd TokenType = '∧' TokenOr TokenType = '∨' TokenBang TokenType = '!' TokenDot TokenType = '.' TokenComma TokenType = ',' TokenEllipsis TokenType = '…' TokenFatArrow TokenType = '⇒' TokenQuestion TokenType = '?' TokenColon TokenType = ':' TokenTemplateInterp TokenType = '∫' TokenTemplateControl TokenType = 'λ' TokenTemplateSeqEnd TokenType = '∎' TokenQuotedLit TokenType = 'Q' // might contain backslash escapes TokenStringLit TokenType = 'S' // cannot contain backslash escapes TokenNumberLit TokenType = 'N' TokenIdent TokenType = 'I' TokenComment TokenType = 'C' TokenNewline TokenType = '\n' TokenEOF TokenType = '␄' TokenBitwiseAnd TokenType = '&' TokenBitwiseOr TokenType = '|' TokenBitwiseNot TokenType = '~' TokenBitwiseXor TokenType = '^' TokenStarStar TokenType = '➚' TokenBacktick TokenType = '`' TokenSemicolon TokenType = ';' TokenTabs TokenType = '␉' TokenInvalid TokenType = '�' TokenBadUTF8 TokenType = '💩' // TokenNil is a placeholder for when a token is required but none is // available, e.g. when reporting errors. The scanner will never produce // this as part of a token stream. TokenNil TokenType = '\x00' )
type Tokens ¶
type Tokens []Token
Tokens is a slice of Token.
func LexConfig ¶
LexConfig performs lexical analysis on the given buffer, treating it as a whole zcl config file, and returns the resulting tokens.
Only minimal validation is done during lexical analysis, so the returned diagnostics may include errors about lexical issues such as bad character encodings or unrecognized characters, but full parsing is required to detect _all_ syntax errors.
func LexExpression ¶
LexExpression performs lexical analysis on the given buffer, treating it as a standalone zcl expression, and returns the resulting tokens.
Only minimal validation is done during lexical analysis, so the returned diagnostics may include errors about lexical issues such as bad character encodings or unrecognized characters, but full parsing is required to detect _all_ syntax errors.
func LexTemplate ¶
LexTemplate performs lexical analysis on the given buffer, treating it as a standalone zcl template, and returns the resulting tokens.
Only minimal validation is done during lexical analysis, so the returned diagnostics may include errors about lexical issues such as bad character encodings or unrecognized characters, but full parsing is required to detect _all_ syntax errors.
type Transformer ¶
type Transformer interface { // Transform accepts a node and returns a replacement node along with // a flag for whether to also visit child nodes. If the flag is false, // none of the child nodes will be visited and the TransformExit method // will not be called for the node. // // It is acceptable and appropriate for Transform to return the same node // it was given, for situations where no transform is needed. Transform(node Node) (Node, bool, zcl.Diagnostics) // TransformExit signals the end of transformations of child nodes of the // given node. If Transform returned a new node, the given node is the // node that was returned, rather than the node that was originally // encountered. TransformExit(node Node) zcl.Diagnostics }
Transformer is an interface used with Transform
type TupleConsExpr ¶
type TupleConsExpr struct { Exprs []Expression SrcRange zcl.Range OpenRange zcl.Range }
func (*TupleConsExpr) Range ¶
func (e *TupleConsExpr) Range() zcl.Range
func (*TupleConsExpr) StartRange ¶
func (e *TupleConsExpr) StartRange() zcl.Range
func (*TupleConsExpr) Value ¶
func (e *TupleConsExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*TupleConsExpr) Variables ¶
func (e *TupleConsExpr) Variables() []zcl.Traversal
type UnaryOpExpr ¶
func (*UnaryOpExpr) Range ¶
func (e *UnaryOpExpr) Range() zcl.Range
func (*UnaryOpExpr) StartRange ¶
func (e *UnaryOpExpr) StartRange() zcl.Range
func (*UnaryOpExpr) Value ¶
func (e *UnaryOpExpr) Value(ctx *zcl.EvalContext) (cty.Value, zcl.Diagnostics)
func (*UnaryOpExpr) Variables ¶
func (e *UnaryOpExpr) Variables() []zcl.Traversal
type VisitFunc ¶
type VisitFunc func(node Node) zcl.Diagnostics
VisitFunc is the callback signature for VisitAll.
type Walker ¶
type Walker interface { Enter(node Node) zcl.Diagnostics Exit(node Node) zcl.Diagnostics }
Walker is an interface used with Walk.