bloblang

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Dec 8, 2024 License: MIT Imports: 12 Imported by: 6

Documentation

Overview

Package bloblang provides high level APIs for registering custom Bloblang plugins, as well as for parsing and executing Bloblang mappings.

For a video guide on Bento plugins check out: https://youtu.be/uH6mKw-Ly0g And an example repo containing component plugins and tests can be found at: https://github.com/warpstreamlabs/bento-plugin-example

Plugins can either be registered globally, and will be accessible to any component parsing Bloblang expressions in the executable, or they can be registered as part of an isolated environment.

Example (BloblangFunctionPluginV2)

This example demonstrates how to create Bloblang methods and functions and execute them with a Bloblang mapping using the new V2 methods, which adds support to our functions and methods for optional named parameters. 

package main

import (
	"encoding/json"
	"fmt"

	"github.com/warpstreamlabs/bento/public/bloblang"
)

func main() {
	multiplyWrongSpec := bloblang.NewPluginSpec().
		Description("Multiplies two numbers together but gets it slightly wrong. Whoops.").
		Param(bloblang.NewFloat64Param("left").Description("The first of two numbers to multiply.")).
		Param(bloblang.NewFloat64Param("right").Description("The second of two numbers to multiply."))

	if err := bloblang.RegisterFunctionV2(
		"multiply_but_always_slightly_wrong", multiplyWrongSpec,
		func(args *bloblang.ParsedParams) (bloblang.Function, error) {
			left, err := args.GetFloat64("left")
			if err != nil {
				return nil, err
			}

			right, err := args.GetFloat64("right")
			if err != nil {
				return nil, err
			}

			return func() (any, error) {
				return left*right + 0.02, nil
			}, nil
		}); err != nil {
		panic(err)
	}

	// Our function now optionally supports named parameters, when a function is
	// instantiated with unamed parameters they must follow the order in which
	// the parameters are registered.
	mapping := `
root.num_ab = multiply_but_always_slightly_wrong(left: this.a, right: this.b)
root.num_cd = multiply_but_always_slightly_wrong(this.c, this.d)
`

	exe, err := bloblang.Parse(mapping)
	if err != nil {
		panic(err)
	}

	res, err := exe.Query(map[string]any{
		"a": 1.2, "b": 2.6, "c": 5.3, "d": 8.2,
	})
	if err != nil {
		panic(err)
	}

	jsonBytes, err := json.Marshal(res)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(jsonBytes))
}

Output:

{"num_ab":3.14,"num_cd":43.48}
Example (BloblangMethodPluginV2)

This example demonstrates how to create Bloblang methods and functions and execute them with a Bloblang mapping using the new V2 methods, which adds support to our functions and methods for optional named parameters. 

package main

import (
	"encoding/json"
	"fmt"
	"math/rand"

	"github.com/warpstreamlabs/bento/public/bloblang"
)

func main() {
	hugStringSpec := bloblang.NewPluginSpec().
		Description("Wraps a string with a prefix and suffix.").
		Param(bloblang.NewStringParam("prefix").Description("The prefix to insert.")).
		Param(bloblang.NewStringParam("suffix").Description("The suffix to append."))

	if err := bloblang.RegisterMethodV2("hug_string", hugStringSpec, func(args *bloblang.ParsedParams) (bloblang.Method, error) {
		prefix, err := args.GetString("prefix")
		if err != nil {
			return nil, err
		}

		suffix, err := args.GetString("suffix")
		if err != nil {
			return nil, err
		}

		return bloblang.StringMethod(func(s string) (any, error) {
			return prefix + s + suffix, nil
		}), nil
	}); err != nil {
		panic(err)
	}

	reverseSpec := bloblang.NewPluginSpec().
		Description("Reverses the order of an array target, but sometimes it randomly doesn't. Whoops.")

	if err := bloblang.RegisterMethodV2("sometimes_reverse", reverseSpec, func(*bloblang.ParsedParams) (bloblang.Method, error) {
		rand := rand.New(rand.NewSource(0))
		return bloblang.ArrayMethod(func(in []any) (any, error) {
			if rand.Int()%3 == 0 {
				// Whoopsie
				return in, nil
			}
			out := make([]any, len(in))
			copy(out, in)
			for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
				out[i], out[j] = out[j], out[i]
			}
			return out, nil
		}), nil
	}); err != nil {
		panic(err)
	}

	// Our methods now optionally support named parameters, when a method is
	// instantiated with unamed parameters they must follow the order in which
	// the parameters are registered.
	mapping := `
root.new_summary = this.summary.hug_string(prefix: "meow", suffix: "woof")
root.reversed = this.names.sometimes_reverse()
`

	exe, err := bloblang.Parse(mapping)
	if err != nil {
		panic(err)
	}

	res, err := exe.Query(map[string]any{
		"summary": "quack",
		"names":   []any{"denny", "pixie", "olaf", "jen", "spuz"},
	})
	if err != nil {
		panic(err)
	}

	jsonBytes, err := json.Marshal(res)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(jsonBytes))
}

Output:

{"new_summary":"meowquackwoof","reversed":["spuz","jen","olaf","pixie","denny"]}
Example (BloblangRestrictedEnvironment)

This example demonstrates how to create and use an isolated Bloblang environment with some standard functions removed. 

package main

import (
	"encoding/json"
	"fmt"
	"strings"

	"github.com/warpstreamlabs/bento/public/bloblang"
)

func main() {
	env := bloblang.NewEnvironment().WithoutFunctions("env", "file")

	customThingSpec := bloblang.NewPluginSpec().
		Description("Uppercases some stuff or something")

	if err := env.RegisterMethodV2("custom_thing", customThingSpec, func(args *bloblang.ParsedParams) (bloblang.Method, error) {
		return bloblang.StringMethod(func(s string) (any, error) {
			return strings.ToUpper(s), nil
		}), nil
	}); err != nil {
		panic(err)
	}

	mapping := `
root.foo = this.foo.string()
root.bar = this.bar + this.baz
root.buz = this.buz.content.custom_thing()
`

	exe, err := env.Parse(mapping)
	if err != nil {
		panic(err)
	}

	res, err := exe.Query(map[string]any{
		"foo": 50.0,
		"bar": "first bit ",
		"baz": "second bit",
		"buz": map[string]any{
			"id":      "XXXX",
			"content": "some nested content",
		},
	})
	if err != nil {
		panic(err)
	}

	jsonBytes, err := json.Marshal(res)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(jsonBytes))
}

Output:

{"bar":"first bit second bit","buz":"SOME NESTED CONTENT","foo":"50"}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrRootDeleted = errors.New("root was deleted")

ErrRootDeleted is returned by a Bloblang query when the mapping results in the root being deleted. It might be considered correct to do this in situations where filtering is allowed or expected.

Functions

func RegisterAdvancedFunction 

func RegisterAdvancedFunction(name string, spec *PluginSpec, ctor AdvancedFunctionConstructor) error

RegisterAdvancedFunction adds a new advanced Bloblang function to the global environment. All function names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func RegisterAdvancedMethod 

func RegisterAdvancedMethod(name string, spec *PluginSpec, ctor AdvancedMethodConstructor) error

RegisterAdvancedMethod adds a new advanced Bloblang method to the global environment. All method names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func RegisterFunction 

func RegisterFunction(name string, ctor FunctionConstructor) error

RegisterFunction adds a new Bloblang function to the global environment. All function names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func RegisterFunctionV2 

func RegisterFunctionV2(name string, spec *PluginSpec, ctor FunctionConstructorV2) error

RegisterFunctionV2 adds a new Bloblang function to the global environment. All function names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func RegisterMethod 

func RegisterMethod(name string, ctor MethodConstructor) error

RegisterMethod adds a new Bloblang method to the global environment. All method names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func RegisterMethodV2 

func RegisterMethodV2(name string, spec *PluginSpec, ctor MethodConstructorV2) error

RegisterMethodV2 adds a new Bloblang method to the global environment. All method names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func ValueAsBytes 

func ValueAsBytes(v any) ([]byte, error)

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

func ValueAsFloat32(v any) (float32, error)

ValueAsFloat32 takes a boxed value and attempts to extract a number from it.

func ValueAsFloat64 

func ValueAsFloat64(v any) (float64, error)

ValueAsFloat64 takes a boxed value and attempts to extract a number from it.

func ValueAsInt64 

func ValueAsInt64(v any) (int64, error)

ValueAsInt64 takes a boxed value and attempts to extract a number from it.

func ValueAsTimestamp 

func ValueAsTimestamp(v any) (time.Time, error)

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

func ValueSanitized(i any) any

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

func ValueToString(v any) string

ValueToString converts any value into a string according to the same rules that other native bento components including bloblang would follow, where simple value types are stringified, but complex types are converted into JSON marshalled as a string.

Types

type AdvancedFunction 

type AdvancedFunction func(ctx *ExecContext) (any, error)

AdvancedFunction defines a Bloblang function that accesses the execution context of the mapping during invocation.

type AdvancedFunctionConstructor 

type AdvancedFunctionConstructor func(args *ParsedParams) (AdvancedFunction, error)

AdvancedFunctionConstructor defines a constructor for a Bloblang function where parameters are parsed using a ParamsSpec provided when registering the function, and the constructed function is provided an ExecContext.

type AdvancedMethod 

type AdvancedMethod func(ctx *ExecContext, fn *ExecFunction) (any, error)

AdvancedMethod defines a Bloblang method that accesses the execution context of the mapping during invocation. Advanced methods are responsible for calling Exec upon the ExecFunction they target, and have the capability to mutate or modify the execution context of that target.

type AdvancedMethodConstructor 

type AdvancedMethodConstructor func(args *ParsedParams) (AdvancedMethod, error)

AdvancedMethodConstructor defines a constructor for a Bloblang method where parameters are parsed using a ParamsSpec provided when registering the method, and the constructed method is provided an ExecContext.

type ArgError 

type ArgError struct {
	// The argument index
	Index int

	// The expected argument type
	ExpectedKind reflect.Kind

	// The actual type provided
	ActualKind reflect.Kind

	// The value of the argument
	Value any
}

ArgError represents an error encountered when parsing a function or method argument.

func (*ArgError) Error 

func (a *ArgError) Error() string

type ArgSpec 

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

ArgSpec provides an API for validating and extracting function or method arguments by registering them with pointer receivers.

func NewArgSpec 

func NewArgSpec() *ArgSpec

NewArgSpec creates an argument parser/validator.

func (*ArgSpec) AnyVar 

func (a *ArgSpec) AnyVar(i *any) *ArgSpec

AnyVar creates an argument to follow the previously created argument that can have any value.

func (*ArgSpec) BoolVar 

func (a *ArgSpec) BoolVar(b *bool) *ArgSpec

BoolVar creates a boolean argument to follow the previously created argument.

func (*ArgSpec) Extract 

func (a *ArgSpec) Extract(args []any) error

Extract the specified typed arguments from a slice of generic arguments. Returns an error if the number of arguments does not match the spec, and returns an *ArgError if the type of an argument is mismatched.

func (*ArgSpec) Float64Var 

func (a *ArgSpec) Float64Var(f *float64) *ArgSpec

Float64Var creates a Float64 argument to follow the previously created argument.

func (*ArgSpec) Int64Var 

func (a *ArgSpec) Int64Var(i *int64) *ArgSpec

Int64Var creates an int64 argument to follow the previously created argument.

func (*ArgSpec) IntVar 

func (a *ArgSpec) IntVar(i *int) *ArgSpec

IntVar creates an int argument to follow the previously created argument.

func (*ArgSpec) StringVar 

func (a *ArgSpec) StringVar(s *string) *ArgSpec

StringVar creates a string argument to follow the previously created argument.

type Environment 

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

Environment provides an isolated Bloblang environment where the available features, functions and methods can be modified.

func GlobalEnvironment 

func GlobalEnvironment() *Environment

GlobalEnvironment returns the global default environment. Modifying this environment will impact all Bloblang parses that aren't initialized with an isolated environment, as well as any new environments initialized after the changes.

func NewEmptyEnvironment 

func NewEmptyEnvironment() *Environment

NewEmptyEnvironment creates a fresh Bloblang environment starting completely empty, where no functions or methods are initially available.

func NewEnvironment 

func NewEnvironment() *Environment

NewEnvironment creates a fresh Bloblang environment, starting with the full range of globally defined features (functions and methods), and provides APIs for expanding or contracting the features available to this environment.

It's worth using an environment when you need to restrict the access or capabilities that certain bloblang mappings have versus others.

For example, an environment could be created that removes any functions for accessing environment variables or reading data from the host disk, which could be used in certain situations without removing those functions globally for all mappings.

func XWrapEnvironment 

func XWrapEnvironment(v *bloblang.Environment) *Environment

XWrapEnvironment is for internal use only, do not use this.

func (*Environment) CheckInterpolatedString 

func (e *Environment) CheckInterpolatedString(str string) error

CheckInterpolatedString attempts to parse a Bloblang interpolated string using the Environment to determine the features (functions and methods) available to it.

When a parsing error occurs the error will be the type *ParseError, which gives access to the line and column where the error occurred, as well as a method for creating a well formatted error message.

func (*Environment) Clone 

func (e *Environment) Clone() *Environment

Clone an environment in order to register functions and methods without modifying the existing environment.

func (*Environment) Deactivated 

func (e *Environment) Deactivated() *Environment

Deactivated returns a version of the environment where constructors are disabled for all functions and methods, allowing mappings to be parsed and validated but not executed.

The underlying register of functions and methods is shared with the target environment, and therefore functions/methods registered to this set will also be added to the still activated environment. Use Clone in order to avoid this.

func (*Environment) OnlyPure 

func (e *Environment) OnlyPure() *Environment

OnlyPure removes any methods and functions that have been registered but are marked as impure. Impure in this context means the method/function is able to mutate global state or access machine state (read environment variables, files, etc). Note that methods/functions that access the machine clock are not marked as pure, so timestamp functions will still work.

func (*Environment) Parse 

func (e *Environment) Parse(blobl string) (*Executor, error)

Parse a Bloblang mapping using the Environment to determine the features (functions and methods) available to the mapping.

When a parsing error occurs the error will be the type *ParseError, which gives access to the line and column where the error occurred, as well as a method for creating a well formatted error message.

func (*Environment) RegisterAdvancedFunction 

func (e *Environment) RegisterAdvancedFunction(name string, spec *PluginSpec, ctor AdvancedFunctionConstructor) error

RegisterAdvancedFunction adds a new Bloblang function to the environment using a provided ParamsSpec to define the name of the function and its parameters. Advanced functions are provided extra context during invocation.

Plugin names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) RegisterAdvancedMethod 

func (e *Environment) RegisterAdvancedMethod(name string, spec *PluginSpec, ctor AdvancedMethodConstructor) error

RegisterAdvancedMethod adds a new Bloblang method to the environment using a provided ParamsSpec to define the name of the method and its parameters. Advanced methods are provided extra context during invocation.

Plugin names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) RegisterFunction 

func (e *Environment) RegisterFunction(name string, ctor FunctionConstructor) error

RegisterFunction adds a new Bloblang function to the environment. All function names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) RegisterFunctionV2 

func (e *Environment) RegisterFunctionV2(name string, spec *PluginSpec, ctor FunctionConstructorV2) error

RegisterFunctionV2 adds a new Bloblang function to the environment using a provided ParamsSpec to define the name of the function and its parameters.

Plugin names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) RegisterMethod 

func (e *Environment) RegisterMethod(name string, ctor MethodConstructor) error

RegisterMethod adds a new Bloblang method to the environment. All method names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) RegisterMethodV2 

func (e *Environment) RegisterMethodV2(name string, spec *PluginSpec, ctor MethodConstructorV2) error

RegisterMethodV2 adds a new Bloblang method to the environment using a provided ParamsSpec to define the name of the method and its parameters.

Plugin names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func (*Environment) WalkFunctions 

func (e *Environment) WalkFunctions(fn func(name string, spec *FunctionView))

WalkFunctions executes a provided function argument for every function that has been registered to the environment.

func (*Environment) WalkMethods 

func (e *Environment) WalkMethods(fn func(name string, spec *MethodView))

WalkMethods executes a provided function argument for every method that has been registered to the environment.

func (*Environment) WithCustomImporter 

func (e *Environment) WithCustomImporter(fn func(name string) ([]byte, error)) *Environment

WithCustomImporter returns a copy of the environment where imports from mappings are done via a provided closure function.

func (*Environment) WithDisabledImports 

func (e *Environment) WithDisabledImports() *Environment

WithDisabledImports returns a copy of the environment where imports within mappings are disabled.

func (*Environment) WithMaxMapRecursion 

func (e *Environment) WithMaxMapRecursion(n int) *Environment

WithMaxMapRecursion returns a copy of the environment where the maximum recursion allowed for maps is set to a given value. If the execution of a mapping from this environment matches this number of recursive map calls the mapping will error out.

func (*Environment) WithoutFunctions 

func (e *Environment) WithoutFunctions(names ...string) *Environment

WithoutFunctions returns a copy of the environment but with a variadic list of function names removed. Instantiation of these removed functions within a mapping will cause errors at parse time.

func (*Environment) WithoutMethods 

func (e *Environment) WithoutMethods(names ...string) *Environment

WithoutMethods returns a copy of the environment but with a variadic list of method names removed. Instantiation of these removed methods within a mapping will cause errors at parse time.

func (*Environment) XUnwrapper 

func (e *Environment) XUnwrapper() any

XUnwrapper is for internal use only, do not use this.

type ExecContext 

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

ExecContext is an optional context provided to advanced functions and methods that contains information about a given mapping at the time the function/method is executed. The vast majority of Bloblang plugins would not require this context and it is omitted by default.

func (*ExecContext) Exec 

func (e *ExecContext) Exec(fn *ExecFunction) (any, error)

Exec attempts to execute a provided ExecFunction, returning either a value or an error. Values returned depend on the function but typically fall within the standard scalar, any-map and any-slice values seen by most plugins.

However, two exceptions exist which should be noted by Exec callers: ExecResultNothing and ExecResultDelete, as both of these values could be yielded and must be handled differently to typical values.

func (*ExecContext) ExecToInt64 

func (e *ExecContext) ExecToInt64(fn *ExecFunction) (int64, error)

ExecToInt64 attempts to execute a provided ExecFunction, returning either an integer value or an error if the execution failed or the value returned was not a valid integer.

type ExecFunction 

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

ExecFunction represents an active Bloblang function that can be executed by providing it an ExecContext. This is only relevant for advanced functions and methods that may wish to exhibit fully customised behaviours and/or mutate the contextual state of parameters and/or method targets.

Most plugin authors will not have a need for interacting with any ExecFunction.

type ExecResultDelete 

type ExecResultDelete *struct{}

ExecResultDelete represents a value yielded from an executed function where the mapping resulted in an instruction to delete the root entity.

When a delete is returned it is up to the caller of the function to interpret what this means. Usually it means the input data should be deleted entirely.

THERE IS NO CIRCUMSTANCE WHERE IT IS APPROPRIATE FOR PLUGIN AUTHORS TO RETURN THIS VALUE.

type ExecResultNothing 

type ExecResultNothing *struct{}

ExecResultNothing represents a value yielded from an executed function where the mapping resulted in nothing being enacted. For example, this could mean the mapping was an if-statement that resolved to `false` and had no alternative branches to execute.

When nothing is returned it is up to the caller of the function to interpret what this means. Usually it means the input data should be left as it was.

THERE IS NO CIRCUMSTANCE WHERE IT IS APPROPRIATE FOR PLUGIN AUTHORS TO RETURN THIS VALUE.

type Executor 

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

Executor stores a parsed Bloblang mapping and provides APIs for executing it.

func Parse 

func Parse(blobl string) (*Executor, error)

Parse a Bloblang mapping allowing the use of the globally accessible range of features (functions and methods).

When a parsing error occurs the error will be the type *ParseError, which gives access to the line and column where the error occurred, as well as a method for creating a well formatted error message.

func (*Executor) Overlay 

func (e *Executor) Overlay(val any, onto *any) error

Overlay executes a Bloblang mapping against a value, where assignments are overlayed onto an existing structure.

If the mapping results in the root of the new document being deleted then ErrRootDeleted is returned, which can be used as a signal to filter rather than fail the mapping.

func (*Executor) Query 

func (e *Executor) Query(val any) (any, error)

Query executes a Bloblang mapping against a value and returns the result. The argument and return values can be structured using the same map[string]interface{} and []interface{} types as would be returned by the Go standard json package unmarshaler.

If the mapping results in the root of the new document being deleted then ErrRootDeleted is returned, which can be used as a signal to filter rather than fail the mapping.

func (*Executor) XUnwrapper 

func (e *Executor) XUnwrapper() any

XUnwrapper is for internal use only, do not use this.

type Function 

type Function func() (any, error)

Function defines a Bloblang function, arguments are provided to the constructor, allowing the implementation of this function to resolve them statically when possible.

type FunctionConstructor 

type FunctionConstructor func(args ...any) (Function, error)

FunctionConstructor defines a constructor for a Bloblang function, where a variadic list of arguments are provided.

When a function is parsed from a mapping with static arguments the constructor will be called only once at parse time. When a function is parsed with dynamic arguments, such as a value derived from the mapping input, the constructor will be called on each invocation of the mapping with the derived arguments.

For a convenient way to perform type checking and coercion on the arguments use an ArgSpec.

type FunctionConstructorV2 

type FunctionConstructorV2 func(args *ParsedParams) (Function, error)

FunctionConstructorV2 defines a constructor for a Bloblang function where parameters are parsed using a ParamsSpec provided when registering the function.

When a function is parsed from a mapping with static arguments the constructor will be called only once at parse time. When a function is parsed with dynamic arguments, such as a value derived from the mapping input, the constructor will be called on each invocation of the mapping with the derived arguments.

type FunctionView 

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

FunctionView describes a particular function belonging to a Bloblang environment.

func (*FunctionView) Description 

func (v *FunctionView) Description() string

Description provides an overview of the function.

func (*FunctionView) FormatJSON 

func (v *FunctionView) FormatJSON() ([]byte, error)

FormatJSON returns a byte slice of the function configuration formatted as a JSON object. The schema of this method is undocumented and is not intended for general use.

Experimental: This method is not intended for general use and could have its signature and/or behaviour changed outside of major version bumps.

func (*FunctionView) TemplateData added in v1.1.0 

func (v *FunctionView) TemplateData() TemplateFunctionData

TemplateData returns an exported struct containing information ready to inject into a template for generating documentation.

type Method 

type Method func(v any) (any, error)

Method defines a Bloblang function that executes on a value. Arguments are provided to the constructor, allowing the implementation of this method to resolve them statically when possible.

In order to avoid type checking the value use one of the typed variants such as StringMethod.

func ArrayMethod 

func ArrayMethod(methodFn func([]any) (any, error)) Method

ArrayMethod creates a general method signature from an array method by performing type checking on the method target.

func BoolMethod 

func BoolMethod(methodFn func(bool) (any, error)) Method

BoolMethod creates a general method signature from a bool method by performing type checking on the method target.

func BytesMethod 

func BytesMethod(methodFn func([]byte) (any, error)) Method

BytesMethod creates a general method signature from a byte slice method by performing type checking on the method target.

func Float64Method 

func Float64Method(methodFn func(float64) (any, error)) Method

Float64Method creates a general method signature from a float method by performing type checking on the method target.

func Int64Method 

func Int64Method(methodFn func(int64) (any, error)) Method

Int64Method creates a general method signature from an int method by performing type checking on the method target.

func ObjectMethod 

func ObjectMethod(methodFn func(obj map[string]any) (any, error)) Method

ObjectMethod creates a general method signature from an object method by performing type checking on the method target.

func StringMethod 

func StringMethod(methodFn func(string) (any, error)) Method

StringMethod creates a general method signature from a string method by performing type checking on the method target.

func TimestampMethod 

func TimestampMethod(methodFn func(time.Time) (any, error)) Method

TimestampMethod creates a general method signature from a timestamp method by performing type checking on the method target.

type MethodConstructor 

type MethodConstructor func(args ...any) (Method, error)

MethodConstructor defines a constructor for a Bloblang method, where a variadic list of arguments are provided.

When a method is parsed from a mapping with static arguments the constructor will be called only once at parse time. When a method is parsed with dynamic arguments, such as a value derived from the mapping input, the constructor will be called on each invocation of the mapping with the derived arguments.

For a convenient way to perform type checking and coercion on the arguments use an ArgSpec.

type MethodConstructorV2 

type MethodConstructorV2 func(args *ParsedParams) (Method, error)

MethodConstructorV2 defines a constructor for a Bloblang method where parameters are parsed using a ParamsSpec provided when registering the method.

When a method is parsed from a mapping with static arguments the constructor will be called only once at parse time. When a method is parsed with dynamic arguments, such as a value derived from the mapping input, the constructor will be called on each invocation of the mapping with the derived arguments.

type MethodView 

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

MethodView describes a particular method belonging to a Bloblang environment.

func (*MethodView) Description 

func (v *MethodView) Description() string

Description provides an overview of the method.

func (*MethodView) FormatJSON 

func (v *MethodView) FormatJSON() ([]byte, error)

FormatJSON returns a byte slice of the method configuration formatted as a JSON object. The schema of this method is undocumented and is not intended for general use.

Experimental: This method is not intended for general use and could have its signature and/or behaviour changed outside of major version bumps.

func (*MethodView) TemplateData added in v1.1.0 

func (v *MethodView) TemplateData() TemplateMethodData

TemplateData returns an exported struct containing information ready to inject into a template for generating documentation.

type ParamDefinition 

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

ParamDefinition describes a single parameter for a function or method.

func NewAnyParam 

func NewAnyParam(name string) ParamDefinition

NewAnyParam creates a new parameter that can be any type. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewBoolParam 

func NewBoolParam(name string) ParamDefinition

NewBoolParam creates a new bool typed parameter. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewFloat64Param 

func NewFloat64Param(name string) ParamDefinition

NewFloat64Param creates a new float64 typed parameter. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewInt64Param 

func NewInt64Param(name string) ParamDefinition

NewInt64Param creates a new 64-bit integer typed parameter. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewQueryParam 

func NewQueryParam(name string, allowScalars bool) ParamDefinition

NewQueryParam creates a new advanced parameter that can yield any value and is encapsulated as an ExecFunction. This is important for advanced functions and methods that need greater control over how the parameters are resolved. The allowScalars parameter determines whether scalar values are valid for this parameter, when `false` all parameter arguments must be dynamic expressions.

However, most plugins will not benefit from query parameters, and they can only be resolved via the ExecContext provided to functions and methods registered with RegisterAdvancedFunction and RegisterAdvancedMethod respectively.

Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewStringParam 

func NewStringParam(name string) ParamDefinition

NewStringParam creates a new string typed parameter. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

func NewTimestampParam 

func NewTimestampParam(name string) ParamDefinition

NewTimestampParam creates a new timestamp typed parameter. Parameter names must match the regular expression /^[a-z0-9]+(_[a-z0-9]+)*$/ (snake case).

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

func (d ParamDefinition) Description(str string) ParamDefinition

Description adds an optional description to the parameter definition, this is used when generating documentation for the parameter to describe what the parameter is for.

func (ParamDefinition) Optional 

func (d ParamDefinition) Optional() ParamDefinition

Optional marks the parameter as optional.

type ParseError 

type ParseError struct {
	Line   int
	Column int
	// contains filtered or unexported fields
}

ParseError is a structured error type for Bloblang parser errors that provides access to information such as the line and column where the error occurred.

func (*ParseError) Error 

func (p *ParseError) Error() string

Error returns a single line error string.

func (*ParseError) ErrorMultiline 

func (p *ParseError) ErrorMultiline() string

ErrorMultiline returns an error string spanning multiple lines that provides a cleaner view of the specific error.

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

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

AsSlice returns a slice of raw argument values.

func (*ParsedParams) Get 

func (p *ParsedParams) Get(name string) (any, error)

Get an argument value with a given name and return it boxed within an empty interface.

func (*ParsedParams) GetBool 

func (p *ParsedParams) GetBool(name string) (bool, error)

GetBool returns a bool argument value with a given name.

func (*ParsedParams) GetFloat64 

func (p *ParsedParams) GetFloat64(name string) (float64, error)

GetFloat64 returns a float argument value with a given name.

func (*ParsedParams) GetInt64 

func (p *ParsedParams) GetInt64(name string) (int64, error)

GetInt64 returns an integer argument value with a given name.

func (*ParsedParams) GetOptionalBool 

func (p *ParsedParams) GetOptionalBool(name string) (*bool, error)

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

func (*ParsedParams) GetOptionalFloat64 

func (p *ParsedParams) GetOptionalFloat64(name string) (*float64, error)

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

func (*ParsedParams) GetOptionalInt64 

func (p *ParsedParams) GetOptionalInt64(name string) (*int64, error)

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

func (*ParsedParams) GetOptionalQuery 

func (p *ParsedParams) GetOptionalQuery(name string) (*ExecFunction, error)

GetOptionalQuery returns an ExecFunction from a parameter defined as a NewQueryParam if it was defined, otherwise nil.

func (*ParsedParams) GetOptionalString 

func (p *ParsedParams) GetOptionalString(name string) (*string, error)

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

func (*ParsedParams) GetOptionalTimestamp 

func (p *ParsedParams) GetOptionalTimestamp(name string) (*time.Time, error)

GetOptionalTimestamp returns a timestamp argument value with a given name if it was defined, otherwise nil.

func (*ParsedParams) GetQuery 

func (p *ParsedParams) GetQuery(name string) (*ExecFunction, error)

GetQuery returns an ExecFunction from a parameter defined as a NewQueryParam.

func (*ParsedParams) GetString 

func (p *ParsedParams) GetString(name string) (string, error)

GetString returns a string argument value with a given name.

func (*ParsedParams) GetTimestamp 

func (p *ParsedParams) GetTimestamp(name string) (time.Time, error)

GetTimestamp returns a timestamp argument value with a given name.

func (*ParsedParams) ImportFile 

func (p *ParsedParams) ImportFile(name string) ([]byte, error)

ImportFile attempts to read a file via the underlying environment importer. Relative paths will be resolved from the path of the file being imported.

type PluginSpec 

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

PluginSpec documents and defines the parameters of a function or method and the way in which it should be used.

Using a plugin spec with explicit parameters means that instantiations of the plugin can be done using either classic argument types (foo, bar, baz), following the order in which the parameters are added, or named style (c: baz, a: foo).

func NewPluginSpec 

func NewPluginSpec() *PluginSpec

NewPluginSpec creates a new plugin definition for a function or method plugin that describes the arguments that the plugin expects.

func (*PluginSpec) Beta 

func (p *PluginSpec) Beta() *PluginSpec

Beta flags the plugin as a beta component.

func (*PluginSpec) Category 

func (p *PluginSpec) Category(str string) *PluginSpec

Category adds an optional category string to the plugin spec, this is used when generating documentation for the plugin.

func (*PluginSpec) Deprecated 

func (p *PluginSpec) Deprecated() *PluginSpec

Deprecated flags the plugin as a deprecated component, it will still be valid in mappings but won't appear prominently in documentation.

func (*PluginSpec) Description 

func (p *PluginSpec) Description(str string) *PluginSpec

Description adds an optional description to the plugin spec, this is used when generating documentation for the plugin.

func (*PluginSpec) EncodeJSON 

func (p *PluginSpec) EncodeJSON(v []byte) error

EncodeJSON attempts to parse a JSON object as a byte slice and uses it to populate the configuration spec. The schema of this method is undocumented and is not intended for general use.

Experimental: This method is not intended for general use and could have its signature and/or behaviour changed outside of major version bumps.

func (*PluginSpec) Example 

func (p *PluginSpec) Example(summary, mapping string, inputOutputs ...[2]string) *PluginSpec

Example adds an optional example to the plugin spec, this is used when generating documentation for the plugin. An example consists of a short summary, a mapping demonstrating the plugin, and one or more input/output combinations. When generating documentation the project will also run these examples and ensure they produce the documented results, in order to skip these checks use ExampleNotTested.

func (*PluginSpec) ExampleNotTested 

func (p *PluginSpec) ExampleNotTested(summary, mapping string, inputOutputs ...[2]string) *PluginSpec

ExampleNotTested adds an optional example to the plugin spec, this is used when generating documentation for the plugin. An example consists of a short summary, a mapping demonstrating the plugin, and one or more input/output combinations.

The implementation of the plugin is expected to be correct, but the input/output combinations are not tested to be accurate at any stage. This is particularly useful in cases where the example input/output combinations are redacted or non-deterministic.

func (*PluginSpec) Experimental 

func (p *PluginSpec) Experimental() *PluginSpec

Experimental flags the plugin as an experimental component.

func (*PluginSpec) Impure 

func (p *PluginSpec) Impure() *PluginSpec

Impure marks the plugin as "impure", meaning it either reads from or interacts with state outside of the boundaries of a single mapping invocation. This usually means reading state from the machine. Impure plugins are excluded from some bloblang environments.

func (*PluginSpec) Param 

func (p *PluginSpec) Param(def ParamDefinition) *PluginSpec

Param adds a parameter to the spec. Instantiations of the plugin with nameless arguments (foo, bar, baz) must follow the order in which fields are added to the spec.

func (*PluginSpec) Static 

func (p *PluginSpec) Static() *PluginSpec

Static marks the plugin as a statically evaluated function or method. This is a guarantee that given the same parameters this plugin will always yield the same value.

Marking a function or method as static has the advantage that it can sometimes be optimistically evaluated at mapping parse time when given static arguments.

func (*PluginSpec) StaticWithFunc 

func (p *PluginSpec) StaticWithFunc(fn func(params *ParsedParams) bool) *PluginSpec

StaticWithFunc marks the plugin as a potentially statically evaluated function or method, but only given certain parameters as determined by the provided closure function. This is a guarantee that given the same parameters this plugin will always yield the same value.

Marking a function or method as static has the advantage that it can sometimes be optimistically evaluated at mapping parse time when given static arguments.

func (*PluginSpec) Variadic 

func (p *PluginSpec) Variadic() *PluginSpec

Variadic marks this plugin as having variadic parameters, which means any number of arguments can be provided and they are unnamed. It is invalid to combine variadic with named parameters.

A variadic method is able to extract arguments from a *ParsedParams object via the AsSlice method.

func (*PluginSpec) Version 

func (p *PluginSpec) Version(v string) *PluginSpec

Version specifies that this plugin was introduced in a given version.

type TemplateExampleData added in v1.1.0 

type TemplateExampleData struct {
	Mapping string
	Summary string
	Results [][2]string

	// True if this example will not function as shown when tested
	SkipTesting bool
}

TemplateExampleData describes a single example for a given bloblang plugin.

type TemplateFunctionData added in v1.1.0 

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

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

	// Category is a rough category for the function.
	Category string

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

	// Params defines the expected arguments of the function.
	Params TemplateParamsData

	// Examples shows general usage for the function.
	Examples []TemplateExampleData

	// Version is the Bento version this component was introduced.
	Version string
}

TemplateFunctionData describes a bloblang function.

type TemplateMethodCategoryData added in v1.1.0 

type TemplateMethodCategoryData struct {
	Category    string
	Description string
	Examples    []TemplateExampleData
}

TemplateMethodCategoryData describes a behaviour, along with examples, of a method plugin for a given category. Separating documentation for a method into categories is sometimes appropriate in cases where the method behaves differently based on the target value.

type TemplateMethodData added in v1.1.0 

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

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

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

	// Params defines the expected arguments of the method.
	Params TemplateParamsData

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

	// Categories further describe the method for a given category.
	Categories []TemplateMethodCategoryData

	// Version is the Bento version this component was introduced.
	Version string
}

TemplateMethodData describes a bloblang method.

type TemplateParamData added in v1.1.0 

type TemplateParamData struct {
	Name        string
	Description string
	ValueType   string

	// IsOptional is implicit when there's a DefaultMarshalled. However, there
	// are times when a parameter is used to change behaviour without having a
	// default.
	IsOptional        bool
	DefaultMarshalled string
}

TemplateParamData describes a single parameter defined for a bloblang plugin.

type TemplateParamsData added in v1.1.0 

type TemplateParamsData struct {
	Variadic    bool
	Definitions []TemplateParamData
}

TemplateParamsData describes the overall set of parameters for a bloblang plugin.

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.