Capy-Bearer Documentation

Description

unit_load() loads a unit and returns a handle you can call exported functions on. It is the way one unit calls another unit's code, as opposed to component(), which renders another unit's output.

The target unit must publish the names it offers with #exports. Anything not exported is invisible to callers.

Calling through the handle

Two spellings do the same thing. Member syntax is the readable one:

var target := unit_load("/tests/capy-module-target.capy") var result := target.echo({name: "Ada"})

call() is the explicit form, and the one to use when the function name is itself a value:

var result := call(target, "echo", {name: "Ada"})

Every exported function takes at most one dval input and returns a dval. Calling with no argument passes an empty dval.

When to load a handle, and when not to

Load a handle once and reuse it when several calls hit the same unit — the handle carries the resolved, compiled unit, so repeat calls skip the lookup.

For a single call, unit_call(path, name, input) does the same work in one step without a handle. Prefer it for one-offs.

What a handle is

A module value is opaque: there is nothing inside it to read, print, or compare. It is request-local — a handle is valid for the request that created it and cannot be stored and reused later. It copies across dval boundaries, so passing one around within a request is safe.

Values crossing a call are copied, not shared. Mutating the dval you passed in does not affect what the callee saw, and mutating the result does not reach back into the callee.

Related entry points

unit_render() runs a unit's RENDER handler and writes its output to the response. unit_info() reports a unit's exports and compile state; unit_compile() compiles a unit without calling it.