suitable - Addon for Figwheel and Emacs CIDER to aid exploratory development in ClojureScript

This project is a code completion backend for interactive repls and editors that use runtime introspection to provide "IntelliSense" support. This can be extremely useful and productive if you're experimenting around with unknown APIs.

For example you work with DOM objects but can't remember how to query for child elements. Type (.| js/document) (with | marking the postion of your cursor) and press TAB. Methods and properties of js/document will appear — including querySelector and querySelectorAll.

Currently Emacs (via CIDER) and figwheel.main are supported. If you want support for your favorite tool please let me know and I'll look into it (no promises, though).

Demo

The animation shows how various properties and methods of the native DOM can be accessed (Tab is used to show completions for the expression at the cursor):

Setup

figwheel.main with rebel-readline

Please note that you need to use rebel-readline with figwheel for that to work. Plain repls have no completion feature.

Tools CLI

First make sure that the normal Tools CLI setup works.

Then modify your deps.edn so that org.rksm/suitable and it's setup code are included:

:aliases {:suitable {:extra-deps {org.rksm/suitable {:mvn/version "0.2.13"}}
                     :main-opts ["-e" "(require,'suitable.hijack-rebel-readline-complete)"
                                 "-m" "figwheel.main"
                                 "--build" "dev" "--repl"]}}

Also add a preload to your dev.cljs.edn:

{:main hello-world.core
 :preloads [suitable.js-introspection]}

Finally start a figwheel repl via clj -A:suitable.

leiningen

First make sure that the normal leiningen setup works.

Add [org.rksm/suitable "0.2.13"] to your dependencies vector.

Then you can start a repl with lein trampoline run -m suitable.figwheel.main -- -b dev -r

Emacs CIDER

Suitable is now a default middleware in CIDER (as of CIDER 0.22.0)! So no extra installation steps are required.

Custom nREPL server

To load suitable into a custom server you can load it using this monstrosity:

clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.22.0"} cider/piggieback {:mvn/version"0.4.1"}}}' -m nrepl.cmdline --middleware "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"

Or from within Clojure:

(ns my-own-nrepl-server
  (:require cider.nrepl
            cider.piggieback
            nrepl.server))

(defn start-cljs-nrepl-server []
(let [middlewares (conj (map resolve cider.nrepl/cider-middleware)
                        #'cider.piggieback/wrap-cljs-repl)
      handler (apply nrepl.server/default-handler middlewares)]
  (nrepl.server/start-server :handler handler))

How does it work?

suitable uses the same input as the widely used compliment. This means it gets a prefix string and a context form from the tool it is connected to. For example you type (.l| js/console) with "|" marking where your cursor is. The input we get would then be: prefix = .l and context = (__prefix__ js/console).

suitable recognizes various ways how CLJS can access properties and methods, such as ., .., doto, and threading forms. Also direct global access is supported such as js/console.log. suitable will then figure out the expression that defines the "parent object" that the property / method we want to use belongs to. For the example above it would be js/console. The system then uses the EcmaScript property descriptor API to enumerate the object members. Those are converted into completion candidates and send back to the tooling.

License

This project is MIT licensed.