:sig
function unit_load(path : string) module

:params
path : the unit path to load

:returns
A `module` handle for the unit.

:content
`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 the same objects on both sides: the callee receives the dval you passed in, and the result it returns is what you get.

## 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.

:errors
A path that does not resolve, a unit that fails to compile, or a name the target does not export raises a runtime error that aborts the request. Use `unit_info()` first when a unit's availability is genuinely optional.

:example capy render
var target := unit_load("/tests/capy-module-target.capy")
print(target.default_input(), "\n")

:example capy render reuse one handle for several calls
var target := unit_load("/tests/capy-module-target.capy")
print(string(target.echo(name: "Ada").name), "\n")
print(string(target.echo(name: "Grace").name), "\n")

:example capy render call by a name held in a value
var target := unit_load("/tests/capy-module-target.capy")
var wanted := "echo"
print(string(call(target, wanted, name: "Katherine").name), "\n")

:see-group
units

:see
component
handler/component
