# calog script API reference

Every function below is a **native** that calog registers into each engine, so a script in
any language can call it. This reference covers the natives the `calog` runner and its
libraries expose. (For the C embedding API -- `calogCreate`, `calogRegister`, `calogFnInvoke`,
etc. -- see the README and `src/calog.h`.)

## Conventions

- **Calling syntax per engine.** Most engines call a native by its bare name --
  `cryptoUuid()`, `kvSet("k", 1)`. Two differ:
  - **Wren**: `Calog.call("name", [args])`, e.g. `Calog.call("kvSet", ["k", 1])`.
  - **Scheme (s7)**: s-expression form, `(kvSet "k" 1)`.
- **Output & exit** (provided by the `calog` runner): `calogPrint(...)` writes to stdout;
  `calogExit([code])` tears everything down and exits. calog is event-driven, so a script
  must call `calogExit` (or be interrupted) to end -- a finished top level does not exit.
- **Values.** Arguments and results marshal through one canonical type: nil, bool, integer,
  real, string, list, and map (keyed record). Strings are **binary-safe** (may contain
  embedded NULs) everywhere the underlying library allows it.
- **Handles** (db connections, sockets, ssh sessions) are opaque values owned by the context
  that created them; do not share a live handle across contexts.
- **Callbacks.** Natives that take a *function* argument (`psSubscribe`, `timerAfter`,
  `timerEvery`, `calogExport`) accept a first-class function value. All engines support this,
  including my-basic (a top-level `def` or `lambda`; see `vendor/ourbasic`).
- **Availability.** Every library in this reference is compiled into `bin/calog`: crypto,
  json, kv, fs, time, timer, export, pubsub, task, net (TCP / UDP / ENet), db (SQLite /
  PostgreSQL / MySQL), http, and ssh. ssh needs a reachable server; http needs a reachable
  endpoint.

---

## Runner (`calog` binary)

| Function | Description |
|---|---|
| `calogPrint(...)` | Write each argument to stdout, space-separated, with a trailing newline. |
| `calogExit([code])` | Tear down the runtime and exit the process with `code` (default `0`). |

## crypto

Binary-safe cryptographic primitives over OpenSSL.

| Function | Description |
|---|---|
| `cryptoHashSha256(data) -> hex` | SHA-256 as a 64-char lowercase hex digest. |
| `cryptoHashSha1(data) -> hex` | SHA-1 as a 40-char lowercase hex digest. |
| `cryptoHmacSha256(key, data) -> hex` | HMAC-SHA-256 as 64-char lowercase hex. |
| `cryptoRandomBytes(count) -> bytes` | `count` cryptographically-random bytes (binary string). |
| `cryptoBase64Encode(data) -> text` | Base64-encode. |
| `cryptoBase64Decode(text) -> data` | Base64-decode (trailing whitespace tolerated). |
| `cryptoHexEncode(data) -> text` | Lowercase hex encode. |
| `cryptoHexDecode(hexText) -> data` | Hex decode (case-insensitive). |
| `cryptoUuid() -> string` | A random RFC 4122 version-4 UUID string. |

## db

SQL over SQLite, PostgreSQL, and MySQL/MariaDB. Parameters are always **bound** (never
string-spliced), so queries are injection-safe. Values marshal as: NULL <-> nil, integers/
reals as-is, text and BLOBs as binary-safe strings.

| Function | Description |
|---|---|
| `dbOpen(driver, conn) -> handle` | Open a connection. `driver` is `"sqlite"`, `"postgres"`, or `"mysql"`. `conn` is a SQLite path or `":memory:"`, a libpq conninfo, or a MySQL `key=value ...` string. |
| `dbExec(handle, sql, ...params) -> rowsAffected` | Run a non-query statement with bound params; returns rows affected. |
| `dbQuery(handle, sql, ...params) -> rows` | Run a query; returns a list of `{column: value}` row maps. |
| `dbClose(handle)` | Close the connection. |

## export

Share a function by name across contexts and engines.

| Function | Description |
|---|---|
| `calogExport(name, fn)` | Publish function `fn` under a global `name`. |
| `calogUnexport(name)` | Remove an exported name. |
| `calogCall(name, ...args) -> result` | Call an exported function by name -- works in **every** engine. (On hook engines -- Lua/JS/Squirrel/s7 -- an export is also reachable by its bare name.) |

## fs

POSIX filesystem access. A failed operation raises a catchable script error carrying
`strerror(errno)`.

| Function | Description |
|---|---|
| `fsRead(path) -> string` | Read a whole file (binary-safe). |
| `fsWrite(path, data)` | Create/truncate and write `data`. |
| `fsAppend(path, data)` | Create if absent, append at the end. |
| `fsExists(path) -> bool` | Whether the path exists. |
| `fsRemove(path)` | Unlink a file. |
| `fsMkdir(path)` | Create one directory level (existing dir is OK). |
| `fsList(path) -> list` | Entry name strings, excluding `.` and `..`. |
| `fsStat(path) -> map` | `{size, isDir, isFile, mtime}`, or nil if the path is absent. |

## http

Minimal HTTP/1.1 client over `http://` and `https://`. Each call is its own connection
(`Connection: close`); redirects are not followed. `https://` verifies the server certificate
against the system CA store by default.

| Function | Description |
|---|---|
| `httpGet(url) -> map` | GET a URL. Returns `{status, body, headers}` (headers keyed by lowercased name). |
| `httpRequest(opts) -> map` | `opts` is `{method (default "GET"), url, headers (map), body, insecure (bool)}`. `insecure=true` skips TLS verification. Returns `{status, body, headers}`. |

## json

| Function | Description |
|---|---|
| `jsonParse(text) -> value` | Parse JSON: object -> map, array -> list, number -> int or real, string, true/false, null -> nil. |
| `jsonStringify(value) -> text` | Serialize a value to compact JSON text. |

## kv

A process-wide, thread-safe store shared by every context and engine. Holds **data only** (a
function value is rejected). Keys are binary-safe.

| Function | Description |
|---|---|
| `kvSet(key, value)` | Store a deep copy of `value` under `key` (replaces any existing). |
| `kvGet(key) -> value` | A deep copy of the stored value, or nil if absent. |
| `kvHas(key) -> bool` | Whether the key is present. |
| `kvDelete(key)` | Remove the key (no error if absent). |
| `kvKeys() -> list` | A list of the stored keys (strings). |

## net

Three first-class transports -- **TCP**, **UDP**, and **ENet** (reliable/ordered delivery
over UDP) -- all always available. Payloads are binary-safe strings. Blocking calls
(`tcpAccept`/`tcpRecv`/`udpRecvFrom`/`enetService`) stall only the calling context's thread.

TCP and UDP:

| Function | Description |
|---|---|
| `tcpConnect(host, port) -> handle` | Connect to a TCP server. |
| `tcpListen(port) -> handle` | Listen on a TCP port. |
| `tcpAccept(handle) -> handle` | Block for a client; returns a connection handle. |
| `tcpSend(handle, data) -> bytesSent` | Send all of `data`. |
| `tcpRecv(handle, maxBytes) -> data` | Read up to `maxBytes`; nil at end of stream. |
| `tcpClose(handle)` | Close a socket. |
| `udpOpen(port) -> handle` | Open a UDP socket (`port` 0 = ephemeral). |
| `udpSendTo(handle, host, port, data) -> bytesSent` | Send a datagram. |
| `udpRecvFrom(handle, maxBytes) -> map` | Receive one datagram: `{data, host, port}`. |
| `udpClose(handle)` | Close a UDP socket. |

ENet (reliable UDP -- ordered, reliable channels over UDP):

| Function | Description |
|---|---|
| `enetHost(port, maxPeers) -> hostHandle` | Create an ENet host. |
| `enetConnect(hostHandle, host, port, channels) -> peerHandle` | Initiate a connection to a peer. |
| `enetService(hostHandle, timeoutMs) -> event` | Poll for one event within `timeoutMs`. Returns `{type, ...}` where `type` is `"none"`, `"connect"`, `"receive"` (with `peer`, `channel`, `data`), or `"disconnect"`. |
| `enetSend(peerHandle, channel, data, reliable)` | Queue a packet on a channel; `reliable` is a bool. |
| `enetDisconnect(peerHandle)` | Begin disconnecting a peer. |
| `enetClose(hostHandle)` | Destroy an ENet host. |

## pubsub

Deliver a message to every subscriber of a topic, across contexts and engines. Delivery is
synchronous; each subscriber runs on its own context's thread and gets a deep copy of the
message. Keep publish graphs acyclic.

| Function | Description |
|---|---|
| `psSubscribe(topic, fn) -> id` | Register `fn` to receive messages published on `topic`. |
| `psUnsubscribe(id)` | Drop the subscription with that id. |
| `psPublish(topic, msg) -> count` | Deliver a copy of `msg` to every subscriber; returns how many were invoked. |

## ssh

SSH/SFTP over libssh2. Requires a reachable SSH server. Payloads are binary-safe.

| Function | Description |
|---|---|
| `sshConnect(host[, port]) -> handle` | Connect (port defaults to 22). |
| `sshAuthPassword(handle, user, password) -> bool` | Password authentication. |
| `sshAuthKey(handle, user, privateKeyPath[, publicKeyPath, passphrase]) -> bool` | Public-key authentication. |
| `sshExec(handle, command) -> map` | Run a remote command: `{stdout, stderr, exitCode}`. |
| `sshClose(handle)` | Close the session. |
| `sftpGet(handle, remotePath) -> data` | Read a remote file whole (binary-safe). |
| `sftpPut(handle, remotePath, data)` | Create/truncate a remote file (mode 0644). |
| `sftpList(handle, path) -> list` | `[{name, size, isDir}, ...]`. |
| `sftpStat(handle, path) -> map` | `{size, isDir}`, or nil if the path is missing. |
| `sftpRemove(handle, path)` | Remove a remote file. |
| `sftpMkdir(handle, path)` | Create a remote directory (mode 0755). |

## task

Launch and manage other calog script contexts. Tasks are fire-and-forget: a spawned context
runs on its own thread; results come back through host natives or the shared kv/pubsub. A
task is owned by the context that spawned it, and only that owner may `taskEval`/`taskClose`.

| Function | Description |
|---|---|
| `taskSpawn(engine, code) -> handle` | Run a code string on a named engine (`"lua"`, `"javascript"`, `"squirrel"`, `"mybasic"`, `"berry"`, `"scheme"`, `"wren"`). |
| `taskLoad(baseName) -> handle` | Launch a script *file* (engine chosen by extension). |
| `taskEval(handle, code)` | Feed more code into a running task (runs on its thread). |
| `taskClose(handle)` | Stop a task (cooperative: waits for its thread to exit). |
| `taskSelf() -> id` | The calling script's own context id. |
| `taskCount() -> n` | Number of tasks this library currently holds open. |

## time

| Function | Description |
|---|---|
| `timeNow() -> real` | Wall-clock epoch seconds, fractional (CLOCK_REALTIME). |
| `timeMonotonic() -> real` | Seconds from an unspecified origin (CLOCK_MONOTONIC); use for intervals. |
| `timeSleep(ms)` | Block the calling context for `ms` milliseconds. |

## timer

One background thread drives every timer; each callback runs on the context that created the
timer.

| Function | Description |
|---|---|
| `timerAfter(ms, fn) -> id` | Fire `fn` once, `ms` milliseconds from now. |
| `timerEvery(ms, fn) -> id` | Fire `fn` every `ms` milliseconds. |
| `timerCancel(id)` | Stop a pending or repeating timer. |