219 lines
11 KiB
Markdown
219 lines
11 KiB
Markdown
# 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. |
|