bara-lang/docs/API.md

REPL API Reference

JSON REPL Protocol

Start the JSON REPL:

cljnim repl --json

The REPL reads one JSON object per line and responds with one JSON object per line.

Operations

eval

Evaluate a single Clojure form.

Request:

{"op": "eval", "form": "(+ 1 2 3)"}

Response (success):

{
  "status": "ok",
  "result": {
    "type": "unknown",
    "value": "6",
    "printed": "6"
  },
  "meta": {
    "ns": "user",
    "ms": 861.5,
    "form": "(+ 1 2 3)"
  }
}

Response (error):

{
  "status": "error",
  "error": {
    "type": "reader/error",
    "message": "Unterminated list",
    "form": "( + 1 2"
  },
  "meta": {
    "ns": "user",
    "ms": 0.1
  }
}

Optional fields:

• request-id — Correlation ID, echoed in the response
• ns — Target namespace (default: "user")

---

eval-batch

Evaluate multiple forms in sequence.

Request:

{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}

Response:

{
  "status": "ok",
  "results": [
    {"status": "ok", "result": {"type": "var", "name": "f", ...}},
    {"status": "ok", "result": {"printed": "42"}, ...}
  ]
}

---

get-defs

List all vars defined in the current session.

Request:

{"op": "get-defs"}

Response:

{"status": "ok", "defs": ["add", "square"], "ns": "user"}

---

clear

Clear all session definitions.

Request:

{"op": "clear"}

Response:

{"status": "ok", "cleared": true}

---

quit

Exit the REPL.

Request:

{"op": "quit"}

Response:

{"status": "ok", "bye": true}

Response Schema

All responses contain:

• status — "ok" or "error"

On success:

• result — Evaluation result object
  • type — "var", "unknown", etc.
  • printed — String representation of the result
• meta — Metadata
  • ns — Current namespace
  • ms — Execution time in milliseconds
  • form — Original form (if eval)

On error:

• error — Error object
  • type — Error category
  • message — Human-readable message
• meta — Same as success

Human REPL Commands

In human mode (cljnim repl):

Command	Description
:quit, :q	Exit REPL
:help, :h	Show help
:defs	List defined vars
:clear	Clear definitions
:ns	Show current namespace