# Host Functions
Schooner ships only pure Scheme primitives by default. Anything
that touches the outside world — logging, reading config, looking
up data, talking to a database — comes from **host functions**:
Elixir functions you register as Scheme procedures via
`Schooner.Host.library/1`.
This guide walks the host-function authoring API: building a
library, the conversion helpers that move between Scheme values
and Elixir terms, foreign payloads for opaque host data, the
callback pattern (Scheme → host → Scheme), and how to map errors
between the two sides.
> **Worked reference:** `Schooner.Time` (in `lib/schooner/time.ex`)
> is the r7rs `(scheme time)` library shipped as an opt-in host
> library. Read it alongside this guide for a concrete, runnable
> example of the patterns described here — a single public
> `library/0` that returns a `%Schooner.Library{}`, a small set of
> primitive impls following the standard ABI, and a sandbox-safe
> canonical name (`["scheme", "time"]`).
## A first host library
```elixir
defmodule MyApp.SchemeLib do
alias Schooner.Host
def lib do
Host.library(
name: ["myapp", "log"],
primitives: [
{"info", 1, &info/1},
{"error", 1, &error_/1}
]
)
end
defp info([msg]) do
text = Host.to_string!(msg, op: "myapp/log/info")
Logger.info(text)
:unspecified
end
defp error_([msg]) do
text = Host.to_string!(msg, op: "myapp/log/error")
Logger.error(text)
:unspecified
end
end
```
The shape of a host primitive is `{name :: binary, arity ::
Schooner.Value.arity_spec, fun :: ([Schooner.Value.t] ->
Schooner.Value.t)}` — the same ABI used by every built-in
primitive Schooner ships with.
To use the library, list it on `Schooner.Environment.new/1`:
```elixir
env = Schooner.Environment.new(libraries: [MyApp.SchemeLib.lib()])
Schooner.eval!(~s|(import (myapp log)) (info "starting")|, env)
```
Because the library has a non-empty name, it is **named** — the
script must `(import (myapp log))` to see its bindings. That's
the sandbox-safe default: the embedder controls the menu, the
script controls which dishes it orders.
## Anonymous libraries (no import needed)
For trivial cases — a single helper, a constant — a host
library with `name: []` is **anonymous**: its bindings are
applied directly to the runtime env at construction time, with
no `(import ...)` required:
```elixir
inject =
Schooner.Host.library(
primitives: [
{"now-ms", 0, fn [] -> System.system_time(:millisecond) end}
]
)
env = Schooner.Environment.new(libraries: [inject])
Schooner.eval!("(now-ms)", env)
# => some integer
```
There is no Scheme syntax that produces an empty library-name
datum, so anonymous libraries are unreachable from script code;
the only path their bindings enter scope is the embedder
listing them. **This is sandbox-loosening** — list anonymous
libraries deliberately.
## Conversion helpers
Schooner does not auto-marshal across the host boundary. Host
functions consume `t:Schooner.Value.t/0` and return
`t:Schooner.Value.t/0`. To go between Scheme values and idiomatic
Elixir terms, use the helpers on `Schooner.Host`.
### Naming convention
- `to_*!/2` — **asserting**: raises `Schooner.Host.TypeError` on
shape mismatch. Takes a keyword list with `:op` so the error
points at the host call site. The bang in the name is the
Elixir convention for "raises rather than returns a tagged
result".
- `to_*/1` — **total**: returns `{:ok, term} | :error`. Use for
the "branch on shape" case.
```elixir
# Asserting — the typical case in a host primitive body
text = Host.to_string!(msg, op: "myapp/log/info")
# Total — when a type mismatch is not an error
case Host.to_string(msg) do
{:ok, text} -> Logger.info(text)
:error -> Logger.info(Schooner.Value.write(msg))
end
```
### Avoid `import Schooner.Host`
Several helper names — `Schooner.Host.to_string/1` and
`Schooner.Host.to_string!/2` — shadow `Kernel.to_string/1`.
**Use `alias Schooner.Host`** and call the helpers as
`Host.to_string!(value, op: "...")`. Don't `import` the module.
### Available accessors
| Helper | Accepts | Returns |
| --- | --- | --- |
| `Schooner.Host.to_integer!/2` | bare exact integer | Elixir integer |
| `Schooner.Host.to_float!/2` | bare Elixir float | Elixir float |
| `Schooner.Host.to_real!/2` | integer / float / rational | Elixir number (rationals coerced to float) |
| `Schooner.Host.to_string!/2` | bare binary (Scheme string) | Elixir binary |
| `Schooner.Host.to_symbol_name!/2` | `{:sym, name}` | Elixir binary (the name) |
| `Schooner.Host.to_char!/2` | `{:char, cp}` | non-negative integer codepoint |
| `Schooner.Host.to_bool!/2` | `true \| false` | Elixir bool |
| `Schooner.Host.to_list!/2` | proper Scheme list | Elixir list |
| `Schooner.Host.to_vector!/2` | `{:vector, tuple}` | Elixir list |
| `Schooner.Host.to_bytevector!/2` | `{:bytevector, binary}` | Elixir binary |
| `Schooner.Host.to_foreign_ref!/2` | `{:foreign, term}` | the wrapped host term |
| `Schooner.Host.to_proc!/2` | closure / primitive / parameter | the value unchanged (callable assertion) |
The `Schooner.Host.to_real!/2` vs `Schooner.Host.to_float!/2`
split is deliberate: `to_float!` rejects integers (the host
should say what it wants), `to_real!` is the lenient "give me
whatever number it is" form.
### Constructors
The same module re-exports `Schooner.Value`'s constructors:
`Host.string/1`, `Host.symbol/1`, `Host.list/1`, `Host.vector/1`,
`Host.foreign/1`, `Host.primitive/3`, etc. Use them instead of
naming the internal tag shape directly — that way future
representation changes only touch `Schooner.Value`, not your
host code.
## Foreign payloads
When the host wants to expose an opaque handle — a `pid`, a
`Reference`, an internal struct — wrap it as a **foreign value**:
```elixir
defmodule MyApp.DbLib do
alias Schooner.Host
def lib(db_pid) do
Host.library(
name: ["myapp", "db"],
values: [
{"connection", Host.foreign(db_pid)}
],
primitives: [
{"query", 2, &query/1}
]
)
end
defp query([conn, sql]) do
pid = Host.to_foreign_ref!(conn, op: "db/query")
sql_text = Host.to_string!(sql, op: "db/query")
rows = MyApp.DB.query(pid, sql_text)
Host.list(Enum.map(rows, &row_to_scheme/1))
end
defp row_to_scheme(row), do: # ...
end
```
Foreign values are **opaque to Scheme**: the script can pass
them around (bind them, return them, store them in pairs and
vectors) but cannot inspect or forge them. `write` redacts the
contents to `#<foreign>`. `eq?` / `eqv?` / `equal?` compare the
wrapped Elixir terms with `===`, so two foreigns wrapping the
same pid are equal.
This is the right vehicle for any "host handle a script needs
to reference but shouldn't see inside".
## Callback pattern (Scheme → host → Scheme)
A host function can receive a Scheme procedure as an argument
and invoke it back via `Schooner.apply!/2`:
```elixir
defp map_over_rows([fun, rows_value]) do
fun = Host.to_proc!(fun, op: "myapp/map-over-rows")
rows = Host.to_list!(rows_value, op: "myapp/map-over-rows")
rows
|> Enum.map(&Schooner.apply!(fun, [&1]))
|> Host.list()
end
```
Used from Scheme:
```scheme
(import (myapp util))
(map-over-rows (lambda (row) (cons "got" row)) '(1 2 3))
;; => (("got" . 1) ("got" . 2) ("got" . 3))
```
`Schooner.apply!/2` works on any procedure value — closures,
primitives, parameters. The callback runs in the same Elixir
process as the outer eval, so it inherits the current
exception/parameter state. A `with-exception-handler` installed
in the outer script catches an error raised three frames deep
across two host hops.
### Continuation barrier (documentation-only in v1)
A Scheme callback that captures a `call/cc` continuation, then
escapes via that continuation **after the host call has
returned**, is unsupported. Schooner v1's `call/cc` is
escape-only; a continuation invoked outside its dynamic extent
already raises a structured error, and the host-boundary case
fires the same guard. So the rule is:
> Capture-and-escape across the host boundary is undefined and
> raises `Schooner.Eval.Error`. Use `(raise ...)` and
> `with-exception-handler` for callbacks that need long-lived
> non-local exit — exceptions cross the host boundary cleanly
> through the existing handler stack.
This is forward-compatible with v2.0's first-class `call/cc`,
which will turn the rule into a hard runtime barrier.
## Error mapping
Two failure modes cross the boundary in opposite directions.
### Host raises a Scheme-catchable error
When you want the script's `with-exception-handler` / `guard` to
see the error, raise a Scheme exception via `Schooner.Error`:
```elixir
defp query([conn, sql]) do
pid = Host.to_foreign_ref!(conn, op: "db/query")
sql_text = Host.to_string!(sql, op: "db/query")
case MyApp.DB.query(pid, sql_text) do
{:ok, rows} ->
Host.list(Enum.map(rows, &row_to_scheme/1))
{:error, reason} ->
raise Schooner.Error,
value:
Schooner.Value.error_object(
:user,
Host.string("db query failed"),
[Host.foreign(reason)]
)
end
end
```
The script catches it like any other:
```scheme
(guard (e ((error-object? e) (handle-failure e)))
(query connection "SELECT ..."))
```
### Host-side type errors are not script-catchable
`Schooner.Host.TypeError` (raised by `to_*!/2` helpers) and
`Schooner.Primitive.Error` (raised by built-in primitive type /
arity / domain checks) both surface to the **host**, not to the
script. They bubble out of `Schooner.eval!/2` as Elixir
exceptions, or land in the `{:error, _}` arm of `Schooner.eval/2`.
This is deliberate: a sandboxed script must not be able to paper
over its own type errors. If you want a host primitive to
produce a *script-catchable* failure, use the `Schooner.Error`
pattern above; if you want it to be a host-side bug report,
use `Schooner.Host.TypeError` (which is what the assertion
helpers produce automatically).
## Tying it all together
```elixir
defmodule MyApp.Embed do
alias Schooner.Host
def env(db_pid) do
Schooner.Environment.new(
standard_libraries: :default,
libraries: [
MyApp.SchemeLib.lib(),
MyApp.DbLib.lib(db_pid)
],
pre_imports: [
["scheme", "base"], # define, length, string-append, number->string ...
["myapp", "log"] # info, error
]
)
end
def run_rule(source, db_pid) do
Schooner.eval(source, env(db_pid))
end
end
```
A script the host hands to `run_rule/2`:
```scheme
(import (myapp db))
(define rows (query connection "SELECT id FROM users WHERE active = TRUE"))
(info (string-append "got " (number->string (length rows)) " rows"))
rows
```
- `define`, `string-append`, `number->string`, `length` are in
scope without import (pre-imported `(scheme base)`).
- `info` is in scope without import (pre-imported `(myapp log)`).
- `query` and `connection` are in scope after the explicit
`(import (myapp db))`.
Decide which surface to pre-import based on trust. For untrusted
input you might lock down the standard libraries to a tighter
set (`standard_libraries: [:base, :char]`) so the script can't
even *attempt* to import things you don't want to expose — see
[Sandbox](sandbox.md).
