|
| 1 | +--- |
| 2 | +name: brepl |
| 3 | +description: "MANDATORY - Load this skill BEFORE using brepl in any way. Teaches the heredoc pattern for reliable Clojure code evaluation." |
| 4 | +--- |
| 5 | + |
| 6 | +# brepl - Evaluating Clojure Code |
| 7 | + |
| 8 | +## CRITICAL: Load This Skill First |
| 9 | + |
| 10 | +**You MUST load this skill before using brepl.** Do NOT attempt to use brepl without loading this skill first, or you will use incorrect syntax. |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +brepl is a REPL client for evaluating Clojure expressions. This skill teaches the heredoc pattern for reliable code evaluation. |
| 15 | + |
| 16 | +**Always load this skill before using brepl. Always use the heredoc pattern for all Clojure code evaluation.** |
| 17 | + |
| 18 | +## The Heredoc Pattern - Default Approach |
| 19 | + |
| 20 | +**Always use heredoc for brepl evaluation.** This eliminates quoting issues, works for all cases, and provides a consistent, reliable pattern. |
| 21 | + |
| 22 | +### Syntax (Stdin - Recommended) |
| 23 | + |
| 24 | +```bash |
| 25 | +brepl <<'EOF' |
| 26 | +(your clojure code here) |
| 27 | +EOF |
| 28 | +``` |
| 29 | + |
| 30 | +This is the simplest heredoc syntax - stdin feeds directly to brepl. |
| 31 | + |
| 32 | +### Alternative Syntax (Positional Argument) |
| 33 | + |
| 34 | +For simple one-liners, you can use positional arguments: |
| 35 | + |
| 36 | +```bash |
| 37 | +brepl '(+ 1 2 3)' |
| 38 | +``` |
| 39 | + |
| 40 | +Heredoc is preferred for anything with quotes or multiple lines. |
| 41 | + |
| 42 | +**Note**: The `-e` flag is optional - brepl automatically treats stdin and positional arguments as code to evaluate. |
| 43 | + |
| 44 | +**Important**: Use `<<'EOF'` (with quotes) not `<<EOF` to prevent shell variable expansion. |
| 45 | + |
| 46 | +### Examples |
| 47 | + |
| 48 | +**Multi-line expressions**: |
| 49 | + |
| 50 | +```bash |
| 51 | +brepl <<'EOF' |
| 52 | +(require '[clojure.string :as str]) |
| 53 | +(str/join ", " ["a" "b" "c"]) |
| 54 | +EOF |
| 55 | +``` |
| 56 | + |
| 57 | +**Code with quotes**: |
| 58 | + |
| 59 | +```bash |
| 60 | +brepl <<'EOF' |
| 61 | +(println "String with 'single' and \"double\" quotes") |
| 62 | +EOF |
| 63 | +``` |
| 64 | + |
| 65 | +**Reloading and testing**: |
| 66 | + |
| 67 | +```bash |
| 68 | +brepl <<'EOF' |
| 69 | +(require '[myapp.core] :reload) |
| 70 | +(myapp.core/some-function "test" 123) |
| 71 | +EOF |
| 72 | +``` |
| 73 | + |
| 74 | +**Complex data structures**: |
| 75 | + |
| 76 | +```bash |
| 77 | +brepl <<'EOF' |
| 78 | +(def config |
| 79 | + {:database {:host "localhost" |
| 80 | + :port 5432 |
| 81 | + :name "mydb"} |
| 82 | + :api {:key "secret-key" |
| 83 | + :endpoint "https://api.example.com"}}) |
| 84 | +(println (:database config)) |
| 85 | +EOF |
| 86 | +``` |
| 87 | + |
| 88 | +**Running tests**: |
| 89 | + |
| 90 | +```bash |
| 91 | +brepl <<'EOF' |
| 92 | +(require '[clojure.test :refer [run-tests]]) |
| 93 | +(require '[myapp.core-test] :reload) |
| 94 | +(run-tests 'myapp.core-test) |
| 95 | +EOF |
| 96 | +``` |
| 97 | + |
| 98 | +## Alternative: Simple Expressions |
| 99 | + |
| 100 | +For very simple expressions, you can use direct positional arguments: |
| 101 | + |
| 102 | +```bash |
| 103 | +# Simple expression |
| 104 | +brepl '(inc 1)' |
| 105 | + |
| 106 | +# Same with heredoc (consistent approach) |
| 107 | +brepl <<'EOF' |
| 108 | +(inc 1) |
| 109 | +EOF |
| 110 | +``` |
| 111 | + |
| 112 | +**Why prefer heredoc:** No mental overhead deciding which pattern to use, no risk of quoting issues, easy to extend. |
| 113 | + |
| 114 | +## Loading Files |
| 115 | + |
| 116 | +To load an entire file into the REPL: |
| 117 | + |
| 118 | +```bash |
| 119 | +brepl -f src/myapp/core.clj |
| 120 | +``` |
| 121 | + |
| 122 | +After loading, you can evaluate functions from that namespace using either pattern. |
| 123 | + |
| 124 | +## Fixing Unbalanced Brackets |
| 125 | + |
| 126 | +Use `brepl balance` to fix unbalanced brackets in Clojure files using parmezan: |
| 127 | + |
| 128 | +```bash |
| 129 | +# Fix file in place (default) |
| 130 | +brepl balance src/myapp/core.clj |
| 131 | + |
| 132 | +# Preview fix to stdout |
| 133 | +brepl balance src/myapp/core.clj --dry-run |
| 134 | +``` |
| 135 | + |
| 136 | +This is useful for recovering files with bracket errors. |
| 137 | + |
| 138 | +## Common Patterns |
| 139 | + |
| 140 | +### Namespace reloading |
| 141 | + |
| 142 | +```bash |
| 143 | +brepl <<'EOF' |
| 144 | +(require '[myapp.core] :reload-all) |
| 145 | +EOF |
| 146 | +``` |
| 147 | + |
| 148 | +### Documentation lookup |
| 149 | + |
| 150 | +```bash |
| 151 | +brepl <<'EOF' |
| 152 | +(require '[clojure.repl :refer [doc source]]) |
| 153 | +(doc map) |
| 154 | +(source filter) |
| 155 | +EOF |
| 156 | +``` |
| 157 | + |
| 158 | +### Error inspection |
| 159 | + |
| 160 | +```bash |
| 161 | +brepl <<'EOF' |
| 162 | +*e |
| 163 | +(require '[clojure.repl :refer [pst]]) |
| 164 | +(pst) |
| 165 | +EOF |
| 166 | +``` |
| 167 | + |
| 168 | +## Critical Rules |
| 169 | + |
| 170 | +1. **Always use heredoc** - Use the heredoc pattern for all brepl evaluations |
| 171 | +2. **Quote the delimiter** - Always use `<<'EOF'` not `<<EOF` to prevent shell expansion |
| 172 | +3. **No escaping needed** - Inside heredoc, write Clojure code naturally |
| 173 | +4. **Multi-step operations** - Combine multiple forms in one heredoc block |
| 174 | +5. **Write correct Clojure** - Ensure proper bracket balancing and valid syntax |
| 175 | + |
| 176 | +## Why Always Use Heredoc |
| 177 | + |
| 178 | +**Consistency over optimization.** While simple positional arguments work for basic cases, using heredoc everywhere means: |
| 179 | + |
| 180 | +1. **No decision fatigue** - One pattern for everything |
| 181 | +2. **No quoting errors** - Everything between `<<'EOF'` and `EOF` is literal |
| 182 | +3. **Easy to extend** - Add more lines without changing syntax |
| 183 | +4. **Readable** - Clear where the code starts and ends |
| 184 | +5. **Safe** - No shell interpretation of Clojure code |
| 185 | + |
| 186 | +Shell quoting with Clojure is error-prone: Clojure uses both single and double quotes, nested quotes require escaping, and reader macros can confuse the shell. Heredoc eliminates all these issues. |
| 187 | + |
| 188 | +## Resources |
| 189 | + |
| 190 | +brepl documentation: https://github.com/licht1stein/brepl |
0 commit comments