Connecting to a Remote REPL

Proto REPL can connect to a remote Clojure process using nREPL. Connect to the remote REPL by triggering the Command Palette (cmd-alt-p) and selecting "Proto REPL: Remote Nrepl Connection". Enter the host and port of the remote nREPL server and it will connect. The keybinding ctrl-alt-, y will also work.

Starting a Self Hosted ClojureScript REPL

Proto REPL includes the ability to start a self hosted ClojureScript REPL. This is a REPL that runs inside of the Atom editor using ClojureScript. It's currently fairly limited in its capabilities but it will continue to be improved in the future. The ability to run a REPL inside Atom will make it easier to use Proto REPL to develop Proto REPL itself and write more of Proto REPL's code in ClojureScript. It also removes the need to have Java or any build system like Leiningen or Boot installed to do basic things.

This is a list of features currently not yet supported in the self hosted REPL.

Loading external files.

Saving and displaying captured values

Interrupting long running commands.

Printing var source code.

Opening the definition of a var.

Running tests.

Usage Outside of Leiningen Projects

Proto REPL can still start a REPL outside of a Leiningen project. It still uses Leiningen to start the REPL but uses a default project shipped with Proto REPL. This allows you to easily open up any Clojure file or even just a new Atom window and kick off a new REPL for experimenting.

Typing in the REPL

Code to be executed in the REPL can be entered by typing in the last entry area. Code can be executed by pressing shift+enter. The REPL maintains a history of executed commands that were entered in the REPL. The history can be navigated by using the up and down arrow keys after placing the cursor in the text entry area.

Sending Code to the REPL

Code can be sent to the REPL from within the REPL itself or any other open text editor. For example if you have some Clojure code in a Markdown file that can be sent to the REPL as well.

Sending a Block

A block of Clojure code is code that's delimited by parentheses (), curly braces {} (defines a map literal in Clojure), or square brackets [] (defines a vector literal in Clojure). The key binding ctrl-alt-, b (Press ctrl and comma together, release, then press b) can be used to send a block from the current text editor. The block that is sent depends on the position of the cursor. The cursor may be located nested inside several blocks, directly after a block, or before a block. The logic for block finding searches for blocks in the following order.

A block directly after the cursor.

A block directly before the cursor.

The first block the cursor is nested within.

Examples: The following examples show some sample Clojure code using a | to indicate cursor position.

Code

Code sent to REPL

Why?

|(foo 1 2)

(foo 1 2)

Cursor directly before block

(foo 1 2)|

(foo 1 2)

Cursor directly after block

(a (b |(c (foo 1 2))))

(c (foo 1 2))

Cursor directly before c block

(a (b| (c (foo 1 2))))

(b (c (foo 1 2)))

Cursor inside b block

Markdown Blocks

The block detection also can find the start and end of a Github Flavored Markdown Clojure blocks. If the cursor is outside of a Clojure block but within a Markdown Clojure Block (Starts with clojure` and ends with `) then all of the code in the Markdown block will be sent.

Sending a Selection

An arbitrary set of selected Clojure code can be sent to the REPL by selecting the code and using the key binding ctrl-alt-, s (Press ctrl and comma together, release, then press s). This allows sending multiple blocks of code at once.

Autocompletion

Proto REPL supports completing of namespaces, vars, functions, local bindings, and Java methods using the Compliment library. Make sure your project includes as a dependency.

Tips

REPL must be started

After modifying the required namespace definition reevaluate it so that Complement will be able to pick up the alias changes.

Completing Namespaces

Completing Functions

Completing Java Methods

Inline Results Display

Inline display of executed blocks or selections is supported if you have the Atom Ink package installed. You can disable inline results through the configuration. The values displayed inline are shown in a tree like view that lets you explore large nested data structures without having to view all of the data.

Automatic Evaluation Mode

Proto REPL supports the automatic evaluation of top level forms as you type. The results are displayed inline next to each top level form. This requires Atom Ink to be installed. Automatic Evaluation Mode can be started for a file by toggling the Atom Command Palette (cmd-alt-p) and selecting "Proto Repl: Autoeval File". It can be stopped by toggling the Atom Command Palette (cmd-alt-p) and selecting "Proto Repl: Stop Autoeval File"

Saving and Viewing Local Binding Values

When you are inside a function or a let block in Clojure there are symbols that have a value. In this example code which sums up m, a, and b are all local bindings.

(reduce (fn [m [a b]]

(update m a #(+ b (or % 0))))

{}

[[:apples 2] [:oranges 3] [:apples 4] [:cherries 7]])

=>

{:apples 6, :oranges 3, :cherries 7}

While this code is simple it can be difficult to understand what's happening inside functions and loops. A lot of developers reach for logging or printing to debug this kind of code. When you do that across multiple functions and namespaces those values are mixed together and separate from the code. Proto REPL's new feature for saving and viewing local bindings let's you see the values in context and from multiple requests.

The following code was the same as before but now it has (proto-repl.saved-values/save 1). The proto-repl.saved-values/save function saves all the local bindings so that they can be viewed in Proto REPL. The 1 in (proto-repl.saved-values/save 1) is just a unique id to tie the saved values back to Proto REPL for display.

(reduce (fn [m [a b]]

(proto-repl.saved-values/save 1)

(update m a #(+ b (or % 0))))

{}

[[:apples 2] [:oranges 3] [:apples 4] [:cherries 7]])

=>

{:apples 6, :oranges 3, :cherries 7}

After running the code invoking the command proto-repl:display-saved-value will display the values in a table. Each row in the table represents a different iteration of the function.

Tables are limited in the amount of detail that can be shown. Proto REPL will truncate long Clojure data structures to fit into a column. Each row of the table can be expanded to explore the details of large data structures.

You can also specify specific bindings to save. For example (proto-repl.saved-values/save 1 m a) will save just the values of local variables m and b.

The Def button - Defining vars for saved local bindings

The "def" button shown in the saved values table allows you to temporarily define vars in the namespace with names the same as the local bindings. This makes it easy to try out the code with the values that were saved. You can easily reevaluate bits of the code in place and all of the local bindings will be available for use.

Using the save value feature

Insert a call to proto-repl.saved-values/save in the code using the keybinding ctrl-alt-shift-, i (Press ctrl shift comma together, release then i) This just inserts the save call with a unique number. The unique number allows you to have multiple save calls in different locations within your code.

Execute your code. If you've placed the code in a function or across multiple namespaces you'll need to redefine the modified code or refresh before executing the code.

Show the values by pressing the keybinding ctrl-alt-shift-, d

Saved values can be cleared with the keybinding ctrl-alt-shift-, c

There's currently a limit of 20 saved values in proto-repl-lib. After debugging any issues make sure to remove the save calls. They're meant to be used in local development only.

Questions and Discussion

Extending Proto REPL

Keybindings and Events

Keyboard shortcuts below refer to using ctrl-alt-, then a letter. That means press the ctrl key and the comma key at the same time, release them, and then press the subsequent letter. Some keyboard shortcuts also include the shift key.

Keybinding

Event

Action

ctrl-alt-, L

proto-repl:toggle

Starts the REPL

ctrl-alt-, shift-L

proto-repl:toggle

Starts the REPL using the current open project.clj

ctrl-alt-, y

proto-repl:remote-nrepl-connection

Connects to a remote nREPL session.

ctrl-alt-, j

proto-repl:start-self-hosted-repl

Starts a self hosted REPL.

ctrl-alt-, e

proto-repl:exit-repl

Exits the REPL

ctrl-alt-, k

proto-repl:clear-repl

Clears REPL Output

ctrl-alt-shift-, s

proto-repl:toggle-auto-scroll

Enables/Disables autoscrolling the REPL

ctrl-alt-, b

proto-repl:execute-block

Sends the current block of Clojure code to the REPL for execution.

ctrl-alt-, B

proto-repl:execute-top-block

Sends the current top-level block of Clojure code to the REPL for execution.