filter

Documentation

Overview

Package filter implements https://google.aip.dev/160. This is used to filter a collection using a "structured syntax accessible to a non-technical audience."

A filter expression may use a field name to be found in a struct. If there is no exact match of the field name, the filter code will look for a camel case match, in which underscores will be skipped and characters following an underscore will match case-insensitively. For example, Field_name will match FieldName. The filter code will also look for a json struct field tag, and compare against the JSON name if there is one, again doing a camel case match. This approach makes it easier to use the same filter expression across languages when filtering protobuf types. If a struct field is a pointer type, it will be dereferenced before being used in any filter comparison.

When a filter expression fails to find a field name, it will fall back to looking for an exported method with the name, again doing a camel case lookup. If there is a matching method, and the method takes no arguments and returns either a single value or a single value and an error, the filter code will call the method to get the value to search for. If the method returns an error, the value will simply be ignored; the error will not be returned or logged. If the method returns a pointer result, it will be dereferenced before being used in any filter comparison.

Index

• func Evaluator[T any](e Expr, functions Functions) (func(context.Context, T) bool, []string)
• type Expr
  • func ParseFilter(filter string) (Expr, error)
• type Functions

Functions

func Evaluator

func Evaluator[T any](e Expr, functions Functions) (func(context.Context, T) bool, []string)

Evaluator takes an Expr and an arbitrary Go type. It returns a function that takes an argument of that Go type and reports whether it matches the expression. The functions argument contains functions the filter expression may call. Evaluator also returns a list of warning messages about the expression.

Types

type Expr

type Expr interface {
	String() string // returns a multi-line string representation
	// contains filtered or unexported methods
}

Expr is the parsed AST of a filter expression.

func ParseFilter

func ParseFilter(filter string) (Expr, error)

ParseFilter parses a filter expression into an Expr. Empty input returns nil, nil. filter = [ expression ] ;

type Functions

type Functions map[string]any

Functions is a set of functions that are permitted when filtering. Each value in the map must be a function. Each function must take at least one argument, which is the type T in Evaluator[T]. The function may take other arguments, which will come from the filter expression. The function should return one or two results; the first result is the type that the function returns, and the optional second result is type error.