Documentation
¶
Overview ¶
Package value holds the internal representation for River values. River 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 ElementError
- type Error
- type FieldError
- type MissingKeyError
- type Number
- type NumberKind
- type RawFunction
- type Type
- type TypeError
- type Unmarshaler
- 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.
River 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 {
RiverCapsule()
}
Capsule is a marker interface for Go values which forces a type to be represented as a River capsule. This is useful for types whose underlying value is not a capsule, such as:
// Secret is a secret value. It would normally be a River 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) RiverCapsule() {}
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 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 implemenations using raw River 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 a River 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 RiverType ¶
RiverType returns the River type from the Go type.
Go types map to River types using the following rules:
- Go numbers (ints, uints, floats) map to a River number
- Go strings map to a River string
- Go bools map to a River bool
- Go arrays and slices map to a River array
- Go map[string]T map to a River object
- Go structs map to a River object
- Valid Go functions map to a River function.
- Go interfaces map to a River capsule
- All other Go values map to a River capsule
Go functions are only valid for River 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 {
// UnmarshalRiver is called when decoding a value. f should be invoked to
// continue decoding with a value to decode into.
UnmarshalRiver(f func(v interface{}) error) error
}
Unmarshaler is a custom type which can be used to hook into the decoder.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value represents a River 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 a River 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 ¶ added in v0.29.0
FromRaw converts a reflect.Value into a River Value. It is useful to prevent downcasting a 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 a River 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 River 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. If panics if v is not an object.
Source Files