adt

package
v0.3.0-alpha4 Latest Latest
Warning

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

Go to latest
Published: Oct 3, 2020 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package adt represents partially and fully evaluated CUE types.

This package introduces several categories of types that indicate some set of values that may be used in a certain situation. Concrete types may belong to multiple categories.

Abstract Types

The following types describe the a place where a value may be used:

Decl       a value than can be used as a StructLit element.
Elem       a value than can be used as a ListLit element.
Expr       represents an Expr in the CUE grammar.
Value      a fully evaluated value that has no references (except for
           children in composite values).
Node       any of the above values.

The following types categorize nodes by function:

Resolver   a reference to position in the result tree.
Evaluator  evaluates to 1 value.
Yielder    evaluates to 0 or more values.
Validator  validates another value.

Reference resolution algorithm

A Resolver is resolved within the context of an Environment. In CUE, a reference is evaluated by substituting it with a copy of the value to which it refers. If the copied value itself contains references we can distinguish two different cases. References that refer to values within the copied reference (not regarding selectors) will henceforth point to the copied node. References that point to outside the referened value will keep referring to their original value.

a: b: {
  c: int
  d: c
  e: f
}
f: 4
g: a.b { // d.c points to inside the referred value, e.f, not.
  c: 3
}

The implementation doesn't actually copy referred values, but rather resolves references with the aid of an Environment. During compile time, each references is associated with the label and a number indicating in which parent scope (offset from the current) this label needs to be looked up. An Environment keeps track of the point at which a value was referenced, providing enough information to look up the labeled value. This Environment is the identical for all references within a fields conjunct. Often, an Environment can even be shared among conjuncts.

Values

Values are fully evaluated expressions. As this means that all references will have been eliminated, Values are fully defined without the need for an Environment. Additionally, Values represent a fully evaluated form, stripped of any comprehensions, optional fields or embeddings.

Index

Constants

View Source
const MaxIndex int64 = 1<<28 - 1

MaxIndex indicates the maximum number of unique strings that are used for labeles within this CUE implementation.

Variables

This section is empty.

Functions

func IsConcrete

func IsConcrete(v Value) bool

IsConcrete returns whether a value is concrete.

func Pos

func Pos(n Node) token.Pos

Pos returns the file position of n, or token.NoPos if it is unknown.

Types

type Acceptor

type Acceptor interface {
	// Accept reports whether a given field is accepted as output.
	// Pass an InvalidLabel to determine whether this is always open.
	Accept(ctx *OpContext, f Feature) bool

	// MatchAndInsert finds the conjuncts for optional fields, pattern
	// constraints, and additional constraints that match f and inserts them in
	// arc. Use f is 0 to match all additional constraints only.
	MatchAndInsert(c *OpContext, arc *Vertex)

	// OptionalTypes returns a bit field with the type of optional constraints
	// that are represented by this Acceptor.
	OptionalTypes() OptionalType
}

Acceptor is a single interface that reports whether feature f is a valid field label for this vertex.

TODO: combine this with the StructMarker functionality?

type BasicType

type BasicType struct {
	Src *ast.Ident
	K   Kind
}

BasicType represents all values of a certain Kind. It can be used as a Value and Expr.

string
int
num
bool

func (*BasicType) Concreteness

func (*BasicType) Concreteness() Concreteness

func (*BasicType) Kind

func (x *BasicType) Kind() Kind

func (*BasicType) Source

func (x *BasicType) Source() ast.Node

type BinaryExpr

type BinaryExpr struct {
	Src *ast.BinaryExpr
	Op  Op
	X   Expr
	Y   Expr
}

BinaryExpr is a binary expression.

X + Y
X & Y

func (*BinaryExpr) Source

func (x *BinaryExpr) Source() ast.Node

type Bool

type Bool struct {
	Src ast.Node
	B   bool
}

Bool is a boolean value. It can be used as a Value and Expr.

func (*Bool) Concreteness

func (*Bool) Concreteness() Concreteness

func (*Bool) Kind

func (x *Bool) Kind() Kind

func (*Bool) Source

func (x *Bool) Source() ast.Node

type Bottom

type Bottom struct {
	Src ast.Node
	Err errors.Error

	Code         ErrorCode
	HasRecursive bool
	ChildError   bool // Err is the error of the child
	// Value holds the computed value so far in case
	Value Value
}

Bottom represents an error or bottom symbol.

Although a Bottom node holds control data, it should not be created until the control information already resulted in an error.

func CombineErrors

func CombineErrors(src ast.Node, x, y Value) *Bottom

CombineErrors combines two errors that originate at the same Vertex.

func (*Bottom) Concreteness

func (*Bottom) Concreteness() Concreteness

func (*Bottom) IsIncomplete

func (b *Bottom) IsIncomplete() bool

func (*Bottom) Kind

func (x *Bottom) Kind() Kind

func (*Bottom) Source

func (x *Bottom) Source() ast.Node

func (*Bottom) Specialize

func (x *Bottom) Specialize(k Kind) Value

type BoundExpr

type BoundExpr struct {
	Src  *ast.UnaryExpr
	Op   Op
	Expr Expr
}

BoundExpr represents an unresolved unary comparator.

<a
=~MyPattern

func (*BoundExpr) Source

func (x *BoundExpr) Source() ast.Node

type BoundValue

type BoundValue struct {
	Src   ast.Expr
	Op    Op
	Value Value
}

A BoundValue is a fully evaluated unary comparator that can be used to validate other values.

<5
=~"Name$"

func (*BoundValue) Concreteness

func (*BoundValue) Concreteness() Concreteness

func (*BoundValue) Kind

func (x *BoundValue) Kind() Kind

func (*BoundValue) Source

func (x *BoundValue) Source() ast.Node

type Builtin

type Builtin struct {
	// TODO:  make these values for better type checking.
	Params []Kind
	Result Kind
	Func   func(c *OpContext, args []Value) Expr

	Package Feature
	Name    string
	// REMOVE: for legacy
	Const string
}

A Builtin is a value representing a native function call.

func (*Builtin) Concreteness

func (*Builtin) Concreteness() Concreteness

Constraint only applies if Builtin is used as constraint.

func (*Builtin) Kind

func (x *Builtin) Kind() Kind

Kind here represents the case where Builtin is used as a Validator.

func (*Builtin) Source

func (x *Builtin) Source() ast.Node

func (*Builtin) WriteName

func (x *Builtin) WriteName(w io.Writer, c *OpContext)

type BuiltinValidator

type BuiltinValidator struct {
	Src     *ast.CallExpr
	Builtin *Builtin
	Args    []Value // any but the first value
}

A BuiltinValidator is a Value that results from evaluation a partial call to a builtin (using CallExpr).

strings.MinRunes(4)

func (*BuiltinValidator) Concreteness

func (*BuiltinValidator) Concreteness() Concreteness

func (*BuiltinValidator) Kind

func (x *BuiltinValidator) Kind() Kind

func (*BuiltinValidator) Source

func (x *BuiltinValidator) Source() ast.Node

type BulkOptionalField

type BulkOptionalField struct {
	Src    *ast.Field // Elipsis or Field
	Filter Expr
	Value  Expr
	Label  Feature // for reference and formatting
}

A BulkOptionalField represents a set of optional field.

[expr]: expr

func (*BulkOptionalField) Source

func (x *BulkOptionalField) Source() ast.Node

type Bytes

type Bytes struct {
	Src ast.Node
	B   []byte
	RE  *regexp.Regexp // only set if needed
}

Bytes is a bytes value. It can be used as a Value and Expr.

func (*Bytes) Concreteness

func (*Bytes) Concreteness() Concreteness

func (*Bytes) Kind

func (x *Bytes) Kind() Kind

func (*Bytes) Source

func (x *Bytes) Source() ast.Node

type CallExpr

type CallExpr struct {
	Src  *ast.CallExpr
	Fun  Expr
	Args []Expr
}

A CallExpr represents a call to a builtin.

len(x)
strings.ToLower(x)

func (*CallExpr) Source

func (x *CallExpr) Source() ast.Node

type Concreteness

type Concreteness int

Concreteness is a measure of the level of concreteness of a value, where lower values mean more concrete.

const (
	BottomLevel Concreteness = iota

	// Concrete indicates a concrete scalar value, list or struct.
	Concrete

	// Constraint indicates a non-concrete scalar value that is more specific,
	// than a top-level type.
	Constraint

	// PrimitiveType indicates a top-level specific type, for instance, string,
	// bytes, number, or bool.
	Type

	// Any indicates any value, or top.
	Any
)

type Config

type Config struct {
	Runtime
	Unifier

	Format func(Node) string
}

type Conjunct

type Conjunct struct {
	Env *Environment

	// CloseID is a unique number that tracks a group of conjuncts that need
	// belong to a single originating definition.
	CloseID ID
	// contains filtered or unexported fields
}

An Conjunct is an Environment-Expr pair. The Environment is the starting point for reference lookup for any reference contained in X.

func MakeConjunct

func MakeConjunct(env *Environment, x Node, id ID) Conjunct

func MakeRootConjunct

func MakeRootConjunct(env *Environment, x Node) Conjunct

MakeRootConjunct creates a conjunct from the given environment and node. It panics if x cannot be used as an expression.

func (*Conjunct) Expr

func (c *Conjunct) Expr() Expr

func (*Conjunct) Field

func (c *Conjunct) Field() Node

func (*Conjunct) ID

func (c *Conjunct) ID() ID

func (*Conjunct) Source

func (c *Conjunct) Source() ast.Node

type Conjunction

type Conjunction struct {
	Src    ast.Expr
	Values []Value
}

A Conjunction is a conjunction of values that cannot be represented as a single value. It is the result of unification.

func (*Conjunction) Concreteness

func (*Conjunction) Concreteness() Concreteness

func (*Conjunction) Kind

func (x *Conjunction) Kind() Kind

func (*Conjunction) Source

func (x *Conjunction) Source() ast.Node

type Decl

type Decl interface {
	Node
	// contains filtered or unexported methods
}

A Decl represents all valid StructLit elements.

type Disjunct

type Disjunct struct {
	Val     Expr
	Default bool
}

A Disjunct is used in Disjunction.

type Disjunction

type Disjunction struct {
	Src ast.Expr

	// Values are the non-error disjuncts of this expression. The first
	// NumDefault values are default values.
	Values []*Vertex

	Errors *Bottom // []bottom

	// NumDefaults indicates the number of default values.
	NumDefaults int
}

A disjunction is a disjunction of values. It is the result of expanding a DisjunctionExpr if the expression cannot be represented as a single value.

func (*Disjunction) Concreteness

func (*Disjunction) Concreteness() Concreteness

func (*Disjunction) Default

func (d *Disjunction) Default() Value

func (*Disjunction) Kind

func (x *Disjunction) Kind() Kind

func (*Disjunction) Source

func (x *Disjunction) Source() ast.Node

type DisjunctionExpr

type DisjunctionExpr struct {
	Src    *ast.BinaryExpr
	Values []Disjunct

	HasDefaults bool
}

A Disjunction represents a disjunction, where each disjunct may or may not be marked as a default.

func (*DisjunctionExpr) Source

func (x *DisjunctionExpr) Source() ast.Node

type DynamicField

type DynamicField struct {
	Src   *ast.Field
	Key   Expr
	Value Expr
}

A DynamicField represents a regular field for which the key is computed.

"\(expr)": expr
(expr): expr

func (*DynamicField) IsOptional

func (x *DynamicField) IsOptional() bool

func (*DynamicField) Source

func (x *DynamicField) Source() ast.Node

type DynamicReference

type DynamicReference struct {
	Src     *ast.Ident
	UpCount int32
	Label   Expr

	// TODO: only use aliases and store the actual expression only in the scope.
	// The feature is unique for every instance. This will also allow dynamic
	// fields to be ordered among normal fields.
	//
	// This could also be used to assign labels to embedded values, if they
	// don't match a label.
	Alias Feature
}

A DynamicReference is like a LabelReference, but with a computed label.

X=(x): X
X="\(x)": X

func (*DynamicReference) Source

func (x *DynamicReference) Source() ast.Node

type Elem

type Elem interface {
	Decl
	// contains filtered or unexported methods
}

An Elem represents all value ListLit elements.

All Elem values can be used as a Decl.

type Ellipsis

type Ellipsis struct {
	Src   *ast.Ellipsis
	Value Expr
}

A Ellipsis represents a set of optional fields of a given type.

...T

func (*Ellipsis) Source

func (x *Ellipsis) Source() ast.Node

type Environment

type Environment struct {
	Up     *Environment
	Vertex *Vertex

	// DynamicLabel is only set when instantiating a field from a pattern
	// constraint. It is used to resolve label references.
	DynamicLabel Feature

	// Cyclic indicates a structural cycle was detected for this conjunct or one
	// of its ancestors.
	Cyclic bool

	// Deref keeps track of nodes that should dereference to Vertex. It is used
	// for detecting structural cycle.
	//
	// The detection algorithm is based on Tomabechi's quasi-destructive graph
	// unification. This detection requires dependencies to be resolved into
	// fully dereferenced vertices. This is not the case in our algorithm:
	// the result of evaluating conjuncts is placed into dereferenced vertices
	// _after_ they are evaluated, but the Environment still points to the
	// non-dereferenced context.
	//
	// In order to be able to detect structural cycles, we need to ensure that
	// at least one node that is part of a cycle in the context in which
	// conjunctions are evaluated dereferences correctly.
	//
	// The only field necessary to detect a structural cycle, however, is
	// the Status field of the Vertex. So rather than dereferencing a node
	// proper, it is sufficient to copy the Status of the dereferenced nodes
	// to these nodes (will always be EvaluatingArcs).
	Deref []*Vertex

	// Cycles contains vertices for which cycles are detected. It is used
	// for tracking self-references within structural cycles.
	//
	// Unlike Deref, Cycles is not incremented with child nodes.
	// TODO: Cycles is always a tail end of Deref, so this can be optimized.
	Cycles []*Vertex
	// contains filtered or unexported fields
}

An Environment links the parent scopes for identifier lookup to a composite node. Each conjunct that make up node in the tree can be associated with a different environment (although some conjuncts may share an Environment).

type ErrorCode

type ErrorCode int

ErrorCode indicates the type of error. The type of error may influence control flow. No other aspects of an error may influence control flow.

const (
	// An EvalError is a fatal evaluation error.
	EvalError ErrorCode = iota

	// A UserError is a fatal error originating from the user.
	UserError

	// NotExistError is used to indicate a value does not exist.
	// Mostly used for legacy reasons.
	NotExistError

	// StructuralCycleError means a structural cycle was found. Structural
	// cycles are permanent errors, but they are not passed up recursively,
	// as a unification of a value with a structural cycle with one that
	// doesn't may still give a useful result.
	StructuralCycleError

	// IncompleteError means an evaluation could not complete because of
	// insufficient information that may still be added later.
	IncompleteError

	// A CycleError indicates a reference error. It is considered to be
	// an incomplete error, as reference errors may be broken by providing
	// a concrete value.
	CycleError
)

func (ErrorCode) String

func (c ErrorCode) String() string

type Evaluator

type Evaluator interface {
	Node
	// contains filtered or unexported methods
}

An Evaluator provides a method to convert to a value.

type Expr

type Expr interface {
	Elem
	// contains filtered or unexported methods
}

An Expr corresponds to an ast.Expr.

All Expr values can be used as an Elem or Decl.

type Feature

type Feature uint32

A Feature is an encoded form of a label which comprises a compact representation of an integer or string label as well as a label type.

const InvalidLabel Feature = 0x7 // 0xb111

InvalidLabel is an encoding of an erroneous label.

func MakeIdentLabel

func MakeIdentLabel(r StringIndexer, s string) Feature

MakeIdentLabel creates a label for the given identifier.

func MakeLabel

func MakeLabel(src ast.Node, index int64, f FeatureType) (Feature, errors.Error)

MakeLabel creates a label. It reports an error if the index is out of range.

func MakeStringLabel

func MakeStringLabel(r StringIndexer, s string) Feature

MakeStringLabel creates a label for the given string.

func (Feature) Index

func (f Feature) Index() int

Index reports the abstract index associated with f.

func (Feature) IsDef

func (f Feature) IsDef() bool

IsDef reports whether the label is a definition (an identifier starting with # or #_.

func (Feature) IsHidden

func (f Feature) IsHidden() bool

IsHidden reports whether this label is hidden (an identifier starting with _ or #_).

func (Feature) IsInt

func (f Feature) IsInt() bool

IsInt reports whether this is an integer index.

func (Feature) IsRegular

func (f Feature) IsRegular() bool

IsRegular reports whether a label represents a data field.

func (Feature) IsString

func (f Feature) IsString() bool

IsString reports whether a label represents a regular field.

func (Feature) IsValid

func (f Feature) IsValid() bool

IsValid reports whether f is a valid label.

func (Feature) SelectorString

func (f Feature) SelectorString(index StringIndexer) string

SelectorString reports the shortest string representation of f when used as a selector.

func (Feature) StringValue

func (f Feature) StringValue(index StringIndexer) string

StringValue reports the string value of f, which must be a string label.

func (Feature) ToValue

func (f Feature) ToValue(ctx *OpContext) Value

ToValue converts a label to a value, which will be a Num for integer labels and a String for string labels. It panics when f is not a regular label.

func (Feature) Typ

func (f Feature) Typ() FeatureType

Typ reports the type of label.

type FeatureType

type FeatureType int8

A FeatureType indicates the type of label.

const (
	StringLabel           FeatureType = 0 // 0b000
	IntLabel              FeatureType = 1 // 0b001
	DefinitionLabel       FeatureType = 3 // 0b011
	HiddenLabel           FeatureType = 6 // 0b110
	HiddenDefinitionLabel FeatureType = 7 // 0b111

)

type Field

type Field struct {
	Src *ast.Field

	Label Feature
	Value Expr
}

Field represents a field with a fixed label. It can be a regular field, definition or hidden field.

foo: bar
#foo: bar
_foo: bar

Legacy:

Foo :: bar

func (*Field) Source

func (x *Field) Source() ast.Node

type FieldReference

type FieldReference struct {
	Src     *ast.Ident
	UpCount int32
	Label   Feature
}

A FieldReference represents a lexical reference to a field.

a

func (*FieldReference) Source

func (x *FieldReference) Source() ast.Node

type ForClause

type ForClause struct {
	Syntax *ast.ForClause
	Key    Feature
	Value  Feature
	Src    Expr
	Dst    Yielder
}

A ForClause represents a for clause of a comprehension. It can be used as a struct or list element.

for k, v in src {}

func (*ForClause) Source

func (x *ForClause) Source() ast.Node

type ID

type ID int32

type IfClause

type IfClause struct {
	Src       *ast.IfClause
	Condition Expr
	Dst       Yielder
}

An IfClause represents an if clause of a comprehension. It can be used as a struct or list element.

if cond {}

func (*IfClause) Source

func (x *IfClause) Source() ast.Node

type ImportReference

type ImportReference struct {
	Src        *ast.Ident
	ImportPath Feature
	Label      Feature // for informative purposes
}

An ImportReference refers to an imported package.

import "strings"

strings.ToLower("Upper")

func (*ImportReference) Source

func (x *ImportReference) Source() ast.Node

type IndexExpr

type IndexExpr struct {
	Src   *ast.IndexExpr
	X     Expr
	Index Expr
}

IndexExpr is like a selector, but selects an index.

X[Index]

func (*IndexExpr) Source

func (x *IndexExpr) Source() ast.Node

type Interpolation

type Interpolation struct {
	Src   *ast.Interpolation
	K     Kind   // string or bytes
	Parts []Expr // odd: strings, even sources
}

An Interpolation is a string interpolation.

"a \(b) c"

func (*Interpolation) Source

func (x *Interpolation) Source() ast.Node

type Kind

type Kind uint16

Kind reports the Value kind.

const (
	NullKind Kind = (1 << iota)
	BoolKind
	IntKind
	FloatKind
	StringKind
	BytesKind
	ListKind
	StructKind

	NumberKind = IntKind | FloatKind

	BottomKind Kind = 0

	NumKind          = IntKind | FloatKind
	TopKind     Kind = (allKinds - 1) // all kinds, but not references
	ScalarKinds      = NullKind | BoolKind |
		IntKind | FloatKind | StringKind | BytesKind
)

func (Kind) CanString

func (k Kind) CanString() bool

CanString reports whether the given type can convert to a string.

func (Kind) IsAnyOf

func (k Kind) IsAnyOf(of Kind) bool

IsAnyOf reports whether k is any of the given kinds.

For instances, k.IsAnyOf(String|Bytes) reports whether k overlaps with the String or Bytes kind.

func (Kind) String

func (k Kind) String() string

String returns the representation of the Kind as a CUE expression. For example:

(IntKind|ListKind).String()

will return:

(int|[...])

func (Kind) TypeString

func (k Kind) TypeString() string

TypeString is like String, but returns a string representation of a valid CUE type.

type LabelReference

type LabelReference struct {
	Src     *ast.Ident
	UpCount int32
}

A LabelReference refers to the string or integer value of a label.

[X=Pattern]: b: X

func (*LabelReference) Source

func (x *LabelReference) Source() ast.Node

type LetClause

type LetClause struct {
	Src   *ast.LetClause
	Label Feature
	Expr  Expr
	Dst   Yielder
}

An LetClause represents a let clause in a comprehension.

for k, v in src {}

func (*LetClause) Source

func (x *LetClause) Source() ast.Node

type LetReference

type LetReference struct {
	Src     *ast.Ident
	UpCount int32
	Label   Feature // for informative purposes
	X       Expr
}

A LetReference evaluates a let expression in its original environment.

let X = x

func (*LetReference) Source

func (x *LetReference) Source() ast.Node

type ListLit

type ListLit struct {
	Src *ast.ListLit

	// scalars, comprehensions, ...T
	Elems []Elem
}

A ListLit represents an unevaluated list literal.

[a, for x in src { ... }, b, ...T]

func (*ListLit) Source

func (x *ListLit) Source() ast.Node

type ListMarker

type ListMarker struct {
	Src    ast.Node
	IsOpen bool
}

func (*ListMarker) Concreteness

func (x *ListMarker) Concreteness() Concreteness

func (*ListMarker) Kind

func (x *ListMarker) Kind() Kind

func (*ListMarker) Source

func (x *ListMarker) Source() ast.Node

type Node

type Node interface {
	Source() ast.Node
	// contains filtered or unexported methods
}

A Node is any abstract data type representing an value or expression.

type NodeLink struct {
	Node *Vertex
}

A NodeLink is used during computation to refer to an existing Vertex. It is used to signal a potential cycle or reference. Note that a NodeLink may be used as a value. This should be taken into account.

func (*NodeLink) Concreteness

func (x *NodeLink) Concreteness() Concreteness

func (*NodeLink) Kind

func (x *NodeLink) Kind() Kind

func (*NodeLink) Source

func (x *NodeLink) Source() ast.Node

type Null

type Null struct {
	Src ast.Node
}

Null represents null. It can be used as a Value and Expr.

func (*Null) Concreteness

func (*Null) Concreteness() Concreteness

func (*Null) Kind

func (x *Null) Kind() Kind

func (*Null) Source

func (x *Null) Source() ast.Node

type Num

type Num struct {
	Src ast.Node
	K   Kind        // needed?
	X   apd.Decimal // Is integer if the apd.Decimal is an integer.
}

Num is a numeric value. It can be used as a Value and Expr.

func (*Num) Concreteness

func (*Num) Concreteness() Concreteness

func (*Num) Kind

func (x *Num) Kind() Kind

func (*Num) Source

func (x *Num) Source() ast.Node

type Op

type Op int

Op indicates the operation at the top of an expression tree of the expression use to evaluate a value.

const (
	NoOp Op = iota

	AndOp
	OrOp

	SelectorOp
	IndexOp
	SliceOp
	CallOp

	BoolAndOp
	BoolOrOp

	EqualOp
	NotOp
	NotEqualOp
	LessThanOp
	LessEqualOp
	GreaterThanOp
	GreaterEqualOp

	MatchOp
	NotMatchOp

	AddOp
	SubtractOp
	MultiplyOp
	FloatQuotientOp
	IntQuotientOp
	IntRemainderOp
	IntDivideOp
	IntModuloOp

	InterpolationOp
)

Values of Op.

func OpFromToken

func OpFromToken(t token.Token) Op

OpFromToken converts a token.Token to an Op.

func (Op) String

func (o Op) String() string

func (Op) Token

func (op Op) Token() token.Token

Token returns the token.Token corresponding to the Op.

type OpContext

type OpContext struct {
	// contains filtered or unexported fields
}

An OpContext associates a Runtime and Unifier to allow evaluating the types defined in this package. It tracks errors provides convenience methods for evaluating values.

func New

func New(v *Vertex, cfg *Config) *OpContext

New creates an operation context.

func NewContext

func NewContext(r Runtime, u Unifier, v *Vertex) *OpContext

NewContext creates an operation context.

func (*OpContext) AddBottom

func (c *OpContext) AddBottom(b *Bottom)

AddBottom records an error in OpContext.

func (*OpContext) AddErr

func (c *OpContext) AddErr(err errors.Error) *Bottom

AddErr records an error in OpContext. It returns errors collected so far.

func (*OpContext) AddErrf

func (c *OpContext) AddErrf(format string, args ...interface{}) *Bottom

AddErrf records an error in OpContext. It returns errors collected so far.

func (*OpContext) AddPosition

func (c *OpContext) AddPosition(n Node)

func (*OpContext) BoolValue

func (c *OpContext) BoolValue(v Value) bool

func (*OpContext) Concrete

func (c *OpContext) Concrete(env *Environment, x Expr, msg interface{}) (result Value, complete bool)

Concrete returns the concrete value of x after evaluating it. msg is used to mention the context in which an error occurred, if any.

func (*OpContext) Elems

func (c *OpContext) Elems(v Value) []*Vertex

Elems returns the elements of a list.

func (*OpContext) Env

func (c *OpContext) Env(upCount int32) *Environment

func (*OpContext) Err

func (c *OpContext) Err() *Bottom

func (*OpContext) Evaluate

func (c *OpContext) Evaluate(env *Environment, x Expr) (result Value, complete bool)

Evaluate evaluates an expression within the given environment and indicates whether the result is complete. It will always return a non-nil result.

func (*OpContext) HasErr

func (c *OpContext) HasErr() bool

HasErr reports whether any error was reported, including whether value was incomplete.

func (*OpContext) Impl

func (c *OpContext) Impl() Runtime

Impl is for internal use only. This will go.

func (*OpContext) Int64

func (c *OpContext) Int64(v Value) int64

func (*OpContext) IsTentative

func (c *OpContext) IsTentative() bool

If IsTentative is set, evaluation of an arc should not finalize to non-concrete values.

func (*OpContext) Label

func (c *OpContext) Label(x Value) Feature

func (*OpContext) MarkPositions

func (c *OpContext) MarkPositions() int

MarkPositions marks the current position stack.

func (*OpContext) NewErrf

func (c *OpContext) NewErrf(format string, args ...interface{}) *Bottom

NewErrf creates a *Bottom value and returns it. The returned uses the current source as the point of origin of the error.

func (*OpContext) NewInt64

func (c *OpContext) NewInt64(n int64, sources ...Node) Value

func (*OpContext) NewList

func (c *OpContext) NewList(values ...Value) *Vertex

NewList returns a new list for the given values.

func (*OpContext) NewPosf

func (c *OpContext) NewPosf(p token.Pos, format string, args ...interface{}) *ValueError

func (*OpContext) NewString

func (c *OpContext) NewString(s string) Value

func (*OpContext) Newf

func (c *OpContext) Newf(format string, args ...interface{}) *ValueError

func (*OpContext) PopArc

func (c *OpContext) PopArc(saved *Vertex)

PopArc signals completion of processing the current arc.

func (*OpContext) PopState

func (c *OpContext) PopState(s frame) *Bottom

func (*OpContext) Pos

func (c *OpContext) Pos() token.Pos

func (*OpContext) PushArc

func (c *OpContext) PushArc(v *Vertex) (saved *Vertex)

PushArc signals c that arc v is currently being processed for the purpose of error reporting. PopArc should be called with the returned value once processing of v is completed.

func (*OpContext) PushState

func (c *OpContext) PushState(env *Environment, src ast.Node) (saved frame)

func (*OpContext) ReleasePositions

func (c *OpContext) ReleasePositions(p int)

ReleasePositions sets the position state to one from a call to MarkPositions.

func (*OpContext) Resolve

func (c *OpContext) Resolve(env *Environment, r Resolver) (*Vertex, *Bottom)

Resolve finds a node in the tree.

Should only be used to insert Conjuncts. TODO: perhaps only return Conjuncts and error.

func (*OpContext) Source

func (c *OpContext) Source() ast.Node

func (*OpContext) Str

func (c *OpContext) Str(x Node) string

Str reports a debug string of x.

func (*OpContext) StringLabel

func (c *OpContext) StringLabel(s string) Feature

StringLabel converts s to a string label.

func (*OpContext) StringValue

func (c *OpContext) StringValue(v Value) string

func (*OpContext) ToBytes

func (c *OpContext) ToBytes(v Value) []byte

ToBytes returns the bytes value of a scalar value.

func (*OpContext) ToString

func (c *OpContext) ToString(v Value) string

ToString returns the string value of a scalar value.

func (*OpContext) Validate

func (c *OpContext) Validate(check Validator, value Value) *Bottom

Validate calls validates value for the given validator.

TODO(errors): return boolean instead: only the caller has enough information to generate a proper error message.

func (*OpContext) Yield

func (c *OpContext) Yield(env *Environment, y Yielder, f YieldFunc) *Bottom

Yield evaluates a Yielder and calls f for each result.

type OptionalField

type OptionalField struct {
	Src   *ast.Field
	Label Feature
	Value Expr
}

An OptionalField represents an optional regular field.

foo?: expr

func (*OptionalField) Source

func (x *OptionalField) Source() ast.Node

type OptionalType

type OptionalType int

OptionalType is a bit field of the type of optional constraints in use by an Acceptor.

const (
	HasField      OptionalType = 1 << iota // X: T
	HasDynamic                             // (X): T or "\(X)": T
	HasPattern                             // [X]: T
	HasAdditional                          // ...T
	IsOpen                                 // Defined for all fields
)

type Resolver

type Resolver interface {
	Node
	// contains filtered or unexported methods
}

A Resolver represents a reference somewhere else within a tree that resolves a value.

type Runtime

type Runtime interface {
	// StringIndexer allows for converting string labels to and from a
	// canonical numeric representation.
	StringIndexer

	// LoadImport loads a unique Vertex associated with a given import path. It
	// returns an error if no import for this package could be found.
	LoadImport(importPath string) (*Vertex, errors.Error)

	// StoreType associates a CUE expression with a Go type.
	StoreType(t reflect.Type, src ast.Expr, expr Expr)

	// LoadType retrieves a previously stored CUE expression for a given Go
	// type if available.
	LoadType(t reflect.Type) (src ast.Expr, expr Expr, ok bool)
}

Runtime defines an interface for low-level representation conversion and lookup.

type SelectorExpr

type SelectorExpr struct {
	Src *ast.SelectorExpr
	X   Expr
	Sel Feature
}

A SelectorExpr looks up a fixed field in an expression.

X.Sel

func (*SelectorExpr) Source

func (x *SelectorExpr) Source() ast.Node

type SliceExpr

type SliceExpr struct {
	Src    *ast.SliceExpr
	X      Expr
	Lo     Expr
	Hi     Expr
	Stride Expr
}

A SliceExpr represents a slice operation. (Not currently in spec.)

X[Lo:Hi:Stride]

func (*SliceExpr) Source

func (x *SliceExpr) Source() ast.Node

type String

type String struct {
	Src ast.Node
	Str string
	RE  *regexp.Regexp // only set if needed
}

String is a string value. It can be used as a Value and Expr.

func (*String) Concreteness

func (*String) Concreteness() Concreteness

func (*String) Kind

func (x *String) Kind() Kind

func (*String) Source

func (x *String) Source() ast.Node

type StringIndexer

type StringIndexer interface {
	// ToIndex returns a unique positive index for s (0 < index < 2^28-1).
	//
	// For each pair of strings s and t it must return the same index if and
	// only if s == t.
	StringToIndex(s string) (index int64)

	// ToString returns a string s for index such that ToIndex(s) == index.
	IndexToString(index int64) string
}

A StringIndexer coverts strings to and from an index that is unique for a given string.

type StructLit

type StructLit struct {
	Src   ast.Node // ast.File or ast.StructLit
	Decls []Decl
}

A StructLit represents an unevaluated struct literal or file body.

func (*StructLit) Source

func (x *StructLit) Source() ast.Node

type StructMarker

type StructMarker struct {
	// NeedClose is used to signal that the evaluator should close this struct.
	// It is only set by the close builtin.
	NeedClose bool
}

func (*StructMarker) Concreteness

func (x *StructMarker) Concreteness() Concreteness

func (*StructMarker) Kind

func (x *StructMarker) Kind() Kind

func (*StructMarker) Source

func (x *StructMarker) Source() ast.Node

type Top

type Top struct{ Src *ast.Ident }

Top represents all possible values. It can be used as a Value and Expr.

func (*Top) Concreteness

func (*Top) Concreteness() Concreteness

func (*Top) Kind

func (x *Top) Kind() Kind

func (*Top) Source

func (x *Top) Source() ast.Node

type UnaryExpr

type UnaryExpr struct {
	Src *ast.UnaryExpr
	Op  Op
	X   Expr
}

UnaryExpr is a unary expression.

Op X
-X !X +X

func (*UnaryExpr) Source

func (x *UnaryExpr) Source() ast.Node

type Unifier

type Unifier interface {
	// Unify fully unifies all values of a Vertex to completion and stores
	// the result in the Vertex. If Unify was called on v before it returns
	// the cached results.
	Unify(c *OpContext, v *Vertex, state VertexStatus) // error or bool?

	// Evaluate returns the evaluated value associated with v. It may return a
	// partial result. That is, if v was not yet unified, it may return a
	// concrete value that must be the result assuming the configuration has no
	// errors.
	//
	// This semantics allows CUE to break reference cycles in a straightforward
	// manner.
	//
	// Vertex v must still be evaluated at some point to catch the underlying
	// error.
	//
	Evaluate(c *OpContext, v *Vertex) Value
}

A Unifier implements a strategy for CUE's unification operation. It must handle the following aspects of CUE evaluation:

  • Structural and reference cycles
  • Non-monotic validation
  • Fixed-point computation of comprehension

type Validator

type Validator interface {
	Value
	// contains filtered or unexported methods
}

A Validator validates a Value. All Validators are Values.

func SimplifyValidator

func SimplifyValidator(ctx *OpContext, v, w Validator) Validator

SimplifyValidator simplifies non-bound validators.

Currently this only checks for pure equality. In the future this can be used to simplify certain builtin validators analogously to how we simplify bounds now.

type Value

type Value interface {
	Expr
	Concreteness() Concreteness
	Kind() Kind
}

A Value represents a node in the evaluated data graph.

All Values values can also be used as a Expr.

func BinOp

func BinOp(c *OpContext, op Op, left, right Value) Value

BinOp handles all operations except AndOp and OrOp. This includes processing unary comparators such as '<4' and '=~"foo"'.

BinOp returns nil if not both left and right are concrete.

func Default

func Default(v Value) Value

Default returns the default value or itself if there is no default.

func SimplifyBounds

func SimplifyBounds(ctx *OpContext, k Kind, x, y *BoundValue) Value

SimplifyBounds collapses bounds if possible. The bound values must be concrete. It returns nil if the bound values cannot be collapsed.

k represents additional type constraints, such as `int`.

func Unwrap

func Unwrap(v Value) Value

Unwrap returns the possibly non-concrete scalar value of v or nil if v is a list, struct or of undefined type.

type ValueClause

type ValueClause struct {
	*StructLit
}

A ValueClause represents the value part of a comprehension.

func (*ValueClause) Source

func (x *ValueClause) Source() ast.Node

type ValueError

type ValueError struct {
	errors.Message
	// contains filtered or unexported fields
}

A ValueError is returned as a result of evaluating a value.

func (*ValueError) AddPosition

func (v *ValueError) AddPosition(n Node)

func (*ValueError) Error

func (e *ValueError) Error() string

func (*ValueError) InputPositions

func (e *ValueError) InputPositions() (a []token.Pos)

func (*ValueError) Path

func (e *ValueError) Path() (a []string)

func (*ValueError) Position

func (e *ValueError) Position() token.Pos

type Vertex

type Vertex struct {
	// Parent links to a parent Vertex. This parent should only be used to
	// access the parent's Label field to find the relative location within a
	// tree.
	Parent *Vertex

	// Label is the feature leading to this vertex.
	Label Feature

	// EvalCount keeps track of temporary dereferencing during evaluation.
	// If EvalCount > 0, status should be considered to be EvaluatingArcs.
	EvalCount int

	// SelfCount is used for tracking self-references.
	SelfCount int

	// Value is the value associated with this vertex. For lists and structs
	// this is a sentinel value indicating its kind.
	Value Value

	// ChildErrors is the collection of all errors of children.
	ChildErrors *Bottom

	// The parent of nodes can be followed to determine the path within the
	// configuration of this node.
	// Value  Value
	Arcs []*Vertex // arcs are sorted in display order.

	// Conjuncts lists the structs that ultimately formed this Composite value.
	// This includes all selected disjuncts.
	//
	// This value may be nil, in which case the Arcs are considered to define
	// the final value of this Vertex.
	Conjuncts []Conjunct

	// Structs is a slice of struct literals that contributed to this value.
	// This information is used to compute the topological sort of arcs.
	Structs []*StructLit

	// Closed contains information about how to interpret field labels for the
	// various conjuncts with respect to which fields are allowed in this
	// Vertex. If allows all fields if it is nil.
	// The evaluator will first check existing fields before using this. So for
	// simple cases, an Acceptor can always return false to close the Vertex.
	Closed Acceptor
	// contains filtered or unexported fields
}

A Vertex is a node in the value tree. It may be a leaf or internal node. It may have arcs to represent elements of a fully evaluated struct or list.

For structs, it only contains definitions and concrete fields. optional fields are dropped.

It maintains source information such as a list of conjuncts that contributed to the value.

func Resolve

func Resolve(ctx *OpContext, c Conjunct) *Vertex

func ToVertex

func ToVertex(v Value) *Vertex

ToVertex wraps v in a new Vertex, if necessary.

func (*Vertex) Accept

func (v *Vertex) Accept(ctx *OpContext, f Feature) bool

func (*Vertex) AddChildError

func (v *Vertex) AddChildError(recursive *Bottom)

AddChildError updates x to record an error that occurred in one of its descendent arcs. The resulting error will record the worst error code of the current error or recursive error.

If x is not already an error, the value is recorded in the error for reference.

func (*Vertex) AddConjunct

func (v *Vertex) AddConjunct(c Conjunct) *Bottom

AddConjunct adds the given Conjuncts to v if it doesn't already exist.

func (*Vertex) AddErr

func (v *Vertex) AddErr(ctx *OpContext, b *Bottom)

func (*Vertex) AddStructs

func (v *Vertex) AddStructs(a ...*StructLit)

func (*Vertex) Concreteness

func (x *Vertex) Concreteness() Concreteness

func (*Vertex) Default

func (v *Vertex) Default() *Vertex

Default returns the default value or itself if there is no default.

func (*Vertex) Elems

func (v *Vertex) Elems() []*Vertex

Elems returns the regular elements of a list.

func (*Vertex) Err

func (v *Vertex) Err(c *OpContext, state VertexStatus) *Bottom

func (*Vertex) Finalize

func (v *Vertex) Finalize(c *OpContext)

func (*Vertex) GetArc

func (v *Vertex) GetArc(f Feature) (arc *Vertex, isNew bool)

GetArc returns a Vertex for the outgoing arc with label f. It creates and ads one if it doesn't yet exist.

func (*Vertex) IsClosed

func (v *Vertex) IsClosed(ctx *OpContext) bool

func (*Vertex) IsData

func (v *Vertex) IsData() bool

IsData reports whether v should be interpreted in data mode. In other words, it tells whether optional field matching and non-regular fields, like definitions and hidden fields, should be ignored.

func (*Vertex) IsErr

func (v *Vertex) IsErr() bool

func (*Vertex) IsList

func (v *Vertex) IsList() bool

func (*Vertex) Kind

func (v *Vertex) Kind() Kind

func (*Vertex) Lookup

func (v *Vertex) Lookup(f Feature) *Vertex

Lookup returns the Arc with label f if it exists or nil otherwise.

func (*Vertex) MatchAndInsert

func (v *Vertex) MatchAndInsert(ctx *OpContext, arc *Vertex)

func (*Vertex) OptionalTypes

func (v *Vertex) OptionalTypes() OptionalType

func (*Vertex) Path

func (v *Vertex) Path() []Feature

Path computes the sequence of Features leading from the root to of the instance to this Vertex.

func (*Vertex) SetValue

func (v *Vertex) SetValue(ctx *OpContext, state VertexStatus, value Value) *Bottom

func (*Vertex) Source

func (v *Vertex) Source() ast.Node

func (*Vertex) Status

func (v *Vertex) Status() VertexStatus

func (*Vertex) ToDataAll

func (v *Vertex) ToDataAll() *Vertex

ToDataAll returns a new v where v and all its descendents contain only the regular fields.

func (*Vertex) ToDataSingle

func (v *Vertex) ToDataSingle() *Vertex

ToDataSingle creates a new Vertex that represents just the regular fields of this vertex. Arcs are left untouched. It is used by cue.Eval to convert nodes to data on per-node basis.

func (*Vertex) UpdateStatus

func (v *Vertex) UpdateStatus(s VertexStatus)

type VertexStatus

type VertexStatus int8

VertexStatus indicates the evaluation progress of a Vertex.

const (
	// Unprocessed indicates a Vertex has not been processed before.
	// Value must be nil.
	Unprocessed VertexStatus = iota

	// Evaluating means that the current Vertex is being evaluated. If this is
	// encountered it indicates a reference cycle. Value must be nil.
	Evaluating

	// Partial indicates that the result was only partially evaluated. It will
	// need to be fully evaluated to get a complete results.
	//
	// TODO: this currently requires a renewed computation. Cache the
	// nodeContext to allow reusing the computations done so far.
	Partial

	// EvaluatingArcs indicates that the arcs of the Vertex are currently being
	// evaluated. If this is encountered it indicates a structural cycle.
	// Value does not have to be nil
	EvaluatingArcs

	// Finalized means that this node is fully evaluated and that the results
	// are save to use without further consideration.
	Finalized
)

type YieldFunc

type YieldFunc func(env *Environment, s *StructLit)

type Yielder

type Yielder interface {
	Node
	// contains filtered or unexported methods
}

A Yielder represents 0 or more labeled values of structs or lists.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL