query

package
v4.4.2 Latest Latest
Warning

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

Go to latest
Published: Jul 18, 2022 License: MIT Imports: 40 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

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 ICompare

func ICompare(left, right interface{}) 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 interface{}) (bool, error)

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

func IGetBytes

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

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

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

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

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

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

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

func (e *ErrRecoverable) Unwrap() error

Unwrap the error.

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

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 InitFunctionHelper

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

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

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 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]interface{}
	Index    int
	MsgBatch MessageBatch

	// Reference new message being mapped
	NewMeta  MetaMsg
	NewValue *interface{}
	// 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. nolint:gocritic // Ignore unnamedResult false positive

func (FunctionContext) NamedValue

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

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

func (FunctionContext) PopValue

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

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

WithNamedValue returns a FunctionContext with a named value.

func (FunctionContext) WithValue

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

WithValue returns a function context with a new value.

func (FunctionContext) WithValueFunc

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

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 outter
	// 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

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

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

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

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

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

func NewLiteralFunction(annotation string, v interface{}) *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) (interface{}, 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 {
	MetaSet(key, value string)
	MetaGet(key string) string
	MetaDelete(key string)
	MetaIter(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 outter
	// 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

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

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) (interface{}, 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

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 *interface{} `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 interface{}) 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]interface{}) (*ParsedParams, error)

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

func (Params) PopulateNameless

func (p Params) PopulateNameless(args ...interface{}) (*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) (interface{}, error)

Field returns an argument value with a given name.

func (*ParsedParams) FieldArray

func (p *ParsedParams) FieldArray(n string) ([]interface{}, 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) (*[]interface{}, 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) (interface{}, error)

Index returns an argument value at a given index.

func (*ParsedParams) Raw

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

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

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

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

NewTypeError creates a new type error.

func NewTypeErrorFrom

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL