# calog example scripts

Small, runnable programs for the `calog` command-line runner (`bin/calog`). Each one is
verified to run against the built binary. They double as a tour of the engines and the
built-in libraries.

## Running

```sh
make                                                   # builds bin/calog (among others)

bin/calog examples/scripts/languages/lua.lua           # run by extension
bin/calog examples/scripts/apps/uuidGen                # no extension -> searches .lua/.js/.nut/.bas/.be/.scm/.wren
bin/calog examples/scripts/multifile/producer.js \
          examples/scripts/multifile/consumer.lua      # several files share one runtime
```

Conventions every example follows:

- **`calogPrint(...)`** writes to stdout (calog-prefixed so it never clashes with an
  engine's own `print`/keyword; on Wren it is `Calog.call("calogPrint", [...])`).
- **`calogExit([code])`** ends the run. calog is event-driven -- a script's top level
  finishing does not exit the process (it may still have timers/subscriptions live), so a
  script asks to exit explicitly. `Ctrl-C` also tears things down cleanly.
- Extensions map to engines: `.lua .js .nut .bas .be .scm .wren`.

## `languages/` -- one guided tour per engine

| file | shows |
|---|---|
| `lua.lua` | Lua 5.4: locals, a function, a numeric `for` building a table, then crypto + json natives |
| `javascript.js` | JavaScript (QuickJS, ES2023): `const`/`let`, arrow fns, `Array.map`/`filter`, template literals, JSON round-trip |
| `squirrel.nut` | Squirrel: locals, a function, `foreach` over an array, a table, a small class |
| `mybasic.bas` | my-basic: variables, a `FOR..NEXT` sum, `IF..THEN..ELSE`, plus crypto + kv |
| `berry.be` | Berry (Python-like): a `def`, a list built with a `for`, a map, then json + uuid |
| `scheme.scm` | s7 Scheme: a recursive factorial, list build + map, string ops (all in one `(begin ...)`) |
| `wren.wren` | Wren: a class, a `List`, and every native reached via `Calog.call(name, [args])` |

## `libraries/` -- one focused example per built-in library

| file | library / shows |
|---|---|
| `crypto.lua` | crypto: SHA-256/SHA-1, HMAC, base64 + hex round-trips, UUID, random bytes |
| `cryptoInJs.js` | crypto from JavaScript |
| `json.lua` | json: parse a nested doc, read fields, stringify a table |
| `jsonInBerry.be` | json from Berry |
| `kv.lua` | kv store: set / get / has / keys / delete |
| `kvInScheme.scm` | kv from s7 Scheme |
| `fs.lua` | fs: mkdir/write/append/read/stat/list/remove, all in a unique `/tmp` dir |
| `time.lua` | time: `timeNow`, and measuring a `timeSleep` with `timeMonotonic` |
| `timer.lua` | timer (Lua callbacks): a `timerAfter` one-shot + a self-cancelling `timerEvery` |
| `timerInMyBasic.bas` | timer callbacks **in my-basic** -- the our-basic fork makes `def`/lambda first-class |
| `database.lua` | db: an in-memory SQLite table, bound-parameter inserts, a query + an aggregate |
| `export.lua` | export: publish a function, call it by name (and, on Lua, by bare name) |
| `pubsub.lua` | pubsub: two handlers subscribe, publish delivers to both, then unsubscribe |
| `task.lua` | task: `taskSelf`, spawn a sibling child, `taskCount` |
| `net.lua` | net: a UDP echo over loopback between a spawned listener and a sender |
| `http.lua` | http: self-contained -- a spawned child runs a one-shot HTTP/1.1 server, then `httpGet`s it |
| `ssh.lua` | ssh/sftp: a documented, safe-to-run template (prints guidance if no server is configured) |

## `polyglot/` -- several languages sharing one runtime

| file | shows |
|---|---|
| `exportAcrossEngines.lua` | Lua exports a function; a spawned **JavaScript** task calls it |
| `pubsubAcrossEngines.lua` | Lua subscribes to a topic; a spawned **JavaScript** task publishes to it |
| `sharedKv.lua` | Lua seeds the shared kv store; a spawned **JavaScript** task reads it back and mutates it |
| `taskFanout.lua` | one Lua script spawns a task on **five** different engines, each printing in its own language |

## `multifile/` -- multiple script files in one run

Files listed on the `calog` command line run **concurrently in one process** and share the
same runtime (kv store, pubsub bus, exports). One `calogExit()` from any file ends the run.

```sh
bin/calog examples/scripts/multifile/producer.js examples/scripts/multifile/consumer.lua
```

| file | role |
|---|---|
| `producer.js` | (JavaScript) writes shared data to kv, then signals `"ready"` on the pubsub bus after a short delay |
| `consumer.lua` | (Lua) subscribes to `"ready"`, and on the signal reads the shared kv data, prints it, and exits |

## `apps/` -- tiny end-to-end tools

| file | shows |
|---|---|
| `uuidGen.lua` | print five random UUIDs |
| `hashText.lua` | write text to a temp file, read it back, print its SHA-256/SHA-1/length, clean up |
| `wordCount.js` | word-count a paragraph (totals, uniques, top frequencies), emit the summary as JSON |