bloblang

Documentation

Index

• type Environment
  • func GlobalEnvironment() *Environment
  • func NewEmptyEnvironment() *Environment
  • func NewEnvironment() *Environment
  • func (e *Environment) Deactivated() *Environment
  • func (e *Environment) ImportFile(name string) ([]byte, error)
  • func (e *Environment) NewField(expr string) (*field.Expression, error)
  • func (e *Environment) NewMapping(blobl string) (*mapping.Executor, error)
  • func (e *Environment) OnlyPure() *Environment
  • func (e *Environment) RegisterFunction(spec query.FunctionSpec, ctor query.FunctionCtor) error
  • func (e *Environment) RegisterMethod(spec query.MethodSpec, ctor query.MethodCtor) error
  • func (e *Environment) WalkFunctions(fn func(name string, spec query.FunctionSpec))
  • func (e *Environment) WalkMethods(fn func(name string, spec query.MethodSpec))
  • func (e *Environment) WithCustomImporter(fn func(name string) ([]byte, error)) *Environment
  • func (e *Environment) WithDisabledImports() *Environment
  • func (e *Environment) WithImporter(importer parser.Importer) *Environment
  • func (e *Environment) WithImporterRelativeToFile(filePath string) *Environment
  • func (e *Environment) WithMaxMapRecursion(n int) *Environment
  • func (e *Environment) WithoutFunctions(names ...string) *Environment
  • func (e *Environment) WithoutMethods(names ...string) *Environment

Types

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 (*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 the Without methods (with empty args if applicable) in order to create a deep copy of the environment that is independent of the source.

func (*Environment) ImportFile

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

ImportFile attempts to read a file from the target filesystem. This defaults to the operating system disk where paths are relative to the bloblang file being parsed. However, custom importers can be configured at the environment level in order to change where and how files are accessed.

func (*Environment) NewField

func (e *Environment) NewField(expr string) (*field.Expression, error)

NewField attempts to parse and create a dynamic field expression from a string. If the expression is invalid an error is returned.

When a parsing error occurs the returned error will be a *parser.Error type, which allows you to gain positional and structured error messages.

func (*Environment) NewMapping

func (e *Environment) NewMapping(blobl string) (*mapping.Executor, error)

NewMapping parses 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 *parser.Error, 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) 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) RegisterFunction

func (e *Environment) RegisterFunction(spec query.FunctionSpec, ctor query.FunctionCtor) error

RegisterFunction adds a new Bloblang function to the environment.

func (*Environment) RegisterMethod

func (e *Environment) RegisterMethod(spec query.MethodSpec, ctor query.MethodCtor) error

RegisterMethod adds a new Bloblang method to the environment.

func (*Environment) WalkFunctions

func (e *Environment) WalkFunctions(fn func(name string, spec query.FunctionSpec))

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 query.MethodSpec))

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 version of the environment where file imports are done exclusively through a provided closure function, which takes an import path (relative or absolute).

func (*Environment) WithDisabledImports

func (e *Environment) WithDisabledImports() *Environment

WithDisabledImports returns a version of the environment where imports within mappings are disabled entirely. This prevents mappings from accessing files from the host disk.

func (*Environment) WithImporter

func (e *Environment) WithImporter(importer parser.Importer) *Environment

WithImporter returns a new environment where Bloblang imports are performed from a new importer.

func (*Environment) WithImporterRelativeToFile

func (e *Environment) WithImporterRelativeToFile(filePath string) *Environment

WithImporterRelativeToFile returns a new environment where any relative imports will be made from the directory of the provided file path. The provided path can itself be relative (to the current importer directory) or absolute.

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.