query

package
v3.41.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 15, 2021 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package query provides a parser for the right-hand side query part of the bloblang spec. This is useful as a separate package as it is used in isolation within interpolation functions.

Index

Constants

This section is empty.

Variables

View Source 
var AllFunctions = &FunctionSet{
	constructors: map[string]FunctionCtor{},
	specs:        []FunctionSpec{},
}

AllFunctions is a set containing every single function declared by this package, and any globally declared plugin methods.

View Source 
var AllMethods = &MethodSet{
	constructors: map[string]MethodCtor{},
	specs:        []MethodSpec{},
}

AllMethods is a set containing every single method declared by this package, and any globally declared plugin methods.

View Source 
var ErrDivideByZero = errors.New("attempted to divide by zero")

ErrDivideByZero occurs when an arithmetic operator is prevented from dividing a value by zero.

View Source 
var (
	ErrNoContext = errors.New("context was undefined")
)

Common query errors.

Functions

func ExecToBytes 

func ExecToBytes(fn Function, ctx FunctionContext) []byte

ExecToBytes returns a byte slice from a function exection.

func ExecToString 

func ExecToString(fn Function, ctx FunctionContext) string

ExecToString returns a string from a function exection.

func IClone 

func IClone(root interface{}) interface{}

IClone performs a deep copy of a generic value.

func IGetBool 

func IGetBool(v interface{}) (bool, error)

IGetBool takes a boxed value and attempts to extract a boolean from it.

func IGetBytes added in v3.40.0 

func IGetBytes(v interface{}) ([]byte, error)

IGetBytes takes a boxed value and attempts to return a byte slice value. Returns an error if the value is not a string or byte slice.

func IGetInt 

func IGetInt(v interface{}) (int64, error)

IGetInt takes a boxed value and attempts to extract an integer (int64) from it.

func IGetNumber 

func IGetNumber(v interface{}) (float64, error)

IGetNumber takes a boxed value and attempts to extract a number (float64) from it.

func IGetString 

func IGetString(v interface{}) (string, error)

IGetString takes a boxed value and attempts to return a string value. Returns an error if the value is not a string or byte slice.

func IGetTimestamp added in v3.40.0 

func IGetTimestamp(v interface{}) (time.Time, error)

IGetTimestamp takes a boxed value and attempts to coerce it into a timestamp, either by interpretting a numerical value as a unix timestamp, or by parsing a string value as RFC3339Nano.

func IIsNull 

func IIsNull(i interface{}) bool

IIsNull returns whether a bloblang type is null, this includes Delete and Nothing types.

func ISanitize 

func ISanitize(i interface{}) interface{}

ISanitize takes a boxed value of any type and attempts to convert it into one of the following types: string, []byte, int64, uint64, float64, bool, []interface{}, map[string]interface{}, Delete, Nothing.

func IToBool 

func IToBool(v interface{}) (bool, error)

IToBool takes a boxed value and attempts to extract a boolean from it or parse it into a bool.

func IToBytes 

func IToBytes(i interface{}) []byte

IToBytes takes a boxed value of any type and attempts to convert it into a byte slice.

func IToInt added in v3.30.0 

func IToInt(v interface{}) (int64, error)

IToInt takes a boxed value and attempts to extract a number (int64) from it or parse one.

func IToNumber 

func IToNumber(v interface{}) (float64, error)

IToNumber takes a boxed value and attempts to extract a number (float64) from it or parse one.

func IToString 

func IToString(i interface{}) string

IToString takes a boxed value of any type and attempts to convert it into a string.

func ListFunctions 

func ListFunctions() []string

ListFunctions returns a slice of function names, sorted alphabetically.

func ListMethods 

func ListMethods() []string

ListMethods returns a slice of method names, sorted alphabetically.

func NewArrayLiteral added in v3.25.0 

func NewArrayLiteral(values ...interface{}) interface{}

NewArrayLiteral creates an array literal from a slice of values. If all values are static then a static []interface{} value is returned. However, if any values are dynamic a Function is returned.

func NewMapLiteral added in v3.25.0 

func NewMapLiteral(values [][2]interface{}) (interface{}, error)

NewMapLiteral creates a map literal from a slice of key/value pairs. If all keys and values are static then a static map[string]interface{} value is returned. However, if any keys or values are dynamic a Function is returned.

func RegisterFunction 

func RegisterFunction(spec FunctionSpec, allowDynamicArgs bool, ctor FunctionCtor, checks ...ArgCheckFn) struct{}

RegisterFunction to be accessible from Bloblang queries. Returns an empty struct in order to allow inline calls.

func RegisterMethod 

func RegisterMethod(spec MethodSpec, allowDynamicArgs bool, ctor MethodCtor, checks ...ArgCheckFn) struct{}

RegisterMethod to be accessible from Bloblang queries. Returns an empty struct in order to allow inline calls.

Types

type ArgCheckFn 

type ArgCheckFn func(args []interface{}) error

ArgCheckFn is an optional argument type checker for a function constructor.

func ExpectAllStringArgs 

func ExpectAllStringArgs() ArgCheckFn

ExpectAllStringArgs returns an error if any argument is not a string type (or a byte slice that can be converted).

func ExpectAtLeastOneArg 

func ExpectAtLeastOneArg() ArgCheckFn

ExpectAtLeastOneArg returns an error unless >0 arguments are specified.

func ExpectBetweenNAndMArgs added in v3.27.0 

func ExpectBetweenNAndMArgs(n, m int) ArgCheckFn

ExpectBetweenNAndMArgs returns an error unless between N and M arguments are specified.

func ExpectBoolArg 

func ExpectBoolArg(i int) ArgCheckFn

ExpectBoolArg returns an error if an argument i is not a boolean type.

func ExpectFloatArg 

func ExpectFloatArg(i int) ArgCheckFn

ExpectFloatArg returns an error if an argument i is not a float type.

func ExpectFunctionArg added in v3.32.0 

func ExpectFunctionArg(i int) ArgCheckFn

ExpectFunctionArg ensures that parameters are query functions. If the argument is a static value it will be converted into a literal function.

func ExpectIntArg 

func ExpectIntArg(i int) ArgCheckFn

ExpectIntArg returns an error if an argument i is not an integer type.

func ExpectNArgs 

func ExpectNArgs(i int) ArgCheckFn

ExpectNArgs returns an error unless exactly N arguments are specified.

func ExpectOneOrZeroArgs 

func ExpectOneOrZeroArgs() ArgCheckFn

ExpectOneOrZeroArgs returns an error if more than one arg is specified.

func ExpectStringArg 

func ExpectStringArg(i int) ArgCheckFn

ExpectStringArg returns an error if an argument i is not a string type (or a byte slice that can be converted).

type ArithmeticOperator added in v3.25.0 

type ArithmeticOperator int

ArithmeticOperator represents an arithmetic operation that combines the results of two query functions. 

const (
	ArithmeticAdd ArithmeticOperator = iota
	ArithmeticSub
	ArithmeticDiv
	ArithmeticMul
	ArithmeticMod
	ArithmeticEq
	ArithmeticNeq
	ArithmeticGt
	ArithmeticLt
	ArithmeticGte
	ArithmeticLte
	ArithmeticAnd
	ArithmeticOr
	ArithmeticPipe
)

All arithmetic operators.

type Delete 

type Delete *struct{}

Delete is a special type that serializes to `null` when forced but indicates a target should be deleted.

type ErrRecoverable 

type ErrRecoverable struct {
	Recovered interface{}
	Err       error
}

ErrRecoverable represents a function execution error that can optionally be recovered into a zero-value.

func (*ErrRecoverable) Error 

func (e *ErrRecoverable) Error() string

Error implements the standard error interface.

func (*ErrRecoverable) Unwrap added in v3.25.0 

func (e *ErrRecoverable) Unwrap() error

Unwrap the error.

type ExampleSpec added in v3.26.0 

type ExampleSpec struct {
	Mapping string
	Summary string
	Results [][2]string
}

ExampleSpec provides a mapping example and some input/output results to display.

func NewExampleSpec added in v3.26.0 

func NewExampleSpec(summary, mapping string, results ...string) ExampleSpec

NewExampleSpec creates a new example spec.

type Function 

type Function interface {
	// Execute this function for a message of a batch.
	Exec(ctx FunctionContext) (interface{}, error)

	// Return a map of target types to path segments for any targets that this
	// query function references.
	QueryTargets(ctx TargetsContext) []TargetPath
}

Function takes a set of contextual arguments and returns the result of the query.

func ClosureFunction added in v3.25.0 

func ClosureFunction(
	exec func(ctx FunctionContext) (interface{}, error),
	queryTargets func(ctx TargetsContext) []TargetPath,
) Function

ClosureFunction allows you to define a Function using closures, this is a convenient constructor for function implementations that don't manage complex state.

func DeprecatedFunction added in v3.25.0 

func DeprecatedFunction(name, arg string) (Function, bool)

DeprecatedFunction attempts to initialize a (now deprecated) old-syntax function.

func InitFunction added in v3.25.0 

func InitFunction(name string, args ...interface{}) (Function, error)

InitFunction attempts to initialise a function by its name and arguments.

func InitMethod added in v3.25.0 

func InitMethod(name string, target Function, args ...interface{}) (Function, error)

InitMethod attempts to initialise a method by its name, target function and arguments.

func NewArithmeticExpression added in v3.25.0 

func NewArithmeticExpression(fns []Function, ops []ArithmeticOperator) (Function, error)

NewArithmeticExpression creates a single query function from a list of child functions and the arithmetic operator types that chain them together. The length of functions must be exactly one fewer than the length of operators.

func NewFieldFunction added in v3.25.0 

func NewFieldFunction(pathStr string) Function

NewFieldFunction creates a query function that returns a path from a JSON input document.

func NewGetMethod added in v3.25.0 

func NewGetMethod(target Function, path string) (Function, error)

NewGetMethod creates a new get method.

func NewIfFunction added in v3.25.0 

func NewIfFunction(queryFn Function, ifFn Function, elseFn Function) Function

NewIfFunction creates a logical if expression from a query which should return a boolean value. If the returned boolean is true then the ifFn is executed and returned, otherwise elseFn is executed and returned.

func NewMapMethod added in v3.25.0 

func NewMapMethod(target, mapArg Function) (Function, error)

NewMapMethod attempts to create a map method.

func NewMatchFunction added in v3.25.0 

func NewMatchFunction(contextFn Function, cases ...MatchCase) Function

NewMatchFunction takes a contextual mapping and a list of MatchCases, when the function is executed

func NewVarFunction added in v3.25.0 

func NewVarFunction(path string) Function

NewVarFunction creates a new variable function.

func Not added in v3.25.0 

func Not(fn Function) Function

Not returns a logical NOT of a child function.

type FunctionCategory added in v3.26.0 

type FunctionCategory string

FunctionCategory is an abstract title for functions of a similar purpose. 

var (
	FunctionCategoryGeneral     FunctionCategory = "General"
	FunctionCategoryMessage     FunctionCategory = "Message Info"
	FunctionCategoryEnvironment FunctionCategory = "Environment"
	FunctionCategoryDeprecated  FunctionCategory = "Deprecated"
	FunctionCategoryPlugin      FunctionCategory = "Plugin"
)

Function categories.

type FunctionContext 

type FunctionContext struct {
	Maps     map[string]Function
	Vars     map[string]interface{}
	Index    int
	MsgBatch MessageBatch
	Legacy   bool
	// contains filtered or unexported fields
}

FunctionContext provides access to a range of query targets for functions to reference.

func (FunctionContext) Value 

func (ctx FunctionContext) Value() *interface{}

Value returns a lazily evaluated context value. A context value is not always available and can therefore be nil.

func (FunctionContext) WithValue added in v3.28.0 

func (ctx FunctionContext) WithValue(v interface{}) FunctionContext

WithValue returns a function context with a new value.

func (FunctionContext) WithValueFunc added in v3.33.0 

func (ctx FunctionContext) WithValueFunc(fn func() *interface{}) FunctionContext

WithValueFunc returns a function context with a new value func.

type FunctionCtor 

type FunctionCtor func(args ...interface{}) (Function, error)

FunctionCtor constructs a new function from input arguments.

type FunctionSet added in v3.39.0 

type FunctionSet struct {
	// contains filtered or unexported fields
}

FunctionSet contains an explicit set of functions to be available in a Bloblang query.

func (*FunctionSet) Add added in v3.39.0 

func (f *FunctionSet) Add(spec FunctionSpec, ctor FunctionCtor, allowDynamicArgs bool, checks ...ArgCheckFn) error

Add a new function to this set by providing a spec (name and documentation), a constructor to be called for each instantiation of the function, and information regarding the arguments of the function.

func (*FunctionSet) Docs added in v3.39.0 

func (f *FunctionSet) Docs() []FunctionSpec

Docs returns a slice of function specs, which document each function.

func (*FunctionSet) Init added in v3.39.0 

func (f *FunctionSet) Init(name string, args ...interface{}) (Function, error)

Init attempts to initialize a function of the set by name and zero or more arguments.

func (*FunctionSet) List added in v3.39.0 

func (f *FunctionSet) List() []string

List returns a slice of function names in alphabetical order.

func (*FunctionSet) Without added in v3.39.0 

func (f *FunctionSet) Without(functions ...string) *FunctionSet

Without creates a clone of the function set that can be mutated in isolation, where a variadic list of functions will be excluded from the set.

type FunctionSpec added in v3.26.0 

type FunctionSpec struct {
	// The release status of the function.
	Status Status

	// A category to place the function within.
	Category FunctionCategory

	// Name of the function (as it appears in config).
	Name string

	// Description of the functions purpose (in markdown).
	Description string

	// Examples shows general usage for the function.
	Examples []ExampleSpec
}

FunctionSpec describes a Bloblang function.

func FunctionDocs added in v3.26.0 

func FunctionDocs() []FunctionSpec

FunctionDocs returns a slice of specs, one for each function.

func NewDeprecatedFunctionSpec added in v3.26.0 

func NewDeprecatedFunctionSpec(name, description string, examples ...ExampleSpec) FunctionSpec

NewDeprecatedFunctionSpec creates a new function spec that is deprecated.

func NewFunctionSpec added in v3.26.0 

func NewFunctionSpec(category FunctionCategory, name, description string, examples ...ExampleSpec) FunctionSpec

NewFunctionSpec creates a new function spec.

func NewHiddenFunctionSpec added in v3.33.0 

func NewHiddenFunctionSpec(name string) FunctionSpec

NewHiddenFunctionSpec creates a new function spec that is hidden from the docs.

func (FunctionSpec) Beta added in v3.28.0 

func (s FunctionSpec) Beta() FunctionSpec

Beta flags the function as a beta component.

type Literal added in v3.25.0 

type Literal struct {
	Value interface{}
}

Literal wraps a static value and returns it for each invocation of the function.

func NewLiteralFunction added in v3.25.0 

func NewLiteralFunction(v interface{}) *Literal

NewLiteralFunction creates a query function that returns a static, literal value.

func (*Literal) Close added in v3.28.0 

func (l *Literal) Close(ctx context.Context) error

Close does nothing.

func (*Literal) Exec added in v3.25.0 

func (l *Literal) Exec(ctx FunctionContext) (interface{}, error)

Exec returns a literal value.

func (*Literal) QueryTargets added in v3.25.0 

func (l *Literal) QueryTargets(ctx TargetsContext) []TargetPath

QueryTargets returns nothing.

type MatchCase added in v3.25.0 

type MatchCase struct {
	// contains filtered or unexported fields
}

MatchCase represents a single match case of a match expression, where a case query is checked and, if true, the underlying query is executed and returned.

func NewMatchCase added in v3.25.0 

func NewMatchCase(caseFn, queryFn Function) MatchCase

NewMatchCase creates a single match case of a match expression, where a case query is checked and, if true, the underlying query is executed and returned.

type MessageBatch 

type MessageBatch interface {
	Get(p int) types.Part
	Len() int
}

MessageBatch is an interface type to be given to a query function, it allows the function to resolve fields and metadata from a Benthos message batch.

type MethodCatSpec added in v3.26.0 

type MethodCatSpec struct {
	Category    MethodCategory
	Description string
	Examples    []ExampleSpec
}

MethodCatSpec describes how a method behaves in the context of a given category.

type MethodCategory added in v3.26.0 

type MethodCategory string

MethodCategory is an abstract title for methods of a similar purpose. 

var (
	MethodCategoryStrings        MethodCategory = "String Manipulation"
	MethodCategoryNumbers        MethodCategory = "Number Manipulation"
	MethodCategoryTime           MethodCategory = "Timestamp Manipulation"
	MethodCategoryRegexp         MethodCategory = "Regular Expressions"
	MethodCategoryEncoding       MethodCategory = "Encoding and Encryption"
	MethodCategoryCoercion       MethodCategory = "Type Coercion"
	MethodCategoryParsing        MethodCategory = "Parsing"
	MethodCategoryObjectAndArray MethodCategory = "Object & Array Manipulation"
	MethodCategoryDeprecated     MethodCategory = "Deprecated"
	MethodCategoryPlugin         MethodCategory = "Plugin"
)

Method categories.

type MethodCtor 

type MethodCtor func(target Function, args ...interface{}) (Function, error)

MethodCtor constructs a new method from a target function and input args.

type MethodSet added in v3.39.0 

type MethodSet struct {
	// contains filtered or unexported fields
}

MethodSet contains an explicit set of methods to be available in a Bloblang query.

func (*MethodSet) Add added in v3.39.0 

func (m *MethodSet) Add(spec MethodSpec, ctor MethodCtor, allowDynamicArgs bool, checks ...ArgCheckFn) error

Add a new method to this set by providing a spec (name and documentation), a constructor to be called for each instantiation of the method, and information regarding the arguments of the method.

func (*MethodSet) Docs added in v3.39.0 

func (m *MethodSet) Docs() []MethodSpec

Docs returns a slice of method specs, which document each method.

func (*MethodSet) Init added in v3.39.0 

func (m *MethodSet) Init(name string, target Function, args ...interface{}) (Function, error)

Init attempts to initialize a method of the set by name from a target function and zero or more arguments.

func (*MethodSet) List added in v3.39.0 

func (m *MethodSet) List() []string

List returns a slice of method names in alphabetical order.

func (*MethodSet) Without added in v3.39.0 

func (m *MethodSet) Without(methods ...string) *MethodSet

Without creates a clone of the method set that can be mutated in isolation, where a variadic list of methods will be excluded from the set.

type MethodSpec added in v3.26.0 

type MethodSpec struct {
	// The release status of the function.
	Status Status

	// Name of the method (as it appears in config).
	Name string

	// Description of the method purpose (in markdown).
	Description string

	// Examples shows general usage for the method.
	Examples []ExampleSpec

	// Categories that this method fits within.
	Categories []MethodCatSpec
}

MethodSpec describes a Bloblang method.

func MethodDocs added in v3.26.0 

func MethodDocs() []MethodSpec

MethodDocs returns a slice of specs, one for each method.

func NewDeprecatedMethodSpec added in v3.26.0 

func NewDeprecatedMethodSpec(name, description string, examples ...ExampleSpec) MethodSpec

NewDeprecatedMethodSpec creates a new method spec that is deprecated. The method will not appear in docs or searches but will still be usable in mappings.

func NewHiddenMethodSpec added in v3.33.0 

func NewHiddenMethodSpec(name string) MethodSpec

NewHiddenMethodSpec creates a new method spec that is hidden from docs.

func NewMethodSpec added in v3.26.0 

func NewMethodSpec(name, description string, examples ...ExampleSpec) MethodSpec

NewMethodSpec creates a new method spec.

func (MethodSpec) Beta added in v3.28.0 

func (m MethodSpec) Beta() MethodSpec

Beta flags the function as a beta component.

func (MethodSpec) InCategory added in v3.26.0 

func (m MethodSpec) InCategory(category MethodCategory, description string, examples ...ExampleSpec) MethodSpec

InCategory describes the methods behaviour in the context of a given category, methods can belong to multiple categories. For example, the `contains` method behaves differently in the object and array category versus the strings one, but belongs in both.

type Nothing 

type Nothing *struct{}

Nothing is a special type that serializes to `null` when forced but indicates a query should be disregarded (and not mapped).

type Status added in v3.32.0 

type Status string

Status of a function or method. 

var (
	StatusStable     Status = "stable"
	StatusBeta       Status = "beta"
	StatusDeprecated Status = "deprecated"
	StatusHidden     Status = "hidden"
)

Component statuses.

type TargetPath added in v3.25.0 

type TargetPath struct {
	Type TargetType
	Path []string
}

TargetPath represents a target type and segmented path that a query function references. An empty path indicates the root of the type is targetted.

func NewTargetPath added in v3.25.0 

func NewTargetPath(t TargetType, Path ...string) TargetPath

NewTargetPath constructs a new target path from a type and zero or more path segments.

type TargetType added in v3.25.0 

type TargetType int

TargetType represents a query target type, which is a source of information that a query might require, such as metadata, structured message contents, the context, etc. 

const (
	TargetMetadata TargetType = iota
	TargetValue
	TargetVariable
)

TargetTypes

type TargetsContext added in v3.26.0 

type TargetsContext struct {
	Maps map[string]Function
}

TargetsContext provides access to a range of query targets for functions to reference when determining their targets.

type TypeError 

type TypeError struct {
	Expected []ValueType
	Actual   ValueType
	Value    interface{}
}

TypeError represents an error where a value of a type was required for a function, method or operator but instead a different type was found.

func NewTypeError 

func NewTypeError(actual interface{}, exp ...ValueType) *TypeError

NewTypeError creates a new type error.

func (*TypeError) Error 

func (t *TypeError) Error() string

Error implements the standard error interface for TypeError.

type TypeMismatch 

type TypeMismatch struct {
	Left  ValueType
	Right ValueType
}

TypeMismatch represents an error where two values should be a comparable type but are not.

func NewTypeMismatch 

func NewTypeMismatch(left, right interface{}) *TypeMismatch

NewTypeMismatch creates a new type mismatch error.

func (*TypeMismatch) Error 

func (t *TypeMismatch) Error() string

Error implements the standard error interface.

type ValueType 

type ValueType string

ValueType represents a discrete value type supported by Bloblang queries. 

var (
	ValueString  ValueType = "string"
	ValueBytes   ValueType = "bytes"
	ValueNumber  ValueType = "number"
	ValueBool    ValueType = "bool"
	ValueArray   ValueType = "array"
	ValueObject  ValueType = "object"
	ValueNull    ValueType = "null"
	ValueDelete  ValueType = "delete"
	ValueNothing ValueType = "nothing"
	ValueUnknown ValueType = "unknown"
)

ValueType variants.

func ITypeOf 

func ITypeOf(i interface{}) ValueType

ITypeOf returns the type of a boxed value as a discrete ValueType. If the type of the value is unknown then ValueUnknown is returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.