traits

Documentation

Overview

Package traits defines interfaces that a type may implement to participate in operator overloads and function dispatch.

Index

• Constants
• type Adder
• type Comparer
• type Container
• type Divider
• type FieldTester
• type Foldable
• type Folder
• type Indexer
• type Iterable
• type Iterator
• type Lister
• type Mapper
• type Matcher
• type Modder
• type Multiplier
• type MutableLister
• type MutableMapper
• type Negater
• type Receiver
• type Sizer
• type Subtractor
• type Zeroer

Constants

const (
	// AdderType types provide a '+' operator overload.
	AdderType = 1 << iota

	// ComparerType types support ordering comparisons '<', '<=', '>', '>='.
	ComparerType

	// ContainerType types support 'in' operations.
	ContainerType

	// DividerType types support '/' operations.
	DividerType

	// FieldTesterType types support the detection of field value presence.
	FieldTesterType

	// IndexerType types support index access with dynamic values.
	IndexerType

	// IterableType types can be iterated over in comprehensions.
	IterableType

	// IteratorType types support iterator semantics.
	IteratorType

	// MatcherType types support pattern matching via 'matches' method.
	MatcherType

	// ModderType types support modulus operations '%'
	ModderType

	// MultiplierType types support '*' operations.
	MultiplierType

	// NegatorType types support either negation via '!' or '-'
	NegatorType

	// ReceiverType types support dynamic dispatch to instance methods.
	ReceiverType

	// SizerType types support the size() method.
	SizerType

	// SubtractorType types support '-' operations.
	SubtractorType

	// FoldableType types support comprehensions v2 macros which iterate over (key, value) pairs.
	FoldableType
)

const (
	// ListerType supports a set of traits necessary for list operations.
	//
	// The ListerType is syntactic sugar and not intended to be a perfect reflection of all List operators.
	ListerType = AdderType | ContainerType | IndexerType | IterableType | SizerType

	// MapperType supports a set of traits necessary for map operations.
	//
	// The MapperType is syntactic sugar and not intended to be a perfect reflection of all Map operators.
	MapperType = ContainerType | IndexerType | IterableType | SizerType
)

Types

type Adder

type Adder interface {
	// Add returns a combination of the current value and other value.
	//
	// If the other value is an unsupported type, an error is returned.
	Add(other ref.Val) ref.Val
}

Adder interface to support '+' operator overloads.

type Comparer

type Comparer interface {
	// Compare this value to the input other value, returning an Int:
	//
	//    this < other  -> Int(-1)
	//    this == other ->  Int(0)
	//    this > other  ->  Int(1)
	//
	// If the comparison cannot be made or is not supported, an error should
	// be returned.
	Compare(other ref.Val) ref.Val
}

Comparer interface for ordering comparisons between values in order to support '<', '<=', '>=', '>' overloads.

type Container

type Container interface {
	// Contains returns true if the value exists within the object.
	Contains(value ref.Val) ref.Val
}

Container interface which permits containment tests such as 'a in b'.

type Divider

type Divider interface {
	// Divide returns the result of dividing the current value by the input
	// denominator.
	//
	// A denominator value of zero results in an error.
	Divide(denominator ref.Val) ref.Val
}

Divider interface to support '/' operator overloads.

type FieldTester

type FieldTester interface {
	// IsSet returns true if the field is defined and set to a non-default
	// value. The method will return false if defined and not set, and an error
	// if the field is not defined.
	IsSet(field ref.Val) ref.Val
}

FieldTester indicates if a defined field on an object type is set to a non-default value.

For use with the `has()` macro.

type Foldable

type Foldable interface {
	// Fold invokes the Folder.FoldEntry for all entries in the type
	Fold(Folder)
}

Foldable aggregate types support iteration over (key, value) or (index, value) pairs.

type Folder

type Folder interface {
	// FoldEntry indicates the key, value pair associated with the entry.
	// If the output is true, continue folding. Otherwise, terminate the fold.
	FoldEntry(key, val any) bool
}

Folder performs a fold on a given entry and indicates whether to continue folding.

type Indexer

type Indexer interface {
	// Get the value at the specified index or error.
	Get(index ref.Val) ref.Val
}

Indexer permits random access of elements by index 'a[b()]'.

type Iterable

type Iterable interface {
	// Iterator returns a new iterator view of the struct.
	Iterator() Iterator
}

Iterable aggregate types permit traversal over their elements.

type Iterator

type Iterator interface {
	ref.Val

	// HasNext returns true if there are unvisited elements in the Iterator.
	HasNext() ref.Val

	// Next returns the next element.
	Next() ref.Val
}

Iterator permits safe traversal over the contents of an aggregate type.

type Lister

type Lister interface {
	ref.Val
	Adder
	Container
	Indexer
	Iterable
	Sizer
}

Lister interface which aggregates the traits of a list.

type Mapper

type Mapper interface {
	ref.Val
	Container
	Indexer
	Iterable
	Sizer

	// Find returns a value, if one exists, for the input key.
	//
	// If the key is not found the function returns (nil, false).
	// If the input key is not valid for the map, or is Err or Unknown the function returns
	// (Unknown|Err, false).
	Find(key ref.Val) (ref.Val, bool)
}

Mapper interface which aggregates the traits of a maps.

type Matcher

type Matcher interface {
	// Match returns true if the pattern matches the current value.
	Match(pattern ref.Val) ref.Val
}

Matcher interface for supporting 'matches()' overloads.

type Modder

type Modder interface {
	// Modulo returns the result of taking the modulus of the current value
	// by the denominator.
	//
	// A denominator value of zero results in an error.
	Modulo(denominator ref.Val) ref.Val
}

Modder interface to support '%' operator overloads.

type Multiplier

type Multiplier interface {
	// Multiply returns the result of multiplying the current and input value.
	Multiply(other ref.Val) ref.Val
}

Multiplier interface to support '*' operator overloads.

type MutableLister

type MutableLister interface {
	Lister
	ToImmutableList() Lister
}

MutableLister interface which emits an immutable result after an intermediate computation.

Note, this interface is intended only to be used within Comprehensions where the mutable value is not directly observable within the user-authored CEL expression.

type MutableMapper

type MutableMapper interface {
	Mapper

	// Insert a key, value pair into the map, returning the map if the insert is successful
	// and an error if key already exists in the mutable map.
	Insert(k, v ref.Val) ref.Val

	// ToImmutableMap converts a mutable map into an immutable map.
	ToImmutableMap() Mapper
}

MutableMapper interface which emits an immutable result after an intermediate computation.

Note, this interface is intended only to be used within Comprehensions where the mutable value is not directly observable within the user-authored CEL expression.

type Negater

type Negater interface {
	// Negate returns the complement of the current value.
	Negate() ref.Val
}

Negater interface to support unary '-' and '!' operator overloads.

type Receiver

type Receiver interface {
	// Receive accepts a function name, overload id, and arguments and returns
	// a value.
	Receive(function string, overload string, args []ref.Val) ref.Val
}

Receiver interface for routing instance method calls within a value.

type Sizer

type Sizer interface {
	// Size returns the number of elements or length of the value.
	Size() ref.Val
}

Sizer interface for supporting 'size()' overloads.

type Subtractor

type Subtractor interface {
	// Subtract returns the result of subtracting the input from the current
	// value.
	Subtract(subtrahend ref.Val) ref.Val
}

Subtractor interface to support binary '-' operator overloads.

type Zeroer

type Zeroer interface {
	// IsZeroValue indicates whether the object is the zero value for the type.
	IsZeroValue() bool
}

Zeroer interface for testing whether a CEL value is a zero value for its type.