unit_call
lib callCapy
function unit_call(target : string, props : as any = {}, request : capture any) anyDescription
unit_call calls an exported function in a unit. A form without props sends an empty map as the function input.
target names the unit and its export in one string, the same way component(), component_render(), and task_execute() do. It splits on the first colon, so a handler name such as COMPONENT:CARD still works after a unit path.
Pass props as map entries, a map, an any, or a scalar. unit_call(target, greeting: "hello") is equivalent to unit_call(target, {greeting: "hello"}). A string or number becomes a scalar any.
The input is the caller's object and the result is the callee's object; nothing is copied. Handlers in the same request share the request value.
An #import alias calls the same exported functions with the path written once and the export name checked at compile time. Prefer an import when the target is fixed.
Call a handler
A handler target includes its full handler name, such as "path.capy:COMPONENT:CARD" or "path.capy:RENDER:DETAIL". It writes output directly and returns none, not the printed text. Use component() when you need a component's output as a string.
unit_call("/doc/examples/card.capy:COMPONENT:CARD", title: "News")Render and component dispatch run the target unit's ONCE hook before its first output invocation in the request. Calling an exported data function does not run ONCE. Both forms can trigger INIT when they first load the unit.
Parameters
request : the caller's request, captured when omitted
target : compound "unit path:exported function name"
props : function input
Return Values
The exported function result, or none for a handler invocation.
Errors
For an exported function call, a missing unit, unavailable export, or incompatible signature stops the request with a runtime error. A missing handler instead prints an error, returns none, and lets the caller continue. Dynamic calls do not provide the compile-time export checks of an import.
Example
Capy
var direct := unit_call("/doc/examples/call_target.capy:echo", "hello")
var compound := unit_call("/doc/examples/call_target.capy:echo", greeting: "hello")
print(direct, " ", compound.greeting, "\n")
Output
hello hello