NOTE: this is a fork of the original project, that is no longer being maintened, and has been updated to work with SUBLIME TEXT 3 and clj deps. Many thanks to jasongilman for his great work!

SublimeClojureSetup

A description of how I setup Sublime Text for Clojure development. It's a bit hacky but it works if you prefer to use Sublime Text for your editing. This is specific to my own workflow on a Mac but should be mostly applicable to development on other platforms with Sublime Text.

Initially based on instructions here: https://gist.github.com/jamesmacaulay/5457344

Why Sublime Text?

I have tested many other code editors but always find myself returning to Sublime Text with SublimeREPL. And why is that? Even though its setup is hacky and is far from perfect, no other editor can match its raw speed and convenience of keybindings shortcuts. As with many things, picking and setting up your code editor is more art than science and what works best for you is up to your specific tastes and requirements.

Prerequisites

• Sublime Text 3
• Java
• Leiningen 2

Leiningen

Install it then create ~/.lein/profiles.clj. See profiles.clj in this repo for contents.

Sublime Text 3 With Clojure

Paths assumed for each OS

• OSX: ~/Library/Application\ Support/Sublime\ Text\ 3
• Linux: ~/.config/sublime-text-3

This documents how to setup Sublime Text 3 with Clojure. It uses the sublime text package manager. Follow the installation instructions to install the package manager into Sublime Text 3. If you already have the package manager installed make sure all packages are up to date.

• Bring up the command pallet - cmd + shift + P
• Select: Package Control: Upgrade/Overwrite All Packages
• It should finish successfully without any feedback. You can see sublime logs by hitting __ctrl + ~__

How to perform basic tasks

Open a Clojure REPL

The Sublime REPL is used to open a REPL within Sublime Text. It can be opened by:

• Invoke the command pallet - cmd + shift + P
• Type repl and select SublimeREPL: Clojure
  • Doing this repeatedly will make it the first one to come up when typing repl
• Alternately it can be opened with the key combination alt + super + l.

Very Important: Most of the time you'll want a REPL open for the current project. Sublime REPL only knows to connect the REPL to the current project if you start the REPL with a Clojure file open in the project and your cursor is in it.

Alternatively, if you wish to run the REPL with clj deps, you'll need to to open the SublimeREPL package and update the contents of /Packages/SublimeREPL/config/Clojure/Default.sublime-commands and /Packages/SublimeREPL/config/Clojure/Main.sublime-menu according to this pull request. Then,

• Invoke the command pallet - cmd + shift + P
• Type repl and select SublimeREPL: Clj

Keybindings

These are setup in the instructions Sublime Text setup instructions below.

• Bindings interacting with the REPL (Require a single Clojure REPL open and running.)
  • alt + super + l - Starts a new Clojure REPL. Make sure to have cusor in an open Clojure file.
  • ctrl + d - Exit the repl
  • ctrl + l - Clear the repl
  • alt + cmd + r - Refresh all code in project by running user/reset. It will fail if a project does not define the user/reset function.
  • alt + cmd + shift + r - The super refresh. If you delete files or rename things sometimes clojure.tools.namespace will have issues. This runs (clojure.tools.namespace.repl/clear) prior to calling reset.
  • alt + cmd + b - Transfer text from the current block to the repl and executes it.
    • This is useful when you have sample code in a clojure file open next to a REPL. Put your cursor within a block of the sample code and invoke the keystroke. The closest block around or near the cursor will be executed in the REPL within the namespace of the file it comes from.
  • alt + cmd + s - Transfers selected text to the repl and executes it. Similar to alt + cmd + b.
  • alt + cmd + x - Runs tests from current test file. Refreshes code in project first.
    • Invoke the keystroke with your cursor in the test file. It will run all the tests in the file in the REPL.
  • alt + cmd + t - Runs a selected test var. Configurable whether this does a refresh first or not.
  • alt + cmd + a - Runs all the tests in the project. Refreshes code in project first. The REPL will still be responsive while tests are running. You can cancel the running tests by refreshing the repl with alt + cmd + r.
  • alt + cmd + d - Print documentation of the selected function.
    • Select a function name in a file including the namespace if part of the call and hit the keystroke.
  • alt + cmd + c - Print source code of the selected function.
  • alt + cmd + n - Print the vars in the selected namespace or namespace alias.
  • alt + cmd + shift + n - Print the documentation of the vars in the selected namespace or namespace alias.
  • alt + cmd + o - Opens the file and scrolls to the line where the selected var is defined. Also works on selected namespaces and with code in jar files.
    • Assumes the subl command line argument works. See https://www.sublimetext.com/docs/2/osx_command_line.html
  • alt + cmd + p - Pretty print the value that was last returned in the repl.
• Other useful keystrokes (Built into Sublime)
  • ctrl + m - Jumps cursor to close or beginning of current block. Press repeatedly to go back and forth.
  • ctrl + shift + m - Select code within current block. Repeated pressing expands selection.
    • This is very useful for selecting a block of Clojure code to cut and paste in a new area.

Setup

Install These Packages

Install these packages using the package manager.

• SublimeREPL
• lispindent
• BracketHighlighter
• EnhancedClojure

Sublime Preference Files

Fix Match Brackets

Add this code to your user preferences

• Add the following lines to /Packages/User/Preferences.sublime-settings

// This needs to be disabled since we're using Bracket Highlighter for highlighting brackets
"match_brackets": false

Fix identification of Clojure Symbols

Sublime Text doesn't correctly identify Clojure symbols.

• Create /Packages/User/Clojure.sublime-settings with the following contents.

{
  "extensions":
  [
    "cljs"
  ],
  "word_separators": "\\()\"',;@$%^&|[]{}`~"
}

Disable auto-pairing of single quotes

Clojure uses single quote characters by themselves like (def my-literal-list '(1 2 3)). Sublime Text will automatically close single quotes. This becomes annoying when writing Clojure code in sublime text. Turn it off by following these steps:

• Open /Packages/Default/Default (OSX).sublime-keymap
• Search for "Auto-pair single quotes" which should be on line 274 or so.
• Comment out the block of about 30 lines directly following that comment to disable pairing of single quotes only.

Add Leiningen to SublimeREPL Path

This file updates SublimeREPL settings so leiningen in on the path. Update this file to include the directory where you installed leiningen.

• Edit /Packages/User/SublimeREPL.sublime-settings with the following changes

{
  // Has to include path to lein
  "default_extend_env":
  {
    "PATH": "REPLACE_ME_WITH_LEIN_DIR:{PATH}:/usr/local/bin"
  }
}

Configure Lisp Indentation Settings

The lispindent.sublime-settings defines which forms use function style indentation. I've added additional ones that are typically used in Clojure Applications

* `/Packages/User/`

Speed up text transfer in SublimeREPL

Change /config/Clojure/Main.sublime-menu line 22 from

"osx":  ["lein", "repl"]

to:

"osx":  ["lein", "trampoline", "run", "-m", "clojure.main"]

This greatly improves the speed at which text is sent from a Clojure window to the REPL. Based on answer here http://stackoverflow.com/questions/20835788/is-it-normal-to-have-really-slow-text-transfer-in-sublime-text-2-with-the-clojur

Setup Keybindings

We'll setup some keybindings in Sublime Text to make it easier to send code to the repl, run tests, etc.

• Append the clojure_keybindings.sublime-keymap in this repo to /Packages/User/Default (OSX).sublime-keymap
  • Keymap files contain JSON so make sure they're valid when saving or Sublime Text will fail with errors.

Clojure Helpers

The ClojureHelpers.py file provides some helper functions that make working with Sublime REPL and Clojure a little better. These are associated with key bindings. You can also add your own helpers to this file.

• Copy ClojureHelpers.py to /Packages/User/

Clojure Snippets

Copy the file clojure_snippets.sublime-snippet to /Packages/User/clojure_snippets.sublime-snippet. It contains some useful completions.