Clojure

# Clojure Development Instructions

Code Evaluation Tool usage

“Use the repl” means to use the **Evaluate Clojure Code** tool from Calva Backseat Driver. It connects you to the same REPL as the user is connected to via Calva.

- Always stay inside Calva's REPL instead of launching a second one from the terminal.

- If there is no REPL connection, ask the user to connect the REPL instead of trying to start and connect it yourself.

JSON Strings in REPL Tool Calls

Do not over-escape JSON arguments when invoking REPL tools.

{
  "namespace": "<current-namespace>",
  "replSessionKey": "cljs",
  "code": "(def foo \"something something\")"
}

Docstrings in `defn`

Docstrings belong immediately after the function name and before the argument vector.

(defn my-function
  "This function does something."
  [arg1 arg2]
  ;; function body
  )

- Define functions before they are used—prefer ordering over `declare` except when truly necessary.

Interactive Programming (a.k.a. REPL Driven Development)

Align Data Structure Elements for Bracket Balancing

**Always align multi-line elements vertically in all data structures: vectors, maps, lists, sets, all code (since Clojure code is data). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.**

;; ❌ Wrong - misaligned vector elements
(select-keys m [:key-a
                :key-b
               :key-c])  ; Misalignment → incorrect ] placement

;; ✅ Correct - aligned vector elements
(select-keys m [:key-a
                :key-b
                :key-c])  ; Proper alignment → correct ] placement

;; ❌ Wrong - misaligned map entries
{:name "Alice"
 :age 30
:city "Oslo"}  ; Misalignment → incorrect } placement

;; ✅ Correct - aligned map entries
{:name "Alice"
 :age 30
 :city "Oslo"}  ; Proper alignment → correct } placement

**Critical**: The bracket balancer relies on consistent indentation to determine structure.

REPL Dependency Management

Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sessions.

(require '[clojure.repl.deps :refer [add-libs]])
(add-libs '{dk.ative/docjure {:mvn/version "1.15.0"}})

- Dynamic dependency loading requires Clojure 1.12 or later

- Perfect for library exploration and prototyping

Checking Clojure Version

*clojure-version*
;; => {:major 1, :minor 12, :incremental 1, :qualifier nil}

REPL Availability Discipline

**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors indicating that the REPL is unavailable, stop immediately and inform the user. Let the user restore REPL before continuing.

#### Why This Matters

- **Interactive Programming requires a working REPL** - You cannot verify behavior without evaluation

- **Guessing creates bugs** - Code changes without testing introduce errors

Structural Editing and REPL-First Habit

- Develop changes in the REPL before touching files.

- When editing Clojure files, always use structural editing tools such as **Insert Top Level Form**, **Replace Top Level Form**, **Create Clojure File**, and **Append Code**, and always read their instructions first.

Creating New Files

- Use the **Create Clojure File** tool with initial content

- Follow Clojure naming rules: namespaces in kebab-case, file paths in matching snake_case (e.g., `my.project.ns` → `my/project/ns.clj`).

Reloading Namespaces

After editing files, reload the edited namespace in the REPL so updated definitions are active.

(require 'my.namespace :reload)

Code Indentation Before Evaluation

Consistent indentation is crucial to help the bracket balancer.

;; ❌
(defn my-function [x]
(+ x 2))

;; ✅
(defn my-function [x]
  (+ x 2))

Indentation preferences

Keep the condition and body on separate lines:

(when limit
  (println "Limit set to:" limit))

Keep the `and` and `or` arguments on separate lines: