query

package
v3.65.0 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2022 License: MIT Imports: 43 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 = NewFunctionSet()

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

View Source 
var AllMethods = NewMethodSet()

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 ErrFrom added in v3.43.1 

func ErrFrom(err error, from Function) error

ErrFrom wraps an error with the annotation of a function.

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 IGetFloat32 added in v3.64.0 

func IGetFloat32(v interface{}) (float32, error)

IGetFloat32 takes a boxed value and attempts to extract a number (float32) from it.

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 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 SliceToDotPath added in v3.43.1 

func SliceToDotPath(path ...string) string

SliceToDotPath returns a valid dot path from a slice of path segments.

Types

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.

func (ArithmeticOperator) String added in v3.43.1 

func (o ArithmeticOperator) String() string

type Delete 

type Delete *struct{}

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

type ElseIf added in v3.45.0 

type ElseIf struct {
	QueryFn Function
	MapFn   Function
}

ElseIf represents an else-if block in an if expression.

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      `json:"mapping"`
	Summary string      `json:"summary"`
	Results [][2]string `json:"results"`
}

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)

	// Annotation returns a string token to identify the function within error
	// messages. The returned token is not valid Bloblang and cannot be used to
	// recreate the function.
	Annotation() string

	// Returns a list of targets that this function attempts (or may attempt) to
	// access. A context must be provided that describes the current execution
	// context that this function will be executed upon, which is how it is able
	// to determine the full path and origin of values that it targets.
	//
	// A new context is returned which should be provided to methods that act
	// upon this function when querying their own targets.
	QueryTargets(ctx TargetsContext) (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(
	annotation string,
	exec func(ctx FunctionContext) (interface{}, error),
	queryTargets func(ctx TargetsContext) (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 InitFunctionHelper added in v3.55.0 

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

InitFunctionHelper attempts to initialise a function by its name and a list of arguments, this is convenient for writing tests.

func InitMethodHelper added in v3.55.0 

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

InitMethodHelper attempts to initialise a method by its name, target function and arguments, this is convenient for writing tests.

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 field from the current context.

func NewGetMethod added in v3.25.0 

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

NewGetMethod creates a new get method.

func NewIfFunction added in v3.25.0 

func NewIfFunction(queryFn, ifFn Function, elseIfs []ElseIf, 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, mapFn 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 NewNamedContextFieldFunction added in v3.43.0 

func NewNamedContextFieldFunction(namedContext, pathStr string) Function

NewNamedContextFieldFunction creates a query function that attempts to return a field from a named context.

func NewNamedContextFunction added in v3.43.0 

func NewNamedContextFunction(name string, fn Function) Function

NewNamedContextFunction wraps a function and ensures that when the function is executed with a new context the context is captured under a new name, with the "main" context left intact.

func NewVarFunction added in v3.25.0 

func NewVarFunction(name 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

	// Reference new message being mapped
	NewMsg types.Part
	// contains filtered or unexported fields
}

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

func (FunctionContext) IncrStackCount added in v3.45.0 

func (ctx FunctionContext) IncrStackCount() (FunctionContext, int)

IncrStackCount increases the count stored in the function context of how many maps we've entered and returns the current count. nolint:gocritic // Ignore unnamedResult false positive

func (FunctionContext) NamedValue added in v3.43.0 

func (ctx FunctionContext) NamedValue(name string) (interface{}, bool)

NamedValue returns the value of a named context if it exists.

func (FunctionContext) PopValue added in v3.43.0 

func (ctx FunctionContext) PopValue() (*interface{}, FunctionContext)

PopValue returns the current default value, and a function context with the top value removed from the context stack. If the value returned is the absolute root value function then the context returned is unchanged. If there is no current default value then a nil value is returned and the context returned is unchanged.

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) WithNamedValue added in v3.43.0 

func (ctx FunctionContext) WithNamedValue(name string, value interface{}) FunctionContext

WithNamedValue returns a FunctionContext with a named value.

func (FunctionContext) WithValue added in v3.28.0 

func (ctx FunctionContext) WithValue(value 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 *ParsedParams) (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 NewFunctionSet added in v3.52.0 

func NewFunctionSet() *FunctionSet

NewFunctionSet creates a function set without any functions in it.

func (*FunctionSet) Add added in v3.39.0 

func (f *FunctionSet) Add(spec FunctionSpec, ctor FunctionCtor) 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) Deactivated added in v3.55.0 

func (f *FunctionSet) Deactivated() *FunctionSet

Deactivated returns a version of the function set where constructors are disabled, allowing mappings to be parsed and validated but not executed.

The underlying register of functions is shared with the target set, and therefore functions added to this set will also be added to the still activated set. Use the Without method (with empty args if applicable) in order to create a deep copy of the set that is independent of the source.

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 *ParsedParams) (Function, error)

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

func (*FunctionSet) NoMessage added in v3.47.0 

func (f *FunctionSet) NoMessage() *FunctionSet

NoMessage creates a clone of the function set that can be mutated in isolation, where all message access functions are removed.

func (*FunctionSet) OnlyPure added in v3.47.0 

func (f *FunctionSet) OnlyPure() *FunctionSet

OnlyPure creates a clone of the function set that can be mutated in isolation, where all impure functions are removed.

func (*FunctionSet) Params added in v3.55.0 

func (f *FunctionSet) Params(name string) (Params, error)

Params attempts to obtain an argument specification for a given function.

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 `json:"status"`

	// A category to place the function within.
	Category FunctionCategory `json:"category"`

	// Name of the function (as it appears in config).
	Name string `json:"name"`

	// Description of the functions purpose (in markdown).
	Description string `json:"description,omitempty"`

	// Params defines the expected arguments of the function.
	Params Params `json:"params"`

	// Examples shows general usage for the function.
	Examples []ExampleSpec `json:"examples,omitempty"`

	// Impure indicates that a function accesses or interacts with the outter
	// environment, and is therefore unsafe to execute in shared environments.
	Impure bool `json:"impure"`
}

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.

func (FunctionSpec) MarkImpure added in v3.47.0 

func (s FunctionSpec) MarkImpure() FunctionSpec

MarkImpure flags the function as being impure, meaning it access or interacts with the environment.

func (FunctionSpec) Param added in v3.55.0 

func (s FunctionSpec) Param(def ParamDefinition) FunctionSpec

Param adds a parameter to the function.

type Iterable added in v3.47.0 

type Iterable interface {
	// TryIterate attempts to create an iterator that walks the function result.
	// Some functions will be unable to provide an iterator due to either the
	// context or function arguments provided, therefore it's possible that a
	// static value will be returned instead.
	TryIterate(ctx FunctionContext) (Iterator, interface{}, error)
}

Iterable is an interface implemented by Bloblang functions that are able to expose their results as an interator, allowing for more efficient chaining of array based methods.

type Iterator added in v3.47.0 

type Iterator interface {
	// Next provides the next element of the iterator, or an error. When the
	// iterator has reached the end ErrEndOfIter is returned.
	Next() (interface{}, error)

	// Len provides a static length of the iterator when possible.
	Len() (int, bool)
}

Iterator allows traversal of a Bloblang function result in iterations.

type Literal added in v3.25.0 

type Literal struct {
	Value interface{}
	// contains filtered or unexported fields
}

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

func NewLiteralFunction added in v3.25.0 

func NewLiteralFunction(annotation string, v interface{}) *Literal

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

func (*Literal) Annotation added in v3.43.1 

func (l *Literal) Annotation() string

Annotation returns a token identifier of the function.

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) (TargetsContext, []TargetPath)

QueryTargets returns nothing.

func (*Literal) String added in v3.55.0 

func (l *Literal) String() string

String returns a string representation of the literal function.

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"
	MethodCategoryGeoIP          MethodCategory = "GeoIP"
	MethodCategoryDeprecated     MethodCategory = "Deprecated"
	MethodCategoryPlugin         MethodCategory = "Plugin"
)

Method categories.

type MethodCtor 

type MethodCtor func(target Function, args *ParsedParams) (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 NewMethodSet added in v3.52.0 

func NewMethodSet() *MethodSet

NewMethodSet creates a method set without any methods in it.

func (*MethodSet) Add added in v3.39.0 

func (m *MethodSet) Add(spec MethodSpec, ctor MethodCtor) 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) Deactivated added in v3.55.0 

func (m *MethodSet) Deactivated() *MethodSet

Deactivated returns a version of the method set where constructors are disabled, allowing mappings to be parsed and validated but not executed.

The underlying register of methods is shared with the target set, and therefore methods added to this set will also be added to the still activated set. Use the Without method (with empty args if applicable) in order to create a deep copy of the set that is independent of the source.

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 *ParsedParams) (Function, error)

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

func (*MethodSet) OnlyPure added in v3.56.0 

func (m *MethodSet) OnlyPure() *MethodSet

OnlyPure creates a clone of the methods set that can be mutated in isolation, where all impure methods are removed.

func (*MethodSet) Params added in v3.55.0 

func (m *MethodSet) Params(name string) (Params, error)

Params attempts to obtain an argument specification for a given method type.

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 `json:"status"`

	// Name of the method (as it appears in config).
	Name string `json:"name"`

	// Description of the method purpose (in markdown).
	Description string `json:"description,omitempty"`

	// Params defines the expected arguments of the method.
	Params Params `json:"params"`

	// Examples shows general usage for the method.
	Examples []ExampleSpec `json:"examples,omitempty"`

	// Categories that this method fits within.
	Categories []MethodCatSpec `json:"categories,omitempty"`

	// Impure indicates that a method accesses or interacts with the outter
	// environment, and is therefore unsafe to execute in shared environments.
	Impure bool `json:"impure"`
}

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.

func (MethodSpec) MarkImpure added in v3.56.0 

func (m MethodSpec) MarkImpure() MethodSpec

MarkImpure flags the method as being impure, meaning it access or interacts with the environment.

func (MethodSpec) Param added in v3.55.0 

func (m MethodSpec) Param(def ParamDefinition) MethodSpec

Param adds a parameter to the function.

func (MethodSpec) VariadicParams added in v3.55.0 

func (m MethodSpec) VariadicParams() MethodSpec

VariadicParams configures the method spec to allow variadic parameters.

type NamedContextFunction added in v3.43.0 

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

NamedContextFunction wraps a query function in a mechanism that captures the current context under an alias.

func (*NamedContextFunction) Annotation added in v3.43.1 

func (n *NamedContextFunction) Annotation() string

Annotation returns the annotation of the underlying function.

func (*NamedContextFunction) Exec added in v3.43.0 

func (n *NamedContextFunction) Exec(ctx FunctionContext) (interface{}, error)

Exec executes the wrapped query function with the context captured under an alias.

func (*NamedContextFunction) Name added in v3.43.0 

func (n *NamedContextFunction) Name() string

Name returns the alias under which the context will be captured.

func (*NamedContextFunction) QueryTargets added in v3.43.0 

func (n *NamedContextFunction) QueryTargets(ctx TargetsContext) (TargetsContext, []TargetPath)

QueryTargets provides a summary of which fields the underlying query function targets.

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 ParamDefinition added in v3.55.0 

type ParamDefinition struct {
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	ValueType   ValueType `json:"type"`

	// IsOptional is implicit when there's a DefaultValue. However, there are
	// times when a parameter is used to change behaviour without having a
	// default.
	IsOptional   bool         `json:"is_optional,omitempty"`
	DefaultValue *interface{} `json:"default,omitempty"`
	// contains filtered or unexported fields
}

ParamDefinition describes a single parameter for a function or method.

func ParamAny added in v3.55.0 

func ParamAny(name, description string) ParamDefinition

ParamAny creates a new parameter that can be any type (excluding query).

func ParamArray added in v3.55.0 

func ParamArray(name, description string) ParamDefinition

ParamArray creates a new array typed parameter.

func ParamBool added in v3.55.0 

func ParamBool(name, description string) ParamDefinition

ParamBool creates a new bool typed parameter.

func ParamFloat added in v3.55.0 

func ParamFloat(name, description string) ParamDefinition

ParamFloat creates a new float typed parameter.

func ParamInt64 added in v3.55.0 

func ParamInt64(name, description string) ParamDefinition

ParamInt64 creates a new integer typed parameter.

func ParamObject added in v3.55.0 

func ParamObject(name, description string) ParamDefinition

ParamObject creates a new object typed parameter.

func ParamQuery added in v3.55.0 

func ParamQuery(name, description string, wrapScalars bool) ParamDefinition

ParamQuery creates a new query typed parameter. The field wrapScalars determines whether non-query arguments are allowed, in which case they will be converted into literal functions.

func ParamString added in v3.55.0 

func ParamString(name, description string) ParamDefinition

ParamString creates a new string typed parameter.

func (ParamDefinition) Default added in v3.55.0 

func (d ParamDefinition) Default(v interface{}) ParamDefinition

Default adds a default value to a parameter, also making it implicitly optional.

func (ParamDefinition) Optional added in v3.55.0 

func (d ParamDefinition) Optional() ParamDefinition

Optional marks the parameter as optional.

func (ParamDefinition) PrettyDefault added in v3.55.0 

func (d ParamDefinition) PrettyDefault() string

PrettyDefault returns a marshalled version of the parameters default value, or an empty string if there isn't one.

type Params added in v3.55.0 

type Params struct {
	Variadic    bool              `json:"variadic,omitempty"`
	Definitions []ParamDefinition `json:"named,omitempty"`
	// contains filtered or unexported fields
}

Params defines the expected arguments of a function or method.

func NewParams added in v3.55.0 

func NewParams() Params

NewParams creates a new empty parameters definition.

func VariadicParams added in v3.55.0 

func VariadicParams() Params

VariadicParams creates a new empty parameters definition where any number of nameless arguments are considered valid.

func (Params) Add added in v3.55.0 

func (p Params) Add(def ParamDefinition) Params

Add a parameter to the spec.

func (Params) PopulateNamed added in v3.55.0 

func (p Params) PopulateNamed(args map[string]interface{}) (*ParsedParams, error)

PopulateNamed returns a set of populated arguments from a map of named parameters.

func (Params) PopulateNameless added in v3.55.0 

func (p Params) PopulateNameless(args ...interface{}) (*ParsedParams, error)

PopulateNameless returns a set of populated arguments from a list of nameless parameters.

type ParsedParams added in v3.55.0 

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

ParsedParams is a reference to the arguments of a method or function instantiation.

func (*ParsedParams) Field added in v3.55.0 

func (p *ParsedParams) Field(n string) (interface{}, error)

Field returns an argument value with a given name.

func (*ParsedParams) FieldArray added in v3.55.0 

func (p *ParsedParams) FieldArray(n string) ([]interface{}, error)

FieldArray returns an array value with a given name.

func (*ParsedParams) FieldBool added in v3.55.0 

func (p *ParsedParams) FieldBool(n string) (bool, error)

FieldBool returns a bool argument value with a given name.

func (*ParsedParams) FieldFloat added in v3.55.0 

func (p *ParsedParams) FieldFloat(n string) (float64, error)

FieldFloat returns a float argument value with a given name.

func (*ParsedParams) FieldInt64 added in v3.55.0 

func (p *ParsedParams) FieldInt64(n string) (int64, error)

FieldInt64 returns an integer argument value with a given name.

func (*ParsedParams) FieldOptionalArray added in v3.55.0 

func (p *ParsedParams) FieldOptionalArray(n string) (*[]interface{}, error)

FieldOptionalArray returns an optional array value with a given name.

func (*ParsedParams) FieldOptionalBool added in v3.55.0 

func (p *ParsedParams) FieldOptionalBool(n string) (*bool, error)

FieldOptionalBool returns a bool argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) FieldOptionalFloat added in v3.55.0 

func (p *ParsedParams) FieldOptionalFloat(n string) (*float64, error)

FieldOptionalFloat returns a float argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) FieldOptionalInt64 added in v3.55.0 

func (p *ParsedParams) FieldOptionalInt64(n string) (*int64, error)

FieldOptionalInt64 returns an int argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) FieldOptionalQuery added in v3.55.0 

func (p *ParsedParams) FieldOptionalQuery(n string) (Function, error)

FieldOptionalQuery returns a query argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) FieldOptionalString added in v3.55.0 

func (p *ParsedParams) FieldOptionalString(n string) (*string, error)

FieldOptionalString returns a string argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) FieldQuery added in v3.55.0 

func (p *ParsedParams) FieldQuery(n string) (Function, error)

FieldQuery returns a query argument value with a given name.

func (*ParsedParams) FieldString added in v3.55.0 

func (p *ParsedParams) FieldString(n string) (string, error)

FieldString returns a string argument value with a given name.

func (*ParsedParams) Index added in v3.55.0 

func (p *ParsedParams) Index(i int) (interface{}, error)

Index returns an argument value at a given index.

func (*ParsedParams) Raw added in v3.55.0 

func (p *ParsedParams) Raw() []interface{}

Raw returns the arguments as a generic slice.

func (*ParsedParams) ResolveDynamic added in v3.55.0 

func (p *ParsedParams) ResolveDynamic(ctx FunctionContext) (*ParsedParams, error)

ResolveDynamic attempts to execute all dynamic arguments with a given context and populate a new parsed parameters set with the values, ready to be used in a function or method.

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
	// contains filtered or unexported fields
}

TargetsContext describes the current Bloblang execution environment from the perspective of a particular query function in a way that allows it to determine which values it is targetting and the origins of those values.

The environment consists of named maps that are globally accessible, the current value that is being executed upon by methods (when applicable), the general (main) context (referenced by the keyword `this`) and any other named contexts accessible at this point.

Since it's possible for any query function to reference and return multiple target candidates (match expressions, etc) then each context and the current value are lists of paths, each being a candidate at runtime.

func (TargetsContext) MainContext added in v3.43.0 

func (ctx TargetsContext) MainContext() []TargetPath

MainContext returns the path of the main context.

func (TargetsContext) NamedContext added in v3.43.0 

func (ctx TargetsContext) NamedContext(name string) []TargetPath

NamedContext returns the path of a named context if it exists.

func (TargetsContext) PopContext added in v3.43.0 

func (ctx TargetsContext) PopContext() TargetsContext

PopContext returns a targets context with the latest context dropped and the previous (when applicable) returned.

func (TargetsContext) Value added in v3.43.0 

func (ctx TargetsContext) Value() []TargetPath

Value returns the current value of the targets context, which is the path(s) being executed upon by methods.

func (TargetsContext) WithContextAsNamed added in v3.43.0 

func (ctx TargetsContext) WithContextAsNamed(name string) TargetsContext

WithContextAsNamed moves the latest context into a named context and returns the context prior to that one to the main context. This is a way for named context mappings to correct the contexts so that the child query function returns the right paths.

func (TargetsContext) WithValues added in v3.43.0 

func (ctx TargetsContext) WithValues(paths []TargetPath) TargetsContext

WithValues returns a targets context where the current value being executed upon by methods is set to something new.

func (TargetsContext) WithValuesAsContext added in v3.43.0 

func (ctx TargetsContext) WithValuesAsContext() TargetsContext

WithValuesAsContext returns a targets context where the current value being executed upon by methods is now the main context. This happens when a query function is executed as a method, or within branches of match expressions.

type TypeError 

type TypeError struct {
	From     string
	Expected []ValueType
	Actual   ValueType
	Value    string
}

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(value interface{}, exp ...ValueType) *TypeError

NewTypeError creates a new type error.

func NewTypeErrorFrom added in v3.43.1 

func NewTypeErrorFrom(from string, value interface{}, exp ...ValueType) *TypeError

NewTypeErrorFrom creates a new type error with an annotation of the query that provided the wrong type.

func (*TypeError) Error 

func (t *TypeError) Error() string

Error implements the standard error interface for TypeError.

type TypeMismatch 

type TypeMismatch struct {
	Lfn       Function
	Rfn       Function
	Left      ValueType
	Right     ValueType
	Operation string
}

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

func NewTypeMismatch 

func NewTypeMismatch(operation string, lfn, rfn Function, 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"
	ValueQuery   ValueType = "query expression"
	ValueUnknown ValueType = "unknown"

	// Specialised and not generally known over ValueNumber.
	ValueInt   ValueType = "integer"
	ValueFloat ValueType = "float"
)

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.