Building a plugin i Light Table
This is the first post in (hopefully) a series of blog posts about the various steps I go through when trying to create a plugin for Light Table. I have decided to try to create a Groovy plugin. I chose Groovy to ensure there was at least one technology fairly familiar to me. I have just started using Light Table, I have no previous experience with ClojureScript and I have just recently started writing some Clojure beyond the basic tutorials.
The short term goal is for the plugin to provide inline results and maybe an instarepl of some sort for groovy scripts.
LightTable-Groovy is the name of my plugin project and you can find the latest source there. It might be a couple of steps ahead of the blog posts though !
LightTable-Groovy is the name of my plugin project and you can find the latest source there. It might be a couple of steps ahead of the blog posts though !
Documentation
Light Table was made open source in january and documentation for plugin developers is a little sparse. So to have something to go by I decided to use some of the other language plugins as inspiration:
- Python plugin (comes bundled/under the light table umbrella)
- Ruby Instarepl
- Haskell plugin
I haven't worked with any of the above mentioned languages, but they did provide enough inspiration to deduce how a Light Table client might interact.
BTW. A quick starter just to get you up an running with a hello world plugin could be this screen cast by Mike Haney.
Connecting a client - Process overview
Before we dwelve into the code It's a good idea to have a high level understanding of what we are trying to achieve !
A couple of use cases that needs to be supported:
- Evaluate current selection or current line of groovy code and present results (preferably inline)
- Evaluate contents of current editor and present results
- Provide as much info about the results of each statement as possible
- (Maybe need to evaluate line/statement by statement)
- For a future instarepl, any change in the editor will trigger an evaluation
It becomes evident that our plugin needs to provide some kind of process that reacts to events from light table. A default pattern for achieving this has been devised for Light Table and roughly equates to the following steps:
- A connect event is triggered from Light Table (you need to set up your plugin to trigger that event…). Typically the connect event can be invoked manually from the connect bar in light table, or it can be triggered implicetly when evaluating code.
- You fire of a process - Using inbuilt support from Light Table you start a process either a shell script or whatever really. I created a shell script that sets some environment stuff and then basically kicks off a groovy script. Light table provides a tcp/ip port and a unique client id which you need to forward to the process.
- Create a tcp client: In your process you create a tcp client using the given port
- Send ack message: Send a json message with client id and an event name (behavior) to Light Table (through the tcp connection!)
- Confirm handshake for process: In your process (i.e. not the tcp connection!) write "Connected" to standard out. ("Connected" is just what the other plugins use, you could use anything you like as long as it matches the connect behaviors(handlers) you provide inside light table.)
- Listen for events: Now you are connected and given you have set up your behaviors in Light Table correctly, your new connection should be reported as connected and shown in the Light Table connect bar. Now you listen for events on your tcp client and provides appropriate responses back to Light Table accordingly. (Handling this is the subject of a future blog post)
Behaviors for connecting (from groovy.cljs):
(defn run-groovy[{:keys [path name client] :as info}]
(let [obj (object/create ::connecting-notifier info)
client-id (clients/->id client)
project-dir (files/parent path)]
(object/merge! client {:port tcp/port
:proc obj})
(notifos/working "Connecting..")
(proc/exec {:command binary-path
:args [tcp/port client-id project-dir]
:cwd plugin-dir
:env {"GROOVY_PATH" (files/join (files/parent path))}
:obj obj})))
(defn check-groovy[obj]
(assoc obj :groovy (or (::groovy-exe @groovy)
(.which shell "groovy"))))
(defn check-server[obj]
(assoc obj :groovy-server (files/exists? server-path)))
(defn handle-no-groovy [client]
(clients/rem! client)
(notifos/done-working)
(popup/popup! {:header "We couldn't find Groovy."
:body "In order to evaluate in Groovy files, Groovy must be installed and on your system PATH."
:buttons [{:label "Download Groovy"
:action (fn []
(platform/open "http://gvmtool.net/"))}
{:label "ok"}]}))
(defn notify [obj]
(let [{:keys [groovy path groovy-server client]} obj]
(cond
(or (not groovy) (empty? groovy)) (do (handle-no-groovy client))
:else (run-groovy obj))
obj))
(defn check-all [obj]
(-> obj
(check-groovy)
(check-server)
(notify)))
(defn try-connect [{:keys [info]}]
(.log js/console (str "try connect" info))
(let [path (:path info)
client (clients/client! :groovy.client)]
(check-all {:path path
:client client})
client))
(object/object* ::groovy-lang
:tags #{:groovy.lang})
(def groovy (object/create ::groovy-lang))
(scl/add-connector {:name "Groovy"
:desc "Select a directory to serve as the root of your groovy project... then again it might not be relevant..."
:connect (fn []
(dialogs/dir groovy :connect))})
(behavior ::connect
:triggers #{:connect}
:reaction (fn [this path]
(try-connect {:info {:path path}})))
- scl/add-connector: This statement adds a connect dialog to our groovy plugin. You select a root directory and upon selection the ::connect behavior is triggered
- ::connect basically responds with invoking a method for connecting. This does some sanity checks and if all goes well ends up invoking run-groovy.
- run-groovy : Fires up our groovy (server) process
- def groovy is basically the "mother" object of our plugin. It helps us scope behaviors and commands
The server part (LTServer.groovy)
import groovy.json.*
params = [
ltPort: args[0].toInteger(),
clientId: args[1].toInteger() // light table generated id for the client (connection)
]
logFile = new File("server.log")
def log(msg) {
logFile << "${new Date().format('dd.MM.yyyy mm:hh:sss')} - $msg\n"
}
client = null
try {
client = new Socket("127.0.0.1", params.ltPort)
} catch (Exception e) {
log "Could not connect to port: ${params.ltPort}"
throw e
}
def sendData(data) {
client << new JsonBuilder(data).toString() + "\n"
}
// ack to Light Table
sendData (
[
name: "Groovy",
"client-id": params.clientId,
dir: new File("").absolutePath,
commands: ["editor.eval.groovy"],
type: "groovy"
]
)
println "Connected" // tells lighttable we're good
client.withStreams {input, output ->
while(true) {
// insert code to listen for events from light table and respond to those (eval code etc)
}
}
Notification of successful conncetion
(behavior ::on-out
:triggers #{:proc.out}
:reaction (fn [this data]
(let [out (.toString data)]
(object/update! this [:buffer] str out)
(if (> (.indexOf out "Connected") -1)
(do
(notifos/done-working)
(object/merge! this {:connected true}))
(object/update! this [:buffer] str data)))))
(behavior ::on-error
:triggers #{:proc.error}
:reaction (fn [this data]
(let [out (.toString data)]
(when-not (> (.indexOf (:buffer @this) "Connected") -1)
(object/update! this [:buffer] str data)
))
))
(behavior ::on-exit
:triggers #{:proc.exit}
:reaction (fn [this data]
;(object/update! this [:buffer] str data)
(when-not (:connected @this)
(notifos/done-working)
(popup/popup! {:header "We couldn't connect."
:body [:span "Looks like there was an issue trying to connect
to the project. Here's what we got:" [:pre (:buffer @this)]]
:buttons [{:label "close"}]})
(clients/rem! (:client @this)))
(proc/kill-all (:procs @this))
(object/destroy! this)
))
(object/object* ::connecting-notifier
:triggers []
:behaviors [::on-exit ::on-error ::on-out]
:init (fn [this client]
(object/merge! this {:client client :buffer ""})
nil))
The above behaviors basically handles signaling success, error or connection exits for our groovy client. As you can see in ::on-out this is where we check standard out from the process for the string "Connected", to signal success.
Wiring up behaviors (behaviors.groovy)
{:+ {:app [(:lt.objs.plugins/load-js ["codemirror/groovy.js", "groovy_compiled.js"])]
:clients []
:editor.groovy []
:files [(:lt.objs.files/file-types
[{:name "Groovy" :exts [:groovy] :mime "text/x-groovy" :tags [:editor.groovy]}])]
:groovy.lang [:lt.plugins.groovy/connect]}}
The important part in terms on the connection is the wiring of the connect behavior to ":groovy.lang". This is needed for groovy to appear as a connection item in the light table connect bar.
"codemirror/groovy.js" deserves a special mention. This is what provides syntax highlighting for our groovy files (defined in the :files vector). The syntax highlighting is provided by the groovy mode module from CodeMirror.
"codemirror/groovy.js" deserves a special mention. This is what provides syntax highlighting for our groovy files (defined in the :files vector). The syntax highlighting is provided by the groovy mode module from CodeMirror.
Wrapping up
So what have we achieved. Well we now have a connection to Light Table from an external process that can listen and respond to events from Light Table. For the purposes of this blog post series, its a Groovy client that hopefully pretty soon will be able to evaluate groovy scripts and respond with evaluation results. We didn't pay much attention to it, but we also got syntax highlighting of our Groovy files complements of CodeMirror.
It took a while to grok how the connection part worked. Once I did understand roughly what was needed I was a bit annoyed with myself for messing about so much. I'm hoping this post might help others to avoid some of the mistakes I stumbled into.
