# Clojure support for Sublime Text 4
This package provides Clojure support for Sublime Text and includes: - Clojure and EDN syntax grammars (Sublime Text 3+) - Clojure code formatter/indenter (Sublime Text 4075+) - Clojure nREPL client (Sublime Text 4075+, nREPL 0.9+) ## Clojure syntax Syntaxes Clojure Sublimed ships with its own syntax definition for Clojure and EDN. Unlike default Clojure syntax, this package is: - slightly more pedantic as per [EDN spec](https://github.com/edn-format/edn) and [Clojure Reader](https://clojure.org/reference/reader), - rigorously tested, - can be used to highlight rainbow parentheses, - punctuation and validation _inside_ regexps, - quoted and unquoted regions are marked for highlighting, - semantically correct tokenization, perfect for fonts with ligatures, - has separate EDN syntax, same way JSON is separate from JavaScript in Sublime Text. Want to put your parser to test? Check out [syntax_test_edn.edn](./test_syntax/syntax_test_edn.edn) and [syntax_test_clojure.cljc](./test_syntax/syntax_test_clojure.cljc). Clojure Sublimed syntax is also used by nREPL client to find form boundaries and namespaces (might be changed in the future). ## Formatter/indenter Clojure Sublimed includes optional support for [Simple Clojure Formatting rules](https://tonsky.me/blog/clojurefmt/). It doesn’t require nREPL connection but does require `Clojure (Sublimed)` syntax to be selected for buffer. To reformat whole file, run `Clojure Sublimed: Reindent Buffer`. To reindent only current line(s), run `Clojure Sublimed: Reindent Lines`. To enable reindenting / formatting on save, add `format_on_save: true` to settings. ([See how to edit settings](#editing-settings)) To enable correct indentations as you type code, rebind `Enter` to `Clojure Sublimed: Insert Newline`: ``` {"keys": ["enter"], "command": "clojure_sublimed_insert_newline", "context": [{"key": "selector", "operator": "equal", "operand": "source.edn | source.clojure"}, {"key": "auto_complete_visible", "operator": "equal", "operand": false}, {"key": "panel_has_focus", "operator": "equal", "operand": false}]} ``` Best way to do it is through running `Preferences: Clojure Sublimed Key Bindings`. ## nREPL Client Clojure Sublimed nREPL client enables interactive development from the comfort of your editor. Principles: - Minimal distraction. Display evaluation results inline. - Decomplected. Eval code and nothing more. - Server-agnostic. We work with any nREPL socket, local or over network. Features: - [x] evaluate code, - [x] display evaluation results inline. - [x] display stack traces inline, - [x] interrupt evaluation, - [x] eval multiple forms at once (parallel evaluation), - [x] lookup symbol info, - [x] show evaluation time, - [x] bind keys to eval arbitrary code. We intentionally excluded following features: - [ ] Autocomplete. Static analysis is much simpler and much more reliable than requiring an always-live connection to the working app. Look at [Sublime LSP](https://github.com/sublimelsp/LSP) with [Clojure LSP](https://github.com/clojure-lsp/clojure-lsp) or [SublimeLinter](https://github.com/SublimeLinter/SublimeLinter) with [clj-kondo](https://github.com/ToxicFrog/SublimeLinter-contrib-clj-kondo) if you need autocompletion. Why nREPL and not Socket Server REPL/pREPL/unREPL? - nREPL has the widest adoption, - nREPL is machine-friendly, - nREPL comes with batteries included (interrupt, load-file, sideload), - nREPL is extensible via middleware, - nREPL serialization is easier to access from Python than EDN. Differences from [Tutkain](https://tutkain.flowthing.me/): - nREPL instead of Socket Server REPL - Does not have separate REPL panel - Keeps multiple eval results on a screen simultaneously - Can show stack traces inline in editor - Can eval several forms in parallel - Can eval non well-formed forms (e.g. `(+ 1 2`) - Can eval infinite sequences - Redirects all `*out*`/`*err*` to `System.out`/`System.err` ## Installation 1. `Package Control: Install Package` → `Clojure Sublimed` 2. Assign syntax to Clojure files: - open any clj/cljc/cljs file, - run `View` → `Syntax` → `Open all with current extension as...` → `Clojure Sublimed` → `Clojure (Sublimed)`. ## How to use Important! Make sure you switched your syntax to `Clojure (Sublimed)`. For Clojure apps 1. Run nREPL server. 2. Run `Clojure Sublimed: Connect` command. For Shadow-cljs apps 1. Run `shadow-cljs watch app`. (This starts a HTTP server and an nREPL) 2. If you are building a web-app, open the http-server url (from step 1) in the browser. This connects the shadow server to JS runtime. 3. Run `Clojure Sublimed: Connect shadow-cljs` command from sublime's command palette. ### Evaluating code from buffer From here you have three options: `Clojure Sublimed: Evaluate` without selection evaluates topmost form around your cursor: Evaluate Topmost `Clojure Sublimed: Evaluate` with selection evaluates selected text: Evaluate Selection `Clojure Sublimed: Evaluate Buffer` will evaluate the entire file: Evaluate Buffer You don’t have to wait for one form to finish evaluating to evaluate something else. Multiple things can be executed in parallel: Evaluate in Parallel By default, Clojure Sublimed will also print evaluation time if it took more than 100 ms: Elapsed time ### Copying evaluation results Sometimes you want to copy evaluation result. It is recommended to rebind `Cmd+C`/`Ctrl+C` from `copy` to `sublime_clojure_copy`. This will copy evaluation result if inside evaluated region and fallback to default `copy` otherwise. ### Interrupting If your evaluation runs too long and you want to interrupt it, run `Clojure Sublimed: Interrupt Pending Evaluations`: Interrupt ### Opening stacktrace If your evaluation failed, put your cursor inside failed region and run `Clojure Sublimed: Toggle Stacktrace`: Toggle Stacktrace Clojure Sublimed will display stacktraces in a Clojure-friendly way. Compare with the default REPL: Stacktraces ### Looking up symbol To show symbol info, run `Clojure Sublimed: Toggle Symbol Info`: Toggle Symbol Info Universal `Clojure Sublimed: Toggle Info` command acts as either `Toggle Stacktrace` or `Toggle Symbol Info`, depending on context. ### Binding keys to eval code Every project is different, and sometimes it’s convenient to run a piece of code so often you’d want it on a shortcut. It might be a namespace reload, test execution, database reconnect, linter, formatter — possibilities are endless. To support such use cases, Clojure Sublimed allows you to bind arbitrary piece of code to a keyboard shortcut. Run `Preferences: Clojure Sublimed Key Bindings` and add something like this: ``` {"keys": ["ctrl+t"], "command": "clojure_sublimed_eval_code", "args": {"code": "(clojure.test/run-all-tests)"}} ``` Then, whenever you press Ctrl + T, you’ll see the result in the status bar, like this: Eval Code Tip: use `(clojure.test/run-all-tests (re-pattern (str *ns*))))` to run tests in current namespace. ### Clearing results Finally, to clear evaluation results run `Clojure Sublimed: Clear Evaluation Results`. ### Editing settings To edit settings, run `Preferences: Clojure Sublimed Settings` command. ### Session-wide settings It is sometimes desirable to set dynamic Clojure vars for the whole session. To do that, edit `"eval_shared"` setting. For example: ``` "eval_shared": "(do (set! *warn-on-reflection* true) (set! *print-namespace-maps* false))" ``` This will be applied to every evaluation. ## Default Key Bindings Clojure Sublimed comes with no keybindings enabled by default to guarantee they won’t conflict with any other extension. This is the recommended keymap: Command | macOS | Windows/Linux | Mnemonic ------------------------------|----------------------------------|-------------------------------------------------| ----------------------- Evaluate | Ctrl Enter | Ctrl Alt Enter | Evaluate Buffer | Ctrl B | Ctrl Alt B | [B]uffer Interrupt Pending Evaluations | Ctrl C | Ctrl Alt C | [C]ancel Toggle Info | Ctrl I | Ctrl Alt I | [I]nfo Clear Evaluation Results | Ctrl L | Ctrl Alt L | c[L]ear Copy Evaluation Results | Command C | Ctrl C | [C]opy Reindent Lines | Ctrl F | Ctrl Alt F | [F]ormat Reindent Buffer | Ctrl Shift F | Ctrl Alt Shift F | Capital [F]ormat To set it up, run `Preferences: Clojure Sublimed Key Bindings` command and copy example keybindings to your local Key Bindings file. ## Frequently Asked Questions Q: REPL/eval doesn’t work A: Make sure you are using nREPL 0.9 or later. A: Make sure you have assigned `Clojure (Sublimed)` syntax to the file. ## Credits Made by [Niki Tonsky](https://twitter.com/nikitonsky). With contributions by [Jaihindh Reddy](https://github.com/jaihindhreddy). ## See also [Writer Color Scheme](https://github.com/tonsky/sublime-scheme-writer): A color scheme optimized for long-form writing. [Alabaster Color Scheme](https://github.com/tonsky/sublime-scheme-alabaster): Minimal color scheme for coding. [Sublime Profiles](https://github.com/tonsky/sublime-profiles): Profile switcher. ## License [MIT License](./LICENSE.txt)