156 lines
2.4 KiB
Markdown
156 lines
2.4 KiB
Markdown
|
|
[← Back to Index](index.md)
|
|
|
|
---
|
|
|
|
# Bara Lang User Guide
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
- Nim >= 2.0
|
|
- GCC or Clang
|
|
- make
|
|
|
|
### Build from Source
|
|
```bash
|
|
git clone https://gitlab.com/balvatar/lisp-nim.git
|
|
cd lisp-nim
|
|
make build
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
### `compile` — Compile to Nim
|
|
```bash
|
|
./cljnim compile input.clj output.nim
|
|
```
|
|
Generates a `.nim` file from Clojure source.
|
|
|
|
### `run` — Compile and Execute
|
|
```bash
|
|
./cljnim run examples/hello.clj
|
|
```
|
|
Compiles to Nim, then to C, then to a binary, and runs it.
|
|
|
|
### `read` — Parse and Print AST
|
|
```bash
|
|
./cljnim read examples/hello.clj
|
|
```
|
|
Shows the Clojure AST as S-expressions.
|
|
|
|
### `repl` — Interactive REPL
|
|
```bash
|
|
# Human-friendly mode
|
|
./cljnim repl
|
|
|
|
# AI mode (structured JSON)
|
|
./cljnim repl --json
|
|
```
|
|
|
|
## Writing Bara Lang Programs
|
|
|
|
### Basic Syntax
|
|
```clojure
|
|
; Comments start with semicolon
|
|
|
|
; Define a variable
|
|
(def x 42)
|
|
|
|
; Define a function
|
|
(defn greet [name]
|
|
(println "Hello, " name))
|
|
|
|
; Call a function
|
|
(greet "World")
|
|
|
|
; Arithmetic
|
|
(+ 1 2 3) ; => 6
|
|
(* 10 20) ; => 200
|
|
(/ 100 4) ; => 25
|
|
|
|
; Conditionals
|
|
(if (> x 0)
|
|
"positive"
|
|
"non-positive")
|
|
|
|
; Local bindings
|
|
(let [a 10
|
|
b 20]
|
|
(+ a b)) ; => 30
|
|
```
|
|
|
|
### Working with Data
|
|
```clojure
|
|
; Vectors (use Nim seq internally)
|
|
(def nums [1 2 3 4 5])
|
|
|
|
; Keywords
|
|
(def person {:name "Alice" :age 30})
|
|
|
|
; Maps and sets use persistent HAMT data structures
|
|
; with structural sharing and O(log₃₂ n) operations.
|
|
```
|
|
|
|
### Recursion
|
|
```clojure
|
|
(defn factorial [n]
|
|
(if (= n 0)
|
|
1
|
|
(* n (factorial (- n 1)))))
|
|
|
|
(println (factorial 5)) ; => 120
|
|
```
|
|
|
|
## AI REPL Guide
|
|
|
|
The JSON REPL is designed for programmatic interaction.
|
|
|
|
### Start AI REPL
|
|
```bash
|
|
./cljnim repl --json
|
|
```
|
|
|
|
### Evaluate a Form
|
|
```json
|
|
{"op": "eval", "form": "(+ 1 2 3)"}
|
|
```
|
|
Response:
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"result": {"printed": "6"},
|
|
"meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
|
|
}
|
|
```
|
|
|
|
### Batch Evaluation
|
|
```json
|
|
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
|
|
```
|
|
|
|
### List Definitions
|
|
```json
|
|
{"op": "get-defs"}
|
|
```
|
|
Response:
|
|
```json
|
|
{"status": "ok", "defs": ["f"], "ns": "user"}
|
|
```
|
|
|
|
### Clear Session
|
|
```json
|
|
{"op": "clear"}
|
|
```
|
|
|
|
### Exit
|
|
```json
|
|
{"op": "quit"}
|
|
```
|
|
|
|
## Tips
|
|
|
|
- Use `:help` in human REPL for available commands.
|
|
- Definitions in REPL persist across evaluations in the same session.
|
|
- The `--json` flag makes the REPL fully machine-readable.
|