Documentation
¶
Overview ¶
Package value holds the internal representation for Alloy values. Alloy values act as a lightweight wrapper around reflect.Value.
Index ¶
- Variables
- func Decode(val Value, target interface{}) error
- func DecodeCopy(val Value, target interface{}) error
- func WalkError(err error, f func(err error)) bool
- type ArgError
- type Capsule
- type ConvertibleFromCapsule
- type ConvertibleIntoCapsule
- type Defaulter
- type ElementError
- type Error
- type FieldError
- type MissingKeyError
- type Number
- type NumberKind
- type RawFunction
- type Type
- type TypeError
- type Unmarshaler
- type Validator
- type Value
- func Array(vv ...Value) Value
- func Bool(b bool) Value
- func Encapsulate(v interface{}) Value
- func Encode(v interface{}) Value
- func Float(f float64) Value
- func FromRaw(v reflect.Value) Value
- func Func(f interface{}) Value
- func Int(i int64) Value
- func Object(m map[string]Value) Value
- func String(s string) Value
- func Uint(u uint64) Value
- func (v Value) Bool() bool
- func (v Value) Call(args ...Value) (Value, error)
- func (v Value) Describe() string
- func (v Value) Float() float64
- func (v Value) Index(i int) Value
- func (v Value) Int() int64
- func (v Value) Interface() interface{}
- func (v Value) Key(key string) (index Value, ok bool)
- func (v Value) Keys() []string
- func (v Value) Len() int
- func (v Value) Number() Number
- func (v Value) OrderedKeys() bool
- func (v Value) Reflect() reflect.Value
- func (v Value) Text() string
- func (v Value) Type() Type
- func (v Value) Uint() uint64
Constants ¶
This section is empty.
Variables ¶
var ErrNoConversion = fmt.Errorf("no custom capsule conversion available")
ErrNoConversion is returned by implementations of ConvertibleCapsule to denote that a custom conversion from or to a specific type is unavailable.
var Null = Value{}
Null is the null value.
Functions ¶
func Decode ¶
Decode assigns a Value val to a Go pointer target. Pointers will be allocated as necessary when decoding.
As a performance optimization, the underlying Go value of val will be assigned directly to target if the Go types match. This means that pointers, slices, and maps will be passed by reference. Callers should take care not to modify any Values after decoding, unless it is expected by the contract of the type (i.e., when the type exposes a goroutine-safe API). In other cases, new maps and slices will be allocated as necessary. Call DecodeCopy to make a copy of val instead.
When a direct assignment is not done, Decode first checks to see if target implements the Unmarshaler or text.Unmarshaler interface, invoking methods as appropriate. It will also use time.ParseDuration if target is *time.Duration.
Next, Decode will attempt to convert val to the type expected by target for assignment. If val or target implement ConvertibleCapsule, conversion between values will be attempted by calling ConvertFrom and ConvertInto as appropriate. If val cannot be converted, an error is returned.
Alloy null values will decode into a nil Go pointer or the zero value for the non-pointer type.
Decode will panic if target is not a pointer.
func DecodeCopy ¶
DecodeCopy is like Decode but a deep copy of val is always made.
Unlike Decode, DecodeCopy will always invoke Unmarshaler and text.Unmarshaler interfaces (if implemented by target).
Types ¶
type Capsule ¶
type Capsule interface {
AlloyCapsule()
}
Capsule is a marker interface for Go values which forces a type to be represented as an Alloy capsule. This is useful for types whose underlying value is not a capsule, such as:
// Secret is a secret value. It would normally be an Alloy string since the
// underlying Go type is string, but it's a capsule since it implements
// the Capsule interface.
type Secret string
func (s Secret) AlloyCapsule() {}
Extension interfaces are used to describe additional behaviors for Capsules. ConvertibleCapsule allows defining custom conversion rules to convert between other Go values.
type ConvertibleFromCapsule ¶
type ConvertibleFromCapsule interface {
Capsule
// ConvertFrom should modify the ConvertibleCapsule value based on the value
// of src.
//
// ConvertFrom should return ErrNoConversion if no conversion is available
// from src.
ConvertFrom(src interface{}) error
}
ConvertibleFromCapsule is a Capsule which supports custom conversion rules from any Go type which is not the same as the capsule type.
type ConvertibleIntoCapsule ¶
type ConvertibleIntoCapsule interface {
Capsule
// ConvertInto should convert its value and store it into dst. dst will be a
// pointer to a value which ConvertInto is expected to update.
//
// ConvertInto should return ErrNoConversion if no conversion into dst is
// available.
ConvertInto(dst interface{}) error
}
ConvertibleIntoCapsule is a Capsule which supports custom conversion rules into any Go type which is not the same as the capsule type.
type Defaulter ¶
type Defaulter interface {
// SetToDefault is called when evaluating a block or body to set the value
// to its defaults.
SetToDefault()
}
The Defaulter interface allows a type to implement default functionality in Alloy configuration evaluation.
Defaulter will be called only on block and body Alloy types.
When using nested blocks, the wrapping type must also implement Defaulter to propagate the defaults of the wrapped type. Otherwise, defaults used for the wrapped type become inconsistent:
- If the wrapped block is NOT defined in the Alloy config, the wrapping type's defaults are used.
- If the wrapped block IS defined in the Alloy config, the wrapped type's defaults are used.
type ElementError ¶
type ElementError struct {
Value Value // The Array value
Index int // The index of the element with the issue
Inner error // The error from the element
}
ElementError is used to report on an error inside of an array.
func (ElementError) Error ¶
func (ee ElementError) Error() string
Error returns the text of the inner error.
type Error ¶
Error is used for reporting on a value-level error. It is the most general type of error for a value.
type FieldError ¶
type FieldError struct {
Value Value // The Object value
Field string // The field name with the issue
Inner error // The error from the field
}
FieldError is used to report on an invalid field inside an object.
func (FieldError) Error ¶
func (fe FieldError) Error() string
Error returns the text of the inner error.
type MissingKeyError ¶
MissingKeyError is used for reporting that a value is missing a key.
func (MissingKeyError) Error ¶
func (mke MissingKeyError) Error() string
Error returns the string form of the MissingKeyError.
type Number ¶
type Number struct {
// contains filtered or unexported fields
}
Number is a generic representation of Go numbers. It is intended to be created on the fly for numerical operations when the real number type is not known.
type NumberKind ¶
type NumberKind uint8
NumberKind categorizes a type of Go number.
const ( // NumberKindInt represents an int-like type (e.g., int, int8, etc.). NumberKindInt NumberKind = iota // NumberKindUint represents a uint-like type (e.g., uint, uint8, etc.). NumberKindUint // NumberKindFloat represents both float32 and float64. NumberKindFloat )
type RawFunction ¶
RawFunction allows creating function implementations using raw Alloy values. This is useful for functions which wish to operate over dynamic types while avoiding decoding to interface{} for performance reasons.
The func value itself is provided as an argument so error types can be filled.
type Type ¶
type Type uint8
Type represents the type of an Alloy value loosely. For example, a Value may be TypeArray, but this does not imply anything about the type of that array's elements (all of which may be any type).
TypeCapsule is a special type which encapsulates arbitrary Go values.
const ( TypeNull Type = iota TypeNumber TypeString TypeBool TypeArray TypeObject TypeFunction TypeCapsule )
Supported Type values.
func AlloyType ¶
AlloyType returns the Alloy type from the Go type.
Go types map to Alloy types using the following rules:
- Go numbers (ints, uints, floats) map to an Alloy number.
- Go strings map to an Alloy string.
- Go bools map to an Alloy bool.
- Go arrays and slices map to an Alloy array.
- Go map[string]T map to an Alloy object.
- Go structs map to an Alloy object, provided they have at least one field with an alloy tag.
- Valid Go functions map to an Alloy function.
- Go interfaces map to an Alloy capsule.
- All other Go values map to an Alloy capsule.
Go functions are only valid for Alloy if they have one non-error return type (the first return type) and one optional error return type (the second return type). Other function types are treated as capsules.
As an exception, any type which implements the Capsule interface is forced to be a capsule.
type Unmarshaler ¶
type Unmarshaler interface {
// UnmarshalAlloy is called when decoding a value. f should be invoked to
// continue decoding with a value to decode into.
UnmarshalAlloy(f func(v interface{}) error) error
}
Unmarshaler is a custom type which can be used to hook into the decoder.
type Validator ¶
type Validator interface {
// Validate is called when evaluating a block or body to enforce the
// value is valid.
Validate() error
}
The Validator interface allows a type to implement validation functionality in Alloy evaluation.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value represents an Alloy value.
func Array ¶
Array creates an array from the given values. A copy of the vv slice is made for producing the Value.
func Encapsulate ¶
func Encapsulate(v interface{}) Value
Encapsulate creates a new Capsule value from v. Encapsulate panics if v does not map to an Alloy capsule.
func Encode ¶
func Encode(v interface{}) Value
Encode creates a new Value from v. If v is a pointer, v must be considered immutable and not change while the Value is used.
func FromRaw ¶
FromRaw converts a reflect.Value into an Alloy Value. It is useful to prevent downcasting an interface into an any.
func Func ¶
func Func(f interface{}) Value
Func makes a new function Value from f. Func panics if f does not map to an Alloy function.
func (Value) Call ¶
Call invokes a function value with the provided arguments. It panics if v is not a function. If v is a variadic function, args should be the full flat list of arguments.
An ArgError will be returned if one of the arguments is invalid. An Error will be returned if the function call returns an error or if the number of arguments doesn't match.
func (Value) Describe ¶
Describe returns a descriptive type name for the value. For capsule values, this prints the underlying Go type name. For other values, it prints the normal Alloy type.
func (Value) Index ¶
Index returns index i of the Value. Panics if the value is not an array or if it is out of bounds of the array's size.
func (Value) Interface ¶
func (v Value) Interface() interface{}
Interface returns the underlying Go value for the Value.
func (Value) Key ¶
Key returns the value for a key in v. It panics if v is not an object. ok will be false if the key did not exist in the object.
func (Value) Keys ¶
Keys returns the keys in v in unspecified order. It panics if v is not an object.
func (Value) OrderedKeys ¶
OrderedKeys reports if v represents an object with consistently ordered keys. It panics if v is not an object.
Source Files