query

package
v4.12.0 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2023 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 (
	FunctionCategoryGeneral     = "General"
	FunctionCategoryMessage     = "Message Info"
	FunctionCategoryEnvironment = "Environment"
	FunctionCategoryDeprecated  = "Deprecated"
	FunctionCategoryPlugin      = "Plugin"
	FunctionCategoryFakeData    = "Fake Data Generation"
)

Function categories.

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

Method categories.

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.

Functions

func ErrFrom 

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, error)

ExecToBytes returns a byte slice from a function execution.

func ExecToString 

func ExecToString(fn Function, ctx FunctionContext) (string, error)

ExecToString returns a string from a function execution.

func IClone 

func IClone(root any) any

IClone performs a deep copy of a generic value.

func ICompare added in v4.1.0 

func ICompare(left, right any) bool

ICompare returns true if both the left and right are equal according to one of the following conditions:

- The types exactly match and have the same value - The types are both either a string or byte slice and the underlying data is the same - The types are both numerical and have the same value - Both types are a matching slice or map containing values matching these same conditions.

func IGetBool 

func IGetBool(v any) (bool, error)

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

func IGetBytes 

func IGetBytes(v any) ([]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 

func IGetFloat32(v any) (float32, error)

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

func IGetInt 

func IGetInt(v any) (int64, error)

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

func IGetNumber 

func IGetNumber(v any) (float64, error)

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

func IGetString 

func IGetString(v any) (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 

func IGetTimestamp(v any) (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 any) bool

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

func ISanitize 

func ISanitize(i any) any

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 any) (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 any) []byte

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

func IToInt 

func IToInt(v any) (int64, error)

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

func IToInt32 added in v4.11.0 

func IToInt32(v any) (int32, error)

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

func IToNumber 

func IToNumber(v any) (float64, error)

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

func IToString 

func IToString(i any) string

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

func IToUint added in v4.11.0 

func IToUint(v any) (uint64, error)

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

func IToUint32 added in v4.11.0 

func IToUint32(v any) (uint32, error)

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

func NewArrayLiteral 

func NewArrayLiteral(values ...any) any

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 

func NewMapLiteral(values [][2]any) (any, 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 

func SliceToDotPath(path ...string) string

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

Types

type ArithmeticOperator 

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 

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 

type ElseIf struct {
	QueryFn Function
	MapFn   Function
}

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

type ErrNoContext 

type ErrNoContext struct {
	FieldName string
}

ErrNoContext is a common query error where a query attempts to reference a structured field when there is no context.

func (ErrNoContext) Error 

func (e ErrNoContext) Error() string

Error returns an attempt at a useful error message.

type ExampleSpec 

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 

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) (any, 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 

func ClosureFunction(
	annotation string,
	exec func(ctx FunctionContext) (any, 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 InitFunctionHelper 

func InitFunctionHelper(name string, args ...any) (Function, error)

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

func InitMethodHelper 

func InitMethodHelper(name string, target Function, args ...any) (Function, error)

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

func NewArithmeticExpression 

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 

func NewFieldFunction(pathStr string) Function

NewFieldFunction creates a query function that returns a field from the current context.

func NewGetMethod 

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

NewGetMethod creates a new get method.

func NewIfFunction 

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 

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

NewMapMethod attempts to create a map method.

func NewMatchFunction 

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

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

func NewMetaFunction added in v4.11.0 

func NewMetaFunction(key string) Function

NewMetaFunction creates a new function for obtaining a metadata value.

func NewNamedContextFieldFunction 

func NewNamedContextFieldFunction(namedContext, pathStr string) Function

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

func NewNamedContextFunction 

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 NewRootFieldFunction 

func NewRootFieldFunction(pathStr string) Function

NewRootFieldFunction creates a query function that returns a field from the root context.

func NewVarFunction 

func NewVarFunction(name string) Function

NewVarFunction creates a new variable function.

func Not 

func Not(fn Function) Function

Not returns a logical NOT of a child function.

type FunctionContext 

type FunctionContext struct {
	Maps     map[string]Function
	Vars     map[string]any
	Index    int
	MsgBatch MessageBatch

	// Reference new message being mapped
	NewMeta  MetaMsg
	NewValue *any
	// contains filtered or unexported fields
}

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

func (FunctionContext) IncrStackCount 

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.

func (FunctionContext) NamedValue 

func (ctx FunctionContext) NamedValue(name string) (any, bool)

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

func (FunctionContext) PopValue 

func (ctx FunctionContext) PopValue() (*any, 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() *any

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

func (FunctionContext) WithNamedValue 

func (ctx FunctionContext) WithNamedValue(name string, value any) FunctionContext

WithNamedValue returns a FunctionContext with a named value.

func (FunctionContext) WithValue 

func (ctx FunctionContext) WithValue(value any) FunctionContext

WithValue returns a function context with a new value.

func (FunctionContext) WithValueFunc 

func (ctx FunctionContext) WithValueFunc(fn func() *any) 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 

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

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

func NewFunctionSet 

func NewFunctionSet() *FunctionSet

NewFunctionSet creates a function set without any functions in it.

func (*FunctionSet) Add 

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 

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 

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

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

func (*FunctionSet) Init 

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 

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 

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 

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

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

func (*FunctionSet) Without 

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 

type FunctionSpec struct {
	// The release status of the function.
	Status Status `json:"status"`

	// A category to place the function within.
	Category string `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 outer
	// environment, and is therefore unsafe to execute in shared environments.
	Impure bool `json:"impure"`

	// Version is the Benthos version this component was introduced.
	Version string `json:"version,omitempty"`
}

FunctionSpec describes a Bloblang function.

func FunctionDocs 

func FunctionDocs() []FunctionSpec

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

func NewDeprecatedFunctionSpec 

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

NewDeprecatedFunctionSpec creates a new function spec that is deprecated.

func NewFunctionSpec 

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

NewFunctionSpec creates a new function spec.

func NewHiddenFunctionSpec 

func NewHiddenFunctionSpec(name string) FunctionSpec

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

func (FunctionSpec) AtVersion added in v4.2.0 

func (s FunctionSpec) AtVersion(v string) FunctionSpec

AtVersion sets the Benthos version this component was introduced.

func (FunctionSpec) Beta 

func (s FunctionSpec) Beta() FunctionSpec

Beta flags the function as a beta component.

func (FunctionSpec) Experimental added in v4.2.0 

func (s FunctionSpec) Experimental() FunctionSpec

Experimental flags the function as an experimental component.

func (FunctionSpec) MarkImpure 

func (s FunctionSpec) MarkImpure() FunctionSpec

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

func (FunctionSpec) Param 

func (s FunctionSpec) Param(def ParamDefinition) FunctionSpec

Param adds a parameter to the function.

type Iterable 

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, any, 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 

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() (any, 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 

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

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

func NewLiteralFunction 

func NewLiteralFunction(annotation string, v any) *Literal

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

func (*Literal) Annotation 

func (l *Literal) Annotation() string

Annotation returns a token identifier of the function.

func (*Literal) Close 

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

Close does nothing.

func (*Literal) Exec 

func (l *Literal) Exec(ctx FunctionContext) (any, error)

Exec returns a literal value.

func (*Literal) QueryTargets 

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

QueryTargets returns nothing.

func (*Literal) String 

func (l *Literal) String() string

String returns a string representation of the literal function.

type MatchCase 

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 

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) *message.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 MetaMsg 

type MetaMsg interface {
	MetaSetMut(key string, value any)
	MetaGetStr(key string) string
	MetaGetMut(key string) (any, bool)
	MetaDelete(key string)
	MetaIterMut(f func(k string, v any) error) error
	MetaIterStr(f func(k, v string) error) error
}

MetaMsg provides access to the metadata of a message.

type MethodCatSpec 

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

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

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 

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

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

func NewMethodSet 

func NewMethodSet() *MethodSet

NewMethodSet creates a method set without any methods in it.

func (*MethodSet) Add 

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 

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 

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

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

func (*MethodSet) Init 

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 

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 

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

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

func (*MethodSet) Without 

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 

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 outer
	// environment, and is therefore unsafe to execute in shared environments.
	Impure bool `json:"impure"`

	// Version is the Benthos version this component was introduced.
	Version string `json:"version,omitempty"`
}

MethodSpec describes a Bloblang method.

func MethodDocs 

func MethodDocs() []MethodSpec

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

func NewDeprecatedMethodSpec 

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 

func NewHiddenMethodSpec(name string) MethodSpec

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

func NewMethodSpec 

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

NewMethodSpec creates a new method spec.

func (MethodSpec) AtVersion added in v4.2.0 

func (m MethodSpec) AtVersion(v string) MethodSpec

AtVersion sets the Benthos version this component was introduced.

func (MethodSpec) Beta 

func (m MethodSpec) Beta() MethodSpec

Beta flags the function as a beta component.

func (MethodSpec) Experimental added in v4.2.0 

func (m MethodSpec) Experimental() MethodSpec

Experimental flags the method as an experimental component.

func (MethodSpec) InCategory 

func (m MethodSpec) InCategory(category, 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 

func (m MethodSpec) MarkImpure() MethodSpec

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

func (MethodSpec) Param 

func (m MethodSpec) Param(def ParamDefinition) MethodSpec

Param adds a parameter to the function.

func (MethodSpec) VariadicParams 

func (m MethodSpec) VariadicParams() MethodSpec

VariadicParams configures the method spec to allow variadic parameters.

type NamedContextFunction 

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 

func (n *NamedContextFunction) Annotation() string

Annotation returns the annotation of the underlying function.

func (*NamedContextFunction) Exec 

func (n *NamedContextFunction) Exec(ctx FunctionContext) (any, error)

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

func (*NamedContextFunction) Name 

func (n *NamedContextFunction) Name() string

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

func (*NamedContextFunction) QueryTargets 

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 

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 *any `json:"default,omitempty"`
	// contains filtered or unexported fields
}

ParamDefinition describes a single parameter for a function or method.

func ParamAny 

func ParamAny(name, description string) ParamDefinition

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

func ParamArray 

func ParamArray(name, description string) ParamDefinition

ParamArray creates a new array typed parameter.

func ParamBool 

func ParamBool(name, description string) ParamDefinition

ParamBool creates a new bool typed parameter.

func ParamFloat 

func ParamFloat(name, description string) ParamDefinition

ParamFloat creates a new float typed parameter.

func ParamInt64 

func ParamInt64(name, description string) ParamDefinition

ParamInt64 creates a new integer typed parameter.

func ParamObject 

func ParamObject(name, description string) ParamDefinition

ParamObject creates a new object typed parameter.

func ParamQuery 

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 

func ParamString(name, description string) ParamDefinition

ParamString creates a new string typed parameter.

func (ParamDefinition) Default 

func (d ParamDefinition) Default(v any) ParamDefinition

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

func (ParamDefinition) Optional 

func (d ParamDefinition) Optional() ParamDefinition

Optional marks the parameter as optional.

func (ParamDefinition) PrettyDefault 

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 

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 

func NewParams() Params

NewParams creates a new empty parameters definition.

func VariadicParams 

func VariadicParams() Params

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

func (Params) Add 

func (p Params) Add(def ParamDefinition) Params

Add a parameter to the spec.

func (Params) PopulateNamed 

func (p Params) PopulateNamed(args map[string]any) (*ParsedParams, error)

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

func (Params) PopulateNameless 

func (p Params) PopulateNameless(args ...any) (*ParsedParams, error)

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

type ParsedParams 

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

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

func (*ParsedParams) Field 

func (p *ParsedParams) Field(n string) (any, error)

Field returns an argument value with a given name.

func (*ParsedParams) FieldArray 

func (p *ParsedParams) FieldArray(n string) ([]any, error)

FieldArray returns an array value with a given name.

func (*ParsedParams) FieldBool 

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

FieldBool returns a bool argument value with a given name.

func (*ParsedParams) FieldFloat 

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

FieldFloat returns a float argument value with a given name.

func (*ParsedParams) FieldInt64 

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

FieldInt64 returns an integer argument value with a given name.

func (*ParsedParams) FieldOptionalArray 

func (p *ParsedParams) FieldOptionalArray(n string) (*[]any, error)

FieldOptionalArray returns an optional array value with a given name.

func (*ParsedParams) FieldOptionalBool 

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 

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 

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 

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 

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 

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

FieldQuery returns a query argument value with a given name.

func (*ParsedParams) FieldString 

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

FieldString returns a string argument value with a given name.

func (*ParsedParams) Index 

func (p *ParsedParams) Index(i int) (any, error)

Index returns an argument value at a given index.

func (*ParsedParams) Raw 

func (p *ParsedParams) Raw() []any

Raw returns the arguments as a generic slice.

func (*ParsedParams) ResolveDynamic 

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 

type Status string

Status of a function or method. 

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

Component statuses.

type TargetPath 

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 targeted.

func NewTargetPath 

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

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

type TargetType 

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
	TargetRoot
	TargetVariable
)

TargetTypes.

type TargetsContext 

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 targeting 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 

func (ctx TargetsContext) MainContext() []TargetPath

MainContext returns the path of the main context.

func (TargetsContext) NamedContext 

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

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

func (TargetsContext) PopContext 

func (ctx TargetsContext) PopContext() TargetsContext

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

func (TargetsContext) Value 

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 

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 

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 

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 any, exp ...ValueType) *TypeError

NewTypeError creates a new type error.

func NewTypeErrorFrom 

func NewTypeErrorFrom(from string, value any, 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 any) *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"
	ValueTimestamp ValueType = "timestamp"
	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 any) 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.