Custom Functions

Custom functions let the host application expose Go logic to FQL scripts. Functions can be registered individually or organized into namespaces.

Registered namespace segments and host-function names are case-insensitive in FQL and have one canonical lowercase qualified spelling in registries, documentation, and tooling. Register each symbol once; uppercase and mixed-case registrations are normalized for compatibility.

Registering functions

The most direct way to add functions is WithFunctionsRegistrar. The callback receives a runtime.Namespace where you register functions by arity:

example.go

read-only

engine, err := ferret.New( ferret.WithFunctionsRegistrar(func(ns runtime.Namespace) { ns.Function().A0().Add("now_unix", func(ctx context.Context) (runtime.Value, error) { return runtime.NewInt(int(time.Now().Unix())), nil }) ns.Function().A1().Add("double", func(ctx context.Context, arg runtime.Value) (runtime.Value, error) { n, err := runtime.CastArg[runtime.Int](arg, 0) if err != nil { return nil, err } return runtime.NewInt(int(n * 2)), nil }) }), )

Scripts can then call these functions directly:

example.fql

read-only

return { timestamp: now_unix(), doubled: double(21) }

Function signatures

Ferret provides typed function signatures for each arity:

Builder method	Go signature	FQL call
`A0()`	`func(ctx) (Value, error)`	`fn()`
`A1()`	`func(ctx, arg) (Value, error)`	`fn(x)`
`A2()`	`func(ctx, arg1, arg2) (Value, error)`	`fn(x, y)`
`A3()`	`func(ctx, arg1, arg2, arg3) (Value, error)`	`fn(x, y, z)`
`A4()`	`func(ctx, arg1, arg2, arg3, arg4) (Value, error)`	`fn(a, b, c, d)`
`Var()`	`func(ctx, args ...Value) (Value, error)`	`fn(a, b, ...)`

Fixed-arity functions (A0 through A4) automatically validate the argument count. Variadic functions (Var) receive a slice and must validate the count themselves.

Namespaces

Use WithNamespace with a library builder to create a named group of functions:

example.go

read-only

lib := runtime.NewLibrary() ns := lib.Namespace("crypto") ns.Function().A1().Add("md5", func(ctx context.Context, arg runtime.Value) (runtime.Value, error) { input := arg.String() hash := md5.Sum([]byte(input)) return runtime.NewString(hex.EncodeToString(hash[:])), nil }) ns.Function().A1().Add("sha256", func(ctx context.Context, arg runtime.Value) (runtime.Value, error) { input := arg.String() hash := sha256.Sum256([]byte(input)) return runtime.NewString(hex.EncodeToString(hash[:])), nil }) engine, err := ferret.New( ferret.WithNamespace(lib), )

Scripts call these as:

example.fql

read-only

return { md5: crypto::md5("hello"), sha: crypto::sha256("hello") }

Namespaces can be nested. A namespace created with ns.Namespace("sub") produces functions accessible as crypto::sub::function_name.

Argument validation

For variadic functions, use the validation helpers from the runtime package to check argument count and types:

example.go

read-only

fns.Var().Add("concat_with", func(ctx context.Context, args ...runtime.Value) (runtime.Value, error) { // At least 2 arguments: separator + one or more values if err := runtime.ValidateArgs(args, 2, runtime.MaxArgs); err != nil { return nil, err } separator, err := runtime.CastArg[runtime.String](args[0], 0) if err != nil { return nil, err } parts := make([]string, 0, len(args)-1) for _, arg := range args[1:] { parts = append(parts, arg.String()) } return runtime.NewString(strings.Join(parts, string(separator))), nil })

Type casting helpers

The runtime package provides generic casting functions that return typed values with clear error messages:

Helper	Purpose
`CastArg[T](arg, index)`	Cast a single argument to type `T`
`CastArgAt[T](args, index)`	Cast argument at position in a slice
`CastArgs[T](args)`	Cast all arguments to the same type
`CastArgs2[T1, T2](a, b)`	Cast two arguments to different types
`CastArgs3[T1, T2, T3](a, b, c)`	Cast three arguments to different types

Arity and type validation

Helper	Purpose
`ValidateArgs(args, min, max)`	Check argument count is within range
`ValidateArgsType(args, types...)`	Check each argument matches expected type
`ValidateArgType(arg, pos, types...)`	Check a single argument matches one of the expected types

Merging pre-built function sets

If you have a *runtime.Functions object built separately, merge it into the engine with WithFunctions:

example.go

read-only

builder := runtime.NewFunctionsBuilder() builder.A1().Add("reverse", reverseFunc) builder.A2().Add("repeat", repeatFunc) funcs, err := builder.Build() if err != nil { log.Fatal(err) } engine, err := ferret.New( ferret.WithFunctions(funcs), )

Complete example

A custom namespace that provides string transformation functions:

example.go

read-only

package main import ( "context" "fmt" "log" "strings" "github.com/MontFerret/ferret/v2" "github.com/MontFerret/ferret/v2/pkg/runtime" "github.com/MontFerret/ferret/v2/pkg/source" ) func main() { lib := runtime.NewLibrary() ns := lib.Namespace("text") ns.Function().A1().Add("title_case", func(ctx context.Context, arg runtime.Value) (runtime.Value, error) { return runtime.NewString(strings.Title(arg.String())), nil }) ns.Function().A2().Add("wrap", func(ctx context.Context, text, wrapper runtime.Value) (runtime.Value, error) { w := wrapper.String() return runtime.NewString(w + text.String() + w), nil }) ns.Function().Var().Add("join", func(ctx context.Context, args ...runtime.Value) (runtime.Value, error) { if err := runtime.ValidateArgs(args, 1, runtime.MaxArgs); err != nil { return nil, err } parts := make([]string, len(args)) for i, arg := range args { parts[i] = arg.String() } return runtime.NewString(strings.Join(parts, "")), nil }) engine, err := ferret.New( ferret.WithNamespace(lib), ) if err != nil { log.Fatal(err) } defer engine.Close() output, err := engine.Run( context.Background(), source.NewAnonymous(` return { titled: text::title_case("hello world"), wrapped: text::wrap("content", "**"), joined: text::join("a", "b", "c") } `), ) if err != nil { log.Fatal(err) } fmt.Println(string(output.Content)) // {"joined":"abc","titled":"Hello World","wrapped":"**content**"} }

Next steps

Runtime modules Modules Install, configure, register, and manage modules in an embedded runtime. Go types Host Values Implement Go types that FQL scripts can hold, access, iterate, query, and dispatch to. Runtime setup Runtime Configuration Control the standard library, logging, encoding, concurrency, and file system access. Guide Develop a Ferret module Build a module with functions, host values, and lifecycle hooks.