ref

Documentation

Overview

Package ref contains the reference interfaces used throughout the types components.

Index

• type FieldGetter
• type FieldTester
• type FieldType
• type Type
• type TypeAdapter
• type TypeProvider
• type TypeRegistry
• type Val

Types

type FieldGetter

type FieldGetter func(target any) (any, error)

FieldGetter is used to get the field value from an input object, if set.

type FieldTester

type FieldTester func(target any) bool

FieldTester is used to test field presence on an input object.

type FieldType

type FieldType struct {
	// Type of the field.
	Type *exprpb.Type

	// IsSet indicates whether the field is set on an input object.
	IsSet FieldTester

	// GetFrom retrieves the field value on the input object, if set.
	GetFrom FieldGetter
}

FieldType represents a field's type value and whether that field supports presence detection.

type Type

type Type interface {
	// HasTrait returns whether the type has a given trait associated with it.
	//
	// See common/types/traits/traits.go for a list of supported traits.
	HasTrait(trait int) bool

	// TypeName returns the qualified type name of the type.
	//
	// The type name is also used as the type's identifier name at type-check and interpretation time.
	TypeName() string
}

Type interface indicate the name of a given type.

type TypeAdapter

type TypeAdapter interface {
	// NativeToValue converts the input `value` to a CEL `ref.Val`.
	NativeToValue(value any) Val
}

TypeAdapter converts native Go values of varying type and complexity to equivalent CEL values.

type TypeProvider

type TypeProvider interface {
	// EnumValue returns the numeric value of the given enum value name.
	EnumValue(enumName string) Val

	// FindIdent takes a qualified identifier name and returns a Value if one
	// exists.
	FindIdent(identName string) (Val, bool)

	// FindType looks up the Type given a qualified typeName. Returns false
	// if not found.
	//
	// Used during type-checking only.
	FindType(typeName string) (*exprpb.Type, bool)

	// FieldFieldType returns the field type for a checked type value. Returns
	// false if the field could not be found.
	FindFieldType(messageType string, fieldName string) (*FieldType, bool)

	// NewValue creates a new type value from a qualified name and map of field
	// name to value.
	//
	// Note, for each value, the Val.ConvertToNative function will be invoked
	// to convert the Val to the field's native type. If an error occurs during
	// conversion, the NewValue will be a types.Err.
	NewValue(typeName string, fields map[string]Val) Val
}

TypeProvider specifies functions for creating new object instances and for resolving enum values by name.

type TypeRegistry

type TypeRegistry interface {
	TypeAdapter
	TypeProvider

	// RegisterDescriptor registers the contents of a protocol buffer `FileDescriptor`.
	RegisterDescriptor(fileDesc protoreflect.FileDescriptor) error

	// RegisterMessage registers a protocol buffer message and its dependencies.
	RegisterMessage(message proto.Message) error

	// RegisterType registers a type value with the provider which ensures the
	// provider is aware of how to map the type to an identifier.
	//
	// If a type is provided more than once with an alternative definition, the
	// call will result in an error.
	RegisterType(types ...Type) error

	// Copy the TypeRegistry and return a new registry whose mutable state is isolated.
	Copy() TypeRegistry
}

TypeRegistry allows third-parties to add custom types to CEL. Not all `TypeProvider` implementations support type-customization, so these features are optional. However, a `TypeRegistry` should be a `TypeProvider` and a `TypeAdapter` to ensure that types which are registered can be converted to CEL representations.

type Val

type Val interface {
	// ConvertToNative converts the Value to a native Go struct according to the
	// reflected type description, or error if the conversion is not feasible.
	//
	// The ConvertToNative method is intended to be used to support conversion between CEL types
	// and native types during object creation expressions or by clients who need to adapt the,
	// returned CEL value into an equivalent Go value instance.
	//
	// When implementing or using ConvertToNative, the following guidelines apply:
	// - Use ConvertToNative when marshalling CEL evaluation results to native types.
	// - Do not use ConvertToNative within CEL extension functions.
	// - Document whether your implementation supports non-CEL field types, such as Go or Protobuf.
	ConvertToNative(typeDesc reflect.Type) (any, error)

	// ConvertToType supports type conversions between CEL value types supported by the expression language.
	ConvertToType(typeValue Type) Val

	// Equal returns true if the `other` value has the same type and content as the implementing struct.
	Equal(other Val) Val

	// Type returns the TypeValue of the value.
	Type() Type

	// Value returns the raw value of the instance which may not be directly compatible with the expression
	// language types.
	Value() any
}

Val interface defines the functions supported by all expression values. Val implementations may specialize the behavior of the value through the addition of traits.