Skip to content
This repository has been archived by the owner on May 10, 2023. It is now read-only.

Latest commit

 

History

History
279 lines (189 loc) · 21.8 KB

README.md

File metadata and controls

279 lines (189 loc) · 21.8 KB
Raw

Proto REPL

Proto REPL is a Clojure development environment and REPL for Atom. See the features and installation instructions. See the proto-repl-demo project for a demonstration of the features.

A screenshot of Proto REPL

Features

Videos/Blog Posts

Getting Started

Option 1. Quick Start

These are the instructions get up and running quickly. Most features will work but for the best results see Option 2.

  1. Install Atom.
  2. Install Java and Leiningen or Boot or have a project with a Gradle wrapper.
  3. Go to Atom settings, select "+ Install" and search for "proto-repl".
  4. Install the Atom Ink package.
  5. Go to the Proto REPL Settings (Atom Preferences, then packages, then Proto REPL)
  6. Modify "Lein Path" or "Boot Path" to the path where Leiningen/Boot was installed. Use which lein in a terminal to get the path.
  • This should be something like /some/path/bin/lein
  • Gradle projects will always look for the wrapper (standalone Gradle installs are not supported).
  • If your project has multiple build configurations, use the Preferred Repl option to choose which of lein, boot, or gradle should be preferred.
  1. Restart Atom.
  2. Start a REPL

See the Proto REPL Demo project for a demonstration of the features of Proto REPL.

Option 2. Opinionated, Complete, Best Way to Setup Atom for Clojure Development with Proto REPL

Follow the instructions here: https://git.io/atom_clojure_setup

Setting up an Existing Clojure Project

Add the Clojars Project library as a dependency.

Usage

Start a Local Clojure REPL

A local Proto REPL primarily works with projects using Leiningen, Boot, or Gradle (with gradle-clojure).

  1. Open your Clojure project in Atom. (See the Leiningen tutorial, the Boot tutorial, or the gradle-clojure documentation for help creating a new project.)
  2. Start the REPL by bring up the Command Palette (cmd-shift-p) and select "Proto REPL: Toggle"

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.

Start the self hosted REPL by triggering the Command Palette and selecting "Proto REPL: Start Self Hosted Repl". The keybinding ctrl-alt-, j will also work.

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

  • Executing commands in the REPL.
  • Executing blocks or selections of code.
  • Autocompletion of vars (does not include documentation yet)
  • Using Proto REPL Charts to draw charts and graphs.
  • Inline display of results
  • Showing documentation of a var.
  • Automatic evaluation mode.

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.

  1. A block directly after the cursor.
  2. A block directly before the cursor.
  3. 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 Clojars Project 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 namespaces

Completing Functions

completing functions

Completing Java Methods

completing Java

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.

inline results screenshot

Automatic Evaluation Mode

(Automatic Evaluation is in beta and subject to change. Please report any issues or suggestions for improvement.)

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"

automatic evaluation mode screenshot

The visualization shown was created with Proto REPL Charts.

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.

saved values table

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.

saved values table expanded

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

  1. 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.
  2. 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.
  3. Show the values by pressing the keybinding ctrl-alt-shift-, d
  4. 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.

Dependencies

  • Java
    • Not required for self hosted REPL.
  • Leiningen, Boot, or Gradle (requires use of Gradle wrapper)
    • Not required for self hosted REPL.
  • Atom Ink
    • This is an optional feature but many of Proto REPL's advanced features won't work without it.
  • Add a dependency to the Clojure proto-repl-lib in your project's dependencies. Clojars Project
    • This is an optional Clojure library that adds support for some of the advanced Proto REPL features.
    • Required for:
      • Saving and displaying local binding values
      • Autocompleting Clojure code

Supports Clojure 1.6 and greater.

Tool Bar Integration

Proto REPL integrates with the Atom Tool Bar package to provide buttons for common REPL actions. Install tool-bar and then restart Proto REPL to get quick access to actions like refreshing namespaces, pretty printing, and toggling REPL scrolling.

Questions and Discussion

For questions and general Proto REPL discussion see the #protorepl channel on Slack

Extending Proto REPL

See extending_proto_repl.md

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.
ctrl-alt-, s proto-repl:execute-selected-text Sends the selected text to the REPL for execution.
ctrl-alt-, f proto-repl:load-current-file Loads the current file in the repl.
ctrl-alt-, r proto-repl:refresh-namespaces Runs the user/reset function. See My Clojure Workflow, Reloaded
ctrl-alt-shift-, r proto-repl:super-refresh-namespaces Clears all loaded namespaces using clojure.tools.namespace the runs the user/reset function.
ctrl-alt-, p proto-repl:pretty-print Pretty prints the last value returned at the REPL.
ctrl-alt-, x proto-repl:run-tests-in-namespace Runs all the tests in the current namespace.
ctrl-alt-, t proto-repl:run-test-under-cursor Runs the test that has a name under the cursor.
ctrl-alt-, a proto-repl:run-all-tests Runs all the test in the current project.
ctrl-alt-, d proto-repl:print-var-documentation Prints the documentation of a var under the cursor.
ctrl-alt-, c proto-repl:print-var-code Prints out the code of the var under the cursor.
ctrl-alt-, o proto-repl:open-file-containing-var Opens the code of the var or namespace under the cursor. This works even with vars defined in libraries.
ctrl-alt-, n proto-repl:list-ns-vars Lists the vars in the namespace under the cursor.
ctrl-alt-shift-, n proto-repl:list-ns-vars-with-docs Lists the vars in the namespace under the cursor with documentation.
shift-ctrl-c proto-repl:interrupt Attempts to interrupt the currently running command in the REPL.
ctrl-alt-shift-, i proto-repl:insert-save-value-call Inserts a call to proto/save with a unique id
ctrl-alt-shift-, d proto-repl:display-saved-values Displays values saved using the proto/save function.
ctrl-alt-shift-, c proto-repl:clear-saved-values Clears previously saved values using the proto/save function.