zcl

package
v0.0.0-...-5239390 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2017 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attribute 

type Attribute struct {
	Name string
	Expr Expression

	Range     Range
	NameRange Range
}

Attribute represents an attribute from within a body.

type AttributeSchema 

type AttributeSchema struct {
	Name     string
	Required bool
}

AttributeSchema represents the requirements for an attribute, and is used for matching attributes within bodies.

type Attributes 

type Attributes map[string]*Attribute

Attributes is a set of attributes keyed by their names.

type Block 

type Block struct {
	Type   string
	Labels []string
	Body   Body

	DefRange    Range   // Range that can be considered the "definition" for seeking in an editor
	TypeRange   Range   // Range for the block type declaration specifically.
	LabelRanges []Range // Ranges for the label values specifically.
}

Block represents a nested block within a Body.

type BlockHeaderSchema 

type BlockHeaderSchema struct {
	Type       string
	LabelNames []string
}

BlockHeaderSchema represents the shape of a block header, and is used for matching blocks within bodies.

type Blocks 

type Blocks []*Block

Blocks is a sequence of Block.

func (Blocks) ByType 

func (els Blocks) ByType() map[string]Blocks

ByType transforms the receiving block sequence into a map from type name to block sequences of only that type.

func (Blocks) OfType 

func (els Blocks) OfType(typeName string) Blocks

OfType filters the receiving block sequence by block type name, returning a new block sequence including only the blocks of the requested type.

type Body 

type Body interface {
	// Content verifies that the entire body content conforms to the given
	// schema and then returns it, and/or returns diagnostics. The returned
	// body content is valid if non-nil, regardless of whether Diagnostics
	// are provided, but diagnostics should still be eventually shown to
	// the user.
	Content(schema *BodySchema) (*BodyContent, Diagnostics)

	// PartialContent is like Content except that it permits the configuration
	// to contain additional blocks or attributes not specified in the
	// schema. If any are present, the returned Body is non-nil and contains
	// the remaining items from the body that were not selected by the schema.
	PartialContent(schema *BodySchema) (*BodyContent, Body, Diagnostics)

	// JustAttributes attempts to interpret all of the contents of the body
	// as attributes, allowing for the contents to be accessed without a priori
	// knowledge of the structure.
	//
	// The behavior of this method depends on the body's source language.
	// Some languages, like JSON, can't distinguish between attributes and
	// blocks without schema hints, but for languages that _can_ error
	// diagnostics will be generated if any blocks are present in the body.
	//
	// Diagnostics may be produced for other reasons too, such as duplicate
	// declarations of the same attribute.
	JustAttributes() (Attributes, Diagnostics)

	// MissingItemRange returns a range that represents where a missing item
	// might hypothetically be inserted. This is used when producing
	// diagnostics about missing required attributes or blocks. Not all bodies
	// will have an obvious single insertion point, so the result here may
	// be rather arbitrary.
	MissingItemRange() Range
}

Body is a container for attributes and blocks. It serves as the primary unit of heirarchical structure within configuration.

The content of a body cannot be meaningfully intepreted without a schema, so Body represents the raw body content and has methods that allow the content to be extracted in terms of a given schema.

func EmptyBody 

func EmptyBody() Body

EmptyBody returns a body with no content. This body can be used as a placeholder when a body is required but no body content is available.

func MergeBodies 

func MergeBodies(bodies []Body) Body

MergeBodies is like MergeFiles except it deals directly with bodies, rather than with entire files.

func MergeFiles 

func MergeFiles(files []*File) Body

MergeFiles combines the given files to produce a single body that contains configuration from all of the given files.

The ordering of the given files decides the order in which contained elements will be returned. If any top-level attributes are defined with the same name across multiple files, a diagnostic will be produced from the Content and PartialContent methods describing this error in a user-friendly way.

type BodyContent 

type BodyContent struct {
	Attributes Attributes
	Blocks     Blocks

	MissingItemRange Range
}

BodyContent is the result of applying a BodySchema to a Body.

type BodySchema 

type BodySchema struct {
	Attributes []AttributeSchema
	Blocks     []BlockHeaderSchema
}

BodySchema represents the desired shallow structure of a body.

type Diagnostic 

type Diagnostic struct {
	Severity DiagnosticSeverity

	// Summary and detail contain the English-language description of the
	// problem. Summary is a terse description of the general problem and
	// detail is a more elaborate, often-multi-sentence description of
	// the probem and what might be done to solve it.
	Summary string
	Detail  string
	Subject *Range
	Context *Range
}

Diagnostic represents information to be presented to a user about an error or anomoly in parsing or evaluating configuration.

func (*Diagnostic) Error 

func (d *Diagnostic) Error() string

error implementation, so that diagnostics can be returned via APIs that normally deal in vanilla Go errors.

This presents only minimal context about the error, for compatibility with usual expectations about how errors will present as strings.

type DiagnosticSeverity 

type DiagnosticSeverity int

DiagnosticSeverity represents the severity of a diagnostic. 

const (
	// DiagInvalid is the invalid zero value of DiagnosticSeverity
	DiagInvalid DiagnosticSeverity = iota

	// DiagError indicates that the problem reported by a diagnostic prevents
	// further progress in parsing and/or evaluating the subject.
	DiagError

	// DiagWarning indicates that the problem reported by a diagnostic warrants
	// user attention but does not prevent further progress. It is most
	// commonly used for showing deprecation notices.
	DiagWarning
)

type DiagnosticWriter 

type DiagnosticWriter interface {
	WriteDiagnostic(*Diagnostic) error
	WriteDiagnostics(Diagnostics) error
}

A DiagnosticWriter emits diagnostics somehow.

func NewDiagnosticTextWriter 

func NewDiagnosticTextWriter(wr io.Writer, files map[string]*File, width uint, color bool) DiagnosticWriter

NewDiagnosticTextWriter creates a DiagnosticWriter that writes diagnostics to the given writer as formatted text.

It is designed to produce text appropriate to print in a monospaced font in a terminal of a particular width, or optionally with no width limit.

The given width may be zero to disable word-wrapping of the detail text and truncation of source code snippets.

If color is set to true, the output will include VT100 escape sequences to color-code the severity indicators. It is suggested to turn this off if the target writer is not a terminal.

type Diagnostics 

type Diagnostics []*Diagnostic

Diagnostics is a list of Diagnostic instances.

func Index 

func Index(collection, key cty.Value, srcRange *Range) (cty.Value, Diagnostics)

Index is a helper function that performs the same operation as the index operator in the zcl expression language. That is, the result is the same as it would be for collection[key] in a configuration expression.

This is exported so that applications can perform indexing in a manner consistent with how the language does it, including handling of null and unknown values, etc.

Diagnostics are produced if the given combination of values is not valid. Therefore a pointer to a source range must be provided to use in diagnostics, though nil can be provided if the calling application is going to ignore the subject of the returned diagnostics anyway.

func (Diagnostics) Append 

func (d Diagnostics) Append(diag *Diagnostic) Diagnostics

Append appends a new error to a Diagnostics and return the whole Diagnostics.

This is provided as a convenience for returning from a function that collects and then returns a set of diagnostics: 

return nil, diags.Append(&zcl.Diagnostic{ ... })

Note that this modifies the array underlying the diagnostics slice, so must be used carefully within a single codepath. It is incorrect (and rude) to extend a diagnostics created by a different subsystem.

func (Diagnostics) Error 

func (d Diagnostics) Error() string

error implementation, so that sets of diagnostics can be returned via APIs that normally deal in vanilla Go errors.

func (Diagnostics) Extend 

func (d Diagnostics) Extend(diags Diagnostics) Diagnostics

Extend concatenates the given Diagnostics with the receiver and returns the whole new Diagnostics.

This is similar to Append but accepts multiple diagnostics to add. It has all the same caveats and constraints.

func (Diagnostics) HasErrors 

func (d Diagnostics) HasErrors() bool

HasErrors returns true if the receiver contains any diagnostics of severity DiagError.

type EvalContext 

type EvalContext struct {
	Variables map[string]cty.Value
	Functions map[string]function.Function
	// contains filtered or unexported fields
}

An EvalContext provides the variables and functions that should be used to evaluate an expression.

func (*EvalContext) NewChild 

func (ctx *EvalContext) NewChild() *EvalContext

NewChild returns a new EvalContext that is a child of the receiver.

func (*EvalContext) Parent 

func (ctx *EvalContext) Parent() *EvalContext

Parent returns the parent of the receiver, or nil if the receiver has no parent.

type Expression 

type Expression interface {
	// Value returns the value resulting from evaluating the expression
	// in the given evaluation context.
	//
	// The context may be nil, in which case the expression may contain
	// only constants and diagnostics will be produced for any non-constant
	// sub-expressions. (The exact definition of this depends on the source
	// language.)
	//
	// The context may instead be set but have either its Variables or
	// Functions maps set to nil, in which case only use of these features
	// will return diagnostics.
	//
	// Different diagnostics are provided depending on whether the given
	// context maps are nil or empty. In the former case, the message
	// tells the user that variables/functions are not permitted at all,
	// while in the latter case usage will produce a "not found" error for
	// the specific symbol in question.
	Value(ctx *EvalContext) (cty.Value, Diagnostics)

	// Variables returns a list of variables referenced in the receiving
	// expression. These are expressed as absolute Traversals, so may include
	// additional information about how the variable is used, such as
	// attribute lookups, which the calling application can potentially use
	// to only selectively populate the scope.
	Variables() []Traversal

	Range() Range
	StartRange() Range
}

Expression is a literal value or an expression provided in the configuration, which can be evaluated within a scope to produce a value.

type File 

type File struct {
	Body  Body
	Bytes []byte

	// Nav is used to integrate with the "zcled" editor integration package,
	// and with diagnostic information formatters. It is not for direct use
	// by a calling application.
	Nav interface{}
}

File is the top-level node that results from parsing a ZCL file.

type Pos 

type Pos struct {
	// Line is the source code line where this position points. Lines are
	// counted starting at 1 and incremented for each newline character
	// encountered.
	Line int

	// Column is the source code column where this position points, in
	// unicode characters, with counting starting at 1.
	//
	// Column counts characters as they appear visually, so for example a
	// latin letter with a combining diacritic mark counts as one character.
	// This is intended for rendering visual markers against source code in
	// contexts where these diacritics would be rendered in a single character
	// cell. Technically speaking, Column is counting grapheme clusters as
	// used in unicode normalization.
	Column int

	// Byte is the byte offset into the file where the indicated character
	// begins. This is a zero-based offset to the first byte of the first
	// UTF-8 codepoint sequence in the character, and thus gives a position
	// that can be resolved _without_ awareness of Unicode characters.
	Byte int
}

Pos represents a single position in a source file, by addressing the start byte of a unicode character encoded in UTF-8.

Pos is generally used only in the context of a Range, which then defines which source file the position is within.

type Range 

type Range struct {
	// Filename is the name of the file into which this range's positions
	// point.
	Filename string

	// Start and End represent the bounds of this range. Start is inclusive
	// and End is exclusive.
	Start, End Pos
}

Range represents a span of characters between two positions in a source file.

This struct is usually used by value in types that represent AST nodes, but by pointer in types that refer to the positions of other objects, such as in diagnostics.

func RangeBetween 

func RangeBetween(start, end Range) Range

RangeBetween returns a new range that spans from the beginning of the start range to the end of the end range.

The result is meaningless if the two ranges do not belong to the same source file or if the end range appears before the start range.

func (Range) ContainsOffset 

func (r Range) ContainsOffset(offset int) bool

ContainsOffset returns true if and only if the given byte offset is within the receiving Range.

func (Range) Ptr 

func (r Range) Ptr() *Range

Ptr returns a pointer to a copy of the receiver. This is a convenience when ranges in places where pointers are required, such as in Diagnostic, but the range in question is returned from a method. Go would otherwise not allow one to take the address of a function call.

func (Range) String 

func (r Range) String() string

String returns a compact string representation of the receiver. Callers should generally prefer to present a range more visually, e.g. via markers directly on the relevant portion of source code.

type Traversal 

type Traversal []Traverser

A Traversal is a description of traversing through a value through a series of operations such as attribute lookup, index lookup, etc.

It is used to look up values in scopes, for example.

The traversal operations are implementations of interface Traverser. This is a closed set of implementations, so the interface cannot be implemented from outside this package.

A traversal can be absolute (its first value is a symbol name) or relative (starts from an existing value).

func TraversalJoin 

func TraversalJoin(abs Traversal, rel Traversal) Traversal

TraversalJoin appends a relative traversal to an absolute traversal to produce a new absolute traversal.

func (Traversal) IsRelative 

func (t Traversal) IsRelative() bool

IsRelative returns true if the receiver is a relative traversal, or false otherwise.

func (Traversal) RootName 

func (t Traversal) RootName() string

RootName returns the root name for a absolute traversal. Will panic if called on a relative traversal.

func (Traversal) SimpleSplit 

func (t Traversal) SimpleSplit() TraversalSplit

SimpleSplit returns a TraversalSplit where the name lookup is the absolute part and the remainder is the relative part. Supported only for absolute traversals, and will panic if applied to a relative traversal.

This can be used by applications that have a relatively-simple variable namespace where only the top-level is directly populated in the scope, with everything else handled by relative lookups from those initial values.

func (Traversal) TraverseAbs 

func (t Traversal) TraverseAbs(ctx *EvalContext) (cty.Value, Diagnostics)

TraverseAbs applies the receiving traversal to the given eval context, returning the resulting value. This is supported only for absolute traversals, and will panic if applied to a relative traversal.

func (Traversal) TraverseRel 

func (t Traversal) TraverseRel(val cty.Value) (cty.Value, Diagnostics)

TraverseRel applies the receiving traversal to the given value, returning the resulting value. This is supported only for relative traversals, and will panic if applied to an absolute traversal.

type TraversalSplit 

type TraversalSplit struct {
	Abs Traversal
	Rel Traversal
}

TraversalSplit represents a pair of traversals, the first of which is an absolute traversal and the second of which is relative to the first.

This is used by calling applications that only populate prefixes of the traversals in the scope, with Abs representing the part coming from the scope and Rel representing the remaining steps once that part is retrieved.

func (TraversalSplit) Join 

func (t TraversalSplit) Join() Traversal

Join concatenates together the Abs and Rel parts to produce a single absolute traversal.

func (TraversalSplit) RootName 

func (t TraversalSplit) RootName() string

RootName returns the root name for the absolute part of the split.

func (TraversalSplit) Traverse 

func (t TraversalSplit) Traverse(ctx *EvalContext) (cty.Value, Diagnostics)

Traverse is a convenience function to apply TraverseAbs followed by TraverseRel.

func (TraversalSplit) TraverseAbs 

func (t TraversalSplit) TraverseAbs(ctx *EvalContext) (cty.Value, Diagnostics)

TraverseAbs traverses from a scope to the value resulting from the absolute traversal.

func (TraversalSplit) TraverseRel 

func (t TraversalSplit) TraverseRel(val cty.Value) (cty.Value, Diagnostics)

TraverseRel traverses from a given value, assumed to be the result of TraverseAbs on some scope, to a final result for the entire split traversal.

type TraverseAttr 

type TraverseAttr struct {
	Name     string
	SrcRange Range
	// contains filtered or unexported fields
}

TraverseAttr looks up an attribute in its initial value.

func (TraverseAttr) TraversalStep 

func (tn TraverseAttr) TraversalStep(val cty.Value) (cty.Value, Diagnostics)

type TraverseIndex 

type TraverseIndex struct {
	Key      cty.Value
	SrcRange Range
	// contains filtered or unexported fields
}

TraverseIndex applies the index operation to its initial value.

func (TraverseIndex) TraversalStep 

func (tn TraverseIndex) TraversalStep(val cty.Value) (cty.Value, Diagnostics)

type TraverseRoot 

type TraverseRoot struct {
	Name     string
	SrcRange Range
	// contains filtered or unexported fields
}

TraverseRoot looks up a root name in a scope. It is used as the first step of an absolute Traversal, and cannot itself be traversed directly.

func (TraverseRoot) TraversalStep 

func (tn TraverseRoot) TraversalStep(cty.Value) (cty.Value, Diagnostics)

TraversalStep on a TraverseName immediately panics, because absolute traversals cannot be directly traversed.

type TraverseSplat 

type TraverseSplat struct {
	Each     Traversal
	SrcRange Range
	// contains filtered or unexported fields
}

TraverseSplat applies the splat operation to its initial value.

func (TraverseSplat) TraversalStep 

func (tn TraverseSplat) TraversalStep(val cty.Value) (cty.Value, Diagnostics)

type Traverser 

type Traverser interface {
	TraversalStep(cty.Value) (cty.Value, Diagnostics)
	// contains filtered or unexported methods
}

A Traverser is a step within a Traversal.

Source Files

View all Source files

Directories

Path Synopsis
Package hclhil adapts Hashicorp Configuration Language and Hashicorp Interpolation Language (HCL and HIL, respectively) to work within the ZCL API.
 Package hclhil adapts Hashicorp Configuration Language and Hashicorp Interpolation Language (HCL and HIL, respectively) to work within the ZCL API.
Package json is the JSON parser for ZCL.
 Package json is the JSON parser for ZCL.
Package zclsyntax contains the parser, AST, etc for zcl's native language, as opposed to the JSON variant and the HCL/HIL shim.
 Package zclsyntax contains the parser, AST, etc for zcl's native language, as opposed to the JSON variant and the HCL/HIL shim.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.