Cognitect REBL

REBLplain.png

Overview

REBL is a graphical, interactive tool for browsing Clojure data. REBL is developed by the Datomic Team at Cognitect, and is available for non-commercial use (per the EULA) free of charge. We hope that many Clojure developers will find it useful.

REBL is included with Cognitect dev-tools.

Release Status

REBL is early access. Your feedback can help make it better. Please report any issues that you encounter.

Installation

Get the latest version of Cognitect dev-tools and unzip it. From the unzip directory, install the dev-tools with the install script:

bash ./install

Add the following to /.clojure/deps.edn to define an alias to use in all projects, or to a project's local deps.edn

{:aliases
 {:rebl        ;; for JDK 11+
  {:extra-deps {com.cognitect/rebl          {:mvn/version "0.9.242"}
                org.openjfx/javafx-fxml     {:mvn/version "15-ea+6"}
                org.openjfx/javafx-controls {:mvn/version "15-ea+6"}
                org.openjfx/javafx-swing    {:mvn/version "15-ea+6"}
                org.openjfx/javafx-base     {:mvn/version "15-ea+6"}
                org.openjfx/javafx-web      {:mvn/version "15-ea+6"}}
   :main-opts ["-m" "cognitect.rebl"]}
  :rebl-jdk8   ;; for JDK 8
  {:extra-deps {com.cognitect/rebl {:mvn/version "0.9.242"}}
   :main-opts ["-m" "cognitect.rebl"]}}}

Usage

Replace your repl invocation (clj or clojure) with the appropriate alias for your JDK version:

  • JDK 8
    • clj -A:rebl-jdk8
  • JDK 11+
    • clj -A:rebl

Your repl should start, along with the REBL UI. Everything evaluated in your REPL will also appear in REBL. You can also type expressions right into REBL's editor (in the upper left). REBL will maintain a history of exprs+results in the root browse table.

Additional UI's can be started by evaluating cognitect.rebl/ui in your editor.

nREPL

To use REBL with nREPL or nREPL based editors:

Forms can be sent to REBL using cognitect.rebl/inspect. They will be evaluated and added to the eval-history.

cider

Emacs cider users can launch REBL automatically and send forms on request via defun->keybinding by using the instructions in the cider-rebl repository.

Cursive

  • Install REBL and the deps.
  • Create a new, or use an existing, Clojure Deps project
    • Edit your REPL Configuration to use:
      • REPL type: clojure.main
      • Check Run with Deps:
      • Enter the appropriate alias: rebl-jdk8 for JDK 8, or rebl for JDK 11+

If you are using nREPL, then please follow the nREPL Instructions.

Limitations

REBL currently requires Java 1.8 or Java 11+

Interface

Code Editor

The Code Editor is a full-featured editor for writing clojure code. Code is evaluated and the results are immediately available inside the browser, out and tap tabs.

Numerous hotkeys are available for text editing.

Browser

Results of evaluation appear in the Browser pane. When navigating using the forward and back buttons, the current values will appear in the appropriate browser in this pane.

nav-> will navigate deeper into data while keeping the current browser view on the data that you're acting upon.

Evaluating new code or navigating back to the root will cause the Browser Pane to return to the evaluation-history.

Browser Viewer

Data in the browser can be displayed in a variety of ways. The Browser View drop-down lists the current available views for the data displayed in the Browser.

Data Viewer

The data currently selected in the Browser will be displayed in the Data Viewer using the currently selected viewer.

Data Viewer Type

A number of viewers are available for different shapes and types of data.

def as:

Typing a valid clojure symbol name into the def as: text box and pressing enter will def bind the data shown in the Data Viewer to that var in the user namespace.

Vars are def'd in the user name space.

This is often useful when navigating deep into data and you want to extract the data in the Data Viewer.

Metadata Viewer

The Metadata Viewer displays the Metadata for the data currently displayed in the Data Viewer

The forward button (Command-Right) navs into the data selected in the Data Viewer and the current value is moved to the Browser.

If nav-> is currently being used, then it will be added to the path when navigating forward.

The back button (Command-Left) navs to the previous value in the navigation history.

If nav-> was used while navigating forward, then the full nav-> path that was used will be treated as a single nav step while navigating back.

This button (Shift-Command-Left) will navigate back to the evaluation history.

Follow REPL

If launching REBL normally, REBL will follow all REPL interactions. The Follow REPL checkbox controls whether this is active or not.

out

The out tab shows *out* for the REBL repl.

tap

REBL adds a tap and calls to tap will be displayed here.

The resulting values from REBL's tap can be cleared, or loaded into the Data View with the browse button.

path:

path: displays the currently navigated path starting with the index in the eval-history.

nav-> allows you to supply a set of keys or a set of parenthesized forms to navigate forward in the currently selected collection without changing the relationship between the Current Browser and Data Viewer panes.

The Data Viewer will nav-> to the data, but the Browser will remain unchanged.

nav-> remains in effect while browsing the eval-history, so if you have a number of results which require the same navigational steps, this can be entered into nav-> and all browsing will utilize those steps.

REBL and Datomic

Datomic entities are automatically navigated via pull.

Datafied Filetypes

REBL will datafy java.io.Files that contain data to return the contents of those files, as described below:

Extension Format Library Required (Tested With)
.csv csv data.csv 0.1.4
.edn edn (none)
.properties Java properties  
.json json data.json 0.2.3
.yml, .yaml YAML snakeyaml 1.23

Browsable Files

REBL will open a WebView on java.io.Files whose name returns a text/ or image/ mimetype from the configured Java FileNameMap.

Current Keybindings

Editor Keys

Command Key Command Key
Add Cursor Above Option-Command-Up Expand Select Control-Shift-Command-Right
Add Cursor Below Option-Command-Down Find Command-F
Add Cursors to Line Ends Shift-Option-L Find Next Command-G
Add Line Comment Command-K Command-c Find Next Selection Command-F3
Add To Next Find Match Command-D Find Previous Shift-Command-G
Backspace Backspace Find Previous Selection Shift-Command-F3
Backward sexp Option-Left Find With Selection Command-E
Backward sexp mark Shift-Option-Left Fold Option-Command-[
Backward Up sexp Option-Up Fold All Command-K Command-0
Barf sexp Backward Control-Option-Right Fold All Block Comments Command-K Command-/
Barf sexp Forward Control-Left Fold All Regions Command-K Command-8
Change All Occurrences Command-F2 Fold Level 1 Command-K Command-1
Copy Command-C Fold Level 2 Command-K Command-2
Copy Line Down Shift-Option-Down Fold Level 3 Command-K Command-3
Copy Line Up Shift-Option-Up Fold Level 4 Command-K Command-4
Cut Command-X Fold Level 5 Command-K Command-5
Delete Delete Fold Level 6 Command-K Command-6
Delete All Left Command-Backspace Fold Level 7 Command-K Command-7
Delete All Right Control-K Fold Recursively Command-K Command-[
Delete Line Shift-Command-K Format Document Shift-Option-F
Evaluate Code Control-Enter Format Selection Command-K Command-F
Command Key Command Key
paredit-open-roun   paredit-forward-slurp-sexp Control-Right
paredit-open-square [ paredit-backward-slurp-sexp Control-Option-Left
paredit-open-curly { backward-sexp-mark Option-Shift-Left
paredit-forward Option-Right forward-sexp-mark Option-Shift-Right
paredit-backward Option-Left paredit-split-sexp Option-Shift-S
paredit-backward-up Option-Up paredit-splice-sexp Option-S
paredit-forward-down Option-Down paredit-kill Control-K
paredit-reindent-defun Option-Q paredit-kill-backward Control-Shift-K
paredit-forward-barf-sexp Control-Left paredit-delete Delete
paredit-backward-barf-sexp Control-Option-Right paredit-backspace Backspace

App Keys

Command Key
Nav Forward Command-Right
Nav Backwards Command-Left
Nav to Root (Eval History) Shift-Command-Left
Focus Browse Control-B
Focus View Control-V
Focus Browse Choice Shift-Control-B
Focus View Choice Shift-Control-V
Focus Code Entry Control-R

Release History

0.9.242

  • Provide dev-tools via Cognitect maven repo

0.9.220

  • Improvement: Added copy functionality to the viewer.
  • Improvement: Keep the cursor in view while navigating with selected text.

0.9.218

  • This version of REBL replaces the embedded code editor (formerly CodeMirror) with Monaco, the editor engine used in VS Code. While this was a good bit of work under the hood, superficially it might not seem like a lot. This will give us a framework for more features. The first of these is proper paredit support (replacing the parinfer we had before). Please see the Hotkeys page for more details.
  • Monaco has a lot of features already, e.g. code folding (press F1 in the editor to see and search for commands and their keystrokes), and provides hooks for many language editing tasks which we hope to wire up over time.
  • At present the keybindings are still hardwired, but we plan to offer user-customized bindings.
  • Speaking of bindings there is a significant change to the default nav bindings - they now conform to the browser standards (Command-L/R, which was always intended but problematic before).

0.9.170

0.9.168

  • add a path of keys or parenthesized expressions to browser "nav->" to transform the elements in the viewer
  • browser "path" shows the path your browsing took
  • tap view has a "browse" button so that you can browse tap results as data
  • column sorts now use Clojure's compare where possible

0.9.157

0.9.149

  • Datafy support for csv, edn, json, and yaml files.
  • Tap pane now shows a list of recent tap> values.
  • "def as…" now works correctly with unprintable/unreadable Objects.

0.9.109

  • Initial release.