vibes

func DeclareNonMutating ¶ added in v0.60.0

func DeclareNonMutating(v value.Value) value.Value

DeclareNonMutating records a builtin's promise that no invocation of it writes to any container reachable from its receiver, arguments, keyword arguments, block, or from any execution's roots, and returns it. Allocating a container and filling it in is not such a write: the promise covers only state something else can already reach, so building a result and returning it keeps it. Script code the builtin drives through a block is not covered and does not need to be.

This is a safety promise, not a performance hint. The runtime stops invalidating its memoized memory-estimator walk around calls to a builtin that makes it, so a declaration that is not true leaves an execution accounting for less memory than it actually holds, and that execution then allocates past the MemoryQuotaBytes it was configured with. A builtin that declares nothing keeps the existing conservative behavior, which is slower and correct; omission costs speed, never correctness.

The promise is between an embedder and itself rather than between the sandbox and untrusted script. A host builtin already runs arbitrary Go in the embedding process and can allocate without bound and ignore every quota today, so declaring grants no capability a host lacked, and script code can neither observe the declaration nor reach it. It widens no sandbox boundary. What it does is switch off a backstop the host then has to honor itself.

Apply it to a builtin whose whole body is known, and re-check it when that body changes.

func DeclareNonRetaining ¶ added in v0.60.0

func DeclareNonRetaining(v value.Value) value.Value

DeclareNonRetaining records a builtin's promise that no invocation of it stores, anywhere that outlives the invocation, a reference to any Value it receives (receiver, arguments, keyword arguments, block) or returns, or to any container reachable from one -- and, symmetrically, that no value it returns or yields shares storage the host already holds (a wrapper built over a package-level map or an adapter field is a retained reference even though the invocation itself stored nothing). It returns the value. Package-level variables, fields on the adapter, closure captures, channels, caches and anything handed to another goroutine all count as outliving the invocation. So does keeping a container reached through an argument rather than the argument itself.

The boundary consults this promise (#1210): a declaring builtin's inputs skip the retention marking, its return skips the detach copy, and blocks it drives through Execution.CallBlock exchange values without boundary copies -- which is exactly why an untrue declaration is a live aliasing channel, not just an accounting error. A later change will also use it to scope the memory estimator's walk memo across a host call (#1199).

It is stated as a safety promise rather than a hint because of what it will mean once consulted: an execution calling a builtin that makes it keeps accounting for memory privately, so an untrue declaration would let a container the host kept be mutated afterwards without that execution observing the change, and its quota would then admit allocations it should have refused. Declare it only where that is true, not on the reasoning that it currently costs nothing.

It is a separate promise from DeclareNonMutating and neither implies the other. A builtin that only reads its arguments but files one away for later is non-mutating and not non-retaining; one that overwrites a slot in its receiver and keeps nothing is the reverse.

func MemberCompletionNames ¶ added in v0.50.0

func MemberCompletionNames() map[string][]string

MemberCompletionNames returns the builtin member-method names per receiver type (string, array, hash, int, float, money, duration, time), for editor tooling such as LSP completion.

func NewAutoBuiltin ¶

func NewAutoBuiltin(name string, fn BuiltinFunc) value.Value

NewAutoBuiltin returns a builtin function Value that auto-invokes without parentheses.

package main

import (
	"context"
	"fmt"

	"github.com/mgomes/vibescript/vibes"
	"github.com/mgomes/vibescript/vibes/value"
)

func main() {
	engine := vibes.MustNewEngine(vibes.Config{StepQuota: 50_000})
	script, err := engine.Compile(`def run()
  tenant
end`)
	if err != nil {
		panic(err)
	}
	tenant := vibes.NewAutoBuiltin("tenant", func(_ *vibes.Execution, _ value.Value, _ []value.Value, _ map[string]value.Value, _ value.Value) (value.Value, error) {
		return value.NewString("acme"), nil
	})
	result, err := script.Call(
		context.Background(),
		"run",
		nil,
		vibes.CallOptions{
			Globals: map[string]value.Value{"tenant": tenant},
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.String())
}

Output:
acme

func NewBuiltin ¶

func NewBuiltin(name string, fn BuiltinFunc) value.Value

NewBuiltin returns a builtin function Value.

package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/mgomes/vibescript/vibes"
	"github.com/mgomes/vibescript/vibes/value"
)

func main() {
	engine := vibes.MustNewEngine(vibes.Config{StepQuota: 50_000})
	script, err := engine.Compile(`def shout(word)
  upcase(word)
end`)
	if err != nil {
		panic(err)
	}
	upcase := vibes.NewBuiltin("upcase", func(_ *vibes.Execution, _ value.Value, args []value.Value, _ map[string]value.Value, _ value.Value) (value.Value, error) {
		return value.NewString(strings.ToUpper(args[0].String())), nil
	})
	result, err := script.Call(
		context.Background(),
		"shout",
		[]value.Value{value.NewString("hi")},
		vibes.CallOptions{
			Globals: map[string]value.Value{"upcase": upcase},
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.String())
}

Output:
HI

func NewTypedBuiltin ¶ added in v0.60.0

func NewTypedBuiltin(name string, fn BuiltinFunc, sig Signature) (value.Value, error)

NewTypedBuiltin returns a builtin function Value that publishes sig to the checker and validates calls against it at runtime. The value can be registered as an engine builtin, passed as a call-option global, or exposed as a capability method.

func QuotaProfileNames ¶ added in v0.60.0

func QuotaProfileNames() []string

QuotaProfileNames returns the profile names in ascending order of generosity.