Documentation
¶
Overview ¶
Package cue creates, evaluates and manipulates CUE configurations.
Index ¶
- Variables
- type Attribute
- type Instance
- func (inst *Instance) Build(p *build.Instance) *Instance
- func (inst *Instance) Doc() []*ast.CommentGroup
- func (inst *Instance) Eval(expr ast.Expr) Value
- func (inst *Instance) Fill(x interface{}, path ...string) (*Instance, error)
- func (inst *Instance) Lookup(path ...string) Value
- func (x Instance) NewInstance(p *build.Instance) *Instance
- func (inst *Instance) Value() Value
- type Iterator
- type Kind
- type Op
- type Option
- type Runtime
- type Value
- func (v Value) AppendFloat(buf []byte, fmt byte, prec int) ([]byte, error)
- func (v Value) AppendInt(buf []byte, base int) ([]byte, error)
- func (v Value) Attribute(key string) Attribute
- func (v Value) Bool() (bool, error)
- func (v Value) Bytes() ([]byte, error)
- func (v Value) Decode(x interface{}) error
- func (v Value) Default() (Value, bool)
- func (v Value) Doc() []*ast.CommentGroup
- func (v Value) Elem() (Value, bool)
- func (v Value) Err() error
- func (v Value) Eval() Value
- func (v Value) Exists() bool
- func (v Value) Expr() (Op, []Value)
- func (v Value) Fields(opts ...Option) (Iterator, error)
- func (v Value) Float64() (float64, error)
- func (v Value) Format(state fmt.State, verb rune)
- func (v Value) IncompleteKind() Kind
- func (v Value) Int(z *big.Int) (*big.Int, error)
- func (v Value) Int64() (int64, error)
- func (v Value) IsConcrete() bool
- func (v Value) IsIncomplete() bool
- func (v Value) IsValid() bool
- func (v Value) Kind() Kind
- func (v Value) Label() (string, bool)
- func (v Value) Len() Value
- func (v Value) List() (Iterator, error)
- func (v Value) Lookup(path ...string) Value
- func (v Value) MantExp(mant *big.Int) (exp int, err error)
- func (v Value) MarshalJSON() (b []byte, err error)
- func (v Value) Null() error
- func (v Value) Pos() token.Pos
- func (v Value) Reader() (io.Reader, error)
- func (v Value) Reference() (inst *Instance, path []string)
- func (v Value) References() [][]stringdeprecated
- func (v Value) Source() ast.Node
- func (v Value) Split() []Value
- func (v Value) String() (string, error)
- func (v Value) Subsumes(w Value) bool
- func (v Value) Syntax(opts ...Option) ast.Node
- func (v Value) Template() func(label string) Value
- func (v Value) Uint64() (uint64, error)
- func (v Value) Unify(w Value) Value
- func (v Value) Validate(opts ...Option) error
- func (v Value) Walk(before func(Value) bool, after func(Value))
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBelow indicates that a value was rounded down in a conversion. ErrBelow = errors.New("cue: value was rounded down") // ErrAbove indicates that a value was rounded up in a conversion. ErrAbove = errors.New("cue: value was rounded up") // ErrInfinite indicates that a value is infinite. ErrInfinite = errors.New("cue: infinite") )
Functions ¶
This section is empty.
Types ¶
type Attribute ¶
type Attribute struct {
// contains filtered or unexported fields
}
An Attribute contains meta data about a field.
func (*Attribute) Err ¶
Err returns the error associated with this Attribute or nil if this attribute is valid.
func (*Attribute) Flag ¶
Flag reports whether an entry with the given name exists at position pos or onwards or an error if the attribute is invalid or if the first pos-1 entries are not defined.
func (*Attribute) Int ¶
Int reports the integer at the given position or an error if the attribute is invalid, the position does not exist, or the value at the given position is not an integer.
type Instance ¶
type Instance struct {
ImportPath string
Dir string
Name string
Incomplete bool // true if Pkg and all its dependencies are free of errors
Err error // non-nil if the package had errors
// contains filtered or unexported fields
}
An Instance defines a single configuration based on a collection of underlying CUE files.
func Build ¶
Build creates one Instance for each build.Instance. A returned Instance may be incomplete, in which case its Err field is set.
Example:
inst := cue.Build(load.Load(args))
func Merge ¶
Merge unifies the given instances into a single one.
Errors regarding conflicts are included in the result, but not reported, so that these will only surface during manifestation. This allows non-conflicting parts to be used.
func (*Instance) Build ¶
Build creates a new instance from the build instances, allowing unbound identifier to bind to the top-level field in inst. The top-level fields in inst take precedence over predeclared identifier and builtin functions.
func (*Instance) Doc ¶
func (inst *Instance) Doc() []*ast.CommentGroup
Doc returns the package comments for this instance.
func (*Instance) Eval ¶
Eval evaluates an expression within an existing instance.
Expressions may refer to builtin packages if they can be uniquely identified.
func (*Instance) Fill ¶
Fill creates a new instance with the values of the old instance unified with the given value. It is not possible to update the emit value.
func (*Instance) Lookup ¶
Lookup reports the value starting from the top level struct (not the emitted value), or an error if the path is not found. The empty path returns the top-level configuration struct, regardless of whether an emit value was specified.
func (Instance) NewInstance ¶
NewInstance creates a new instance. Use Insert to populate the instance.
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
An Iterator iterates over values.
func (*Iterator) IsOptional ¶
IsOptional reports if a field is optional.
func (*Iterator) Label ¶
Label reports the label of the value if i iterates over struct fields and "" otherwise.
type Kind ¶
type Kind int
Kind determines the underlying type of a Value.
const ( // BottomKind is the error value. BottomKind Kind = 1 << iota // NullKind indicates a null value. NullKind // BoolKind indicates a boolean value. BoolKind // IntKind represents an integral number. IntKind // FloatKind represents a decimal float point number that cannot be // converted to an integer. The underlying number may still be integral, // but resulting from an operation that enforces the float type. FloatKind // StringKind indicates any kind of string. StringKind // BytesKind is a blob of data. BytesKind // StructKind is a kev-value map. StructKind // ListKind indicates a list of values. ListKind // NumberKind represents any kind of number. NumberKind = IntKind | FloatKind )
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 BooleanAndOp BooleanOrOp EqualOp NotOp NotEqualOp LessThanOp LessThanEqualOp GreaterThanOp GreaterThanEqualOp RegexMatchOp NotRegexMatchOp AddOp SubtractOp MultiplyOp FloatQuotientOp FloatRemainOp IntQuotientOp IntRemainderOp IntDivideOp IntModuloOp InterpolationOp )
Values of Op.
type Option ¶
type Option option
An Option defines modes of evaluation.
func All ¶
func All() Option
All indicates that all fields and values should be included in processing even if they can be elided or omitted.
func Attributes ¶
Attributes indicates that attributes should be included.
func Concrete ¶
Concrete ensures that all values are concrete.
For Validate this means it returns an error if this is not the case. In other cases a non-concrete value will be replaced with an error.
type Runtime ¶
A Runtime is used for creating CUE interpretations.
Any operation that involves two Values or Instances should originate from the same Runtime.
func (*Runtime) Build ¶
Build creates an Instance from the given build.Instance. A returned Instance may be incomplete, in which case its Err field is set.
func (*Runtime) FromExpr ¶
FromExpr creates an instance from an expression. Any references must be resolved beforehand.
func (*Runtime) Parse ¶
Parse parses a CUE source value into a CUE Instance. The source code may be provided as a string, byte slice, or io.Reader. The name is used as the file name in position information. The source may import builtin packages.
Example ¶
package main
import (
"fmt"
"cuelang.org/go/cue"
)
func main() {
const config = `
msg: "Hello \(place)!"
place: "world"
`
var r cue.Runtime
instance, err := r.Parse("test", config)
if err != nil {
// handle error
}
str, err := instance.Lookup("msg").String()
if err != nil {
// handle error
}
fmt.Println(str)
}
Output: Hello world!
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value holds any value, which may be a Boolean, Error, List, Null, Number, Struct, or String.
func (Value) AppendFloat ¶
AppendFloat appends to buf the string form of the floating-point number x. It returns an error if v is not a number.
func (Value) AppendInt ¶
AppendInt appends the string representation of x in the given base to buf and returns the extended buffer, or an error if the underlying number was not an integer.
func (Value) Attribute ¶
Attribute returns the attribute data for the given key. The returned attribute will return an error for any of its methods if there is no attribute for the requested key.
func (Value) Bytes ¶
Bytes returns a byte slice if v represents a list of bytes or an error otherwise.
func (Value) Decode ¶
Decode initializes x with Value v. If x is a struct, it will validate the constraints specified in the field tags.
func (Value) Default ¶
Default reports the default value and whether it existed. It returns the normal value if there is no default.
func (Value) Doc ¶
func (v Value) Doc() []*ast.CommentGroup
Doc returns all documentation comments associated with the field from which the current value originates.
func (Value) Eval ¶
Eval resolves the references of a value and returns the result. This method is not necessary to obtain concrete values.
func (Value) Expr ¶
Expr reports the operation of the underlying expression and the values it operates on. The returned values are appended to the given slice, which may be nil.
For unary expressions, it returns the single value of the expression.
For binary expressions it returns first the left and right value, in that order. For associative operations however, (for instance '&' and '|'), it may return more than two values, where the operation is to be applied in sequence.
For selector and index expressions it returns the subject and then the index. For selectors, the index is the string value of the identifier. For slice expressions, it returns the subject, low value, and high value, in that order.
For interpolations it returns a sequence of values to be concatenated, some of which will be literal strings and some unevaluated expressions.
A builtin call expression returns the value of the builtin followed by the args of the call.
If v is not an expression, Partial append v itself. TODO: return v if this is complete? Yes for now TODO: add values if a == nil?
func (Value) Fields ¶
Fields creates an iterator over v's fields if v is a struct or an error otherwise.
func (Value) Float64 ¶
Float64 returns the float64 value nearest to x. It reports an error if v is not a number. If x is too small to be represented by a float64 (|x| < math.SmallestNonzeroFloat64), the result is (0, ErrBelow) or (-0, ErrAbove), respectively, depending on the sign of x. If x is too large to be represented by a float64 (|x| > math.MaxFloat64), the result is (+Inf, ErrAbove) or (-Inf, ErrBelow), depending on the sign of x.
func (Value) IncompleteKind ¶
IncompleteKind returns a mask of all kinds that this value may be.
func (Value) Int ¶
Int converts the underlying integral number to an big.Int. It reports an error if the underlying value is not an integer type. If a non-nil *Int argument z is provided, Int stores the result in z instead of allocating a new Int.
func (Value) Int64 ¶
Int64 converts the underlying integral number to int64. It reports an error if the underlying value is not an integer type or cannot be represented as an int64. The result is (math.MinInt64, ErrAbove) for x < math.MinInt64, and (math.MaxInt64, ErrBelow) for x > math.MaxInt64.
func (Value) IsConcrete ¶
IsConcrete reports whether the current value is a concrete scalar value, not relying on default values, a terminal error, a list, or a struct. It does not verify that values of lists or structs are concrete themselves. To check whether there is a concrete default, use v.Default().IsConcrete().
func (Value) IsIncomplete ¶
IsIncomplete is deprecated.
It indicates that the value cannot be fully evaluated due to insufficient information.
func (Value) IsValid ¶
IsValid reports whether this value is defined and evaluates to something other than an error.
func (Value) Kind ¶
Kind returns the kind of value. It returns BottomKind for atomic values that are not concrete. For instance, it will return BottomKind for the bounds >=0.
func (Value) Label ¶
Label reports he label used to obtain this value from the enclosing struct.
TODO: get rid of this somehow. Probably by including a FieldInfo struct or the like.
func (Value) Len ¶
Len returns the number of items of the underlying value. For lists it reports the capacity of the list. For structs it indicates the number of fields, for bytes the number of bytes.
func (Value) List ¶
List creates an iterator over the values of a list or reports an error if v is not a list.
func (Value) Lookup ¶
Lookup reports the value starting from v, or an error if the path is not found. The empty path returns v itself.
Lookup cannot be used to look up hidden fields.
func (Value) MantExp ¶
MantExp breaks x into its mantissa and exponent components and returns the exponent. If a non-nil mant argument is provided its value is set to the mantissa of x. The components satisfy x == mant × 10**exp. It returns an error if v is not a number.
The components are not normalized. For instance, 2.00 is represented mant == 200 and exp == -2. Calling MantExp with a nil argument is an efficient way to get the exponent of the receiver.
func (Value) MarshalJSON ¶
MarshalJSON marshalls this value into valid JSON.
func (Value) Reader ¶
Reader returns a new Reader if v is a string or bytes type and an error otherwise.
func (Value) Reference ¶
Reference returns path from the root of the instance referred to by this value such that inst.Lookup(path) resolves to the same value, or no path if this value is not a reference,
func (Value) References
deprecated
func (Value) Source ¶
Source returns the original node for this value. The return value may not be a syntax.Expr. For instance, a struct kind may be represented by a struct literal, a field comprehension, or a file. It returns nil for computed nodes. Use Split to get all source values that apply to a field.
func (Value) Split ¶
Split returns a list of values from which v originated such that the unification of all these values equals v and for all returned values Source returns a non-nil value.
func (Value) Subsumes ¶
Subsumes reports whether w is an instance of v.
Value v and w must be obtained from the same build. TODO: remove this requirement.
func (Value) Syntax ¶
Syntax converts the possibly partially evaluated value into syntax. This can use used to print the value with package format.
func (Value) Template ¶
Template returns a function that represents the template definition for a struct in a configuration file. It returns nil if v is not a struct kind or if there is no template associated with the struct.
The returned function returns the value that would be unified with field given its name.
func (Value) Uint64 ¶
Uint64 converts the underlying integral number to uint64. It reports an error if the underlying value is not an integer type or cannot be represented as a uint64. The result is (0, ErrAbove) for x < 0, and (math.MaxUint64, ErrBelow) for x > math.MaxUint64.
func (Value) Unify ¶
Unify reports the greatest lower bound of v and w.
Value v and w must be obtained from the same build. TODO: remove this requirement.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ast declares the types used to represent syntax trees for CUE packages.
|
Package ast declares the types used to represent syntax trees for CUE packages. |
|
Package build defines data types and utilities for defining CUE configuration instances.
|
Package build defines data types and utilities for defining CUE configuration instances. |
|
Package encoding provides support for managing data format files supported by CUE.
|
Package encoding provides support for managing data format files supported by CUE. |
|
Package errors defines shared types for handling CUE errors.
|
Package errors defines shared types for handling CUE errors. |
|
Package format implements standard formatting of CUE configurations.
|
Package format implements standard formatting of CUE configurations. |
|
Package literal implements conversions to and from string representations of basic data types.
|
Package literal implements conversions to and from string representations of basic data types. |
|
Package load loads CUE instances.
|
Package load loads CUE instances. |
|
Package parser implements a parser for CUE source files.
|
Package parser implements a parser for CUE source files. |
|
Package scanner implements a scanner for CUE source text.
|
Package scanner implements a scanner for CUE source text. |
|
Package token defines constants representing the lexical tokens of the Go programming language and basic operations on tokens (printing, predicates).
|
Package token defines constants representing the lexical tokens of the Go programming language and basic operations on tokens (printing, predicates). |