ref

Documentation

Overview

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

Index

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

Types

type FieldType

type FieldType struct {
	// SupportsPresence indicates if the field having been set can be detected.
	SupportsPresence bool

	// Type of the field.
	Type *exprpb.Type
}

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 interface{}) 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.
	//
	// Used during type-checking only.
	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 *descpb.FileDescriptorProto) 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
}

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.
	ConvertToNative(typeDesc reflect.Type) (interface{}, error)

	// ConvertToType supports type conversions between 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() interface{}
}

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