First Contribution

This tutorial assumes you have a basic familiarity with Clojure(Script) and using Light Table. If you don't, I recommend David Nolen's ClojureScript Tutorial and the first couple of tutorials. Let's get started on your first contribution!

Getting Started

The contribution you're going to add is a command for printing command stats. While such a command would normally be added through a plugin, we're adding it to Light Table here as an exercise. This tutorial assumes you're contributing to Light Table core. If you were contributing to a Light Table plugin, you would use a forked version of the plugin instead of a forked Light Table but most of the workflow still applies.

First, you'll need to fork Light Table and build a local version of it using these instructions. The install script will take a few minutes. Once it's done, you can start an edge version of LightTable from the commandline e.g. deploy/light on OS X.

With Light Table open, add your fork as a folder using the command add folder. Then open sidebar/command.cljs with the navigate pane or Cmd-O. The file you're looking at is responsible for the command pane you invoke with Ctrl-Space.

Light Table UI, Console and Eval

Before writing the command, let's start a connection to eval ClojureScript. Run the command Add Connection and choose Light Table UI. To confirm this works try evaling something at the bottom of the file e.g. (inc 1). PressCmd-Enter to eval that expression and see the result of 2. Be sure to only eval the given expression. When evaling in a core file such as this, evaling the whole file with Cmd-Shift-Enter can have drastic consequences i.e. reset critical state.

It will be useful to have the console open while developing. Run the command Toggle console to open it at the bottom. Verify the console works by printing something e.g. (prn "Hey!").

Write a command

Now you're ready to write a command. Let's add it to the bottom of the file. As you can see from other commands, the command function takes a map. That map must contain keys of :command, :desc and :exec that respectively are a unique id, a description you see in the command pane and the function invoked by a command. Let's start with a basic test command:

(cmd/command {:command :command-stats
          :desc "App: Print command stats"
          :exec (fn []
                   (prn "TEST"))})

After evaling that expression, run the command by typing its description in the command pane!

Now let's add some actual functionality. Command information is stored in the atom cmd/manager under the :commands key. Eval the atom thinking of how you can get a command count. You'll want to eventually wind up with an expression similar to (-> @cmd/manager :commands count). Replace "TEST" with that expression and re-eval your command. You should see the command print your command count!

Improve the command

You'll notice the command currently prints to the console. While this is good for debugging, we can do better. Let's pull in the notifos namespace to improve this. At the top of the file add this in the :require section [lt.objs.notifos :as notifos]. After adding it, Cmd-Enter to eval it. Replace prn with notifos/set-msg!, eval and the count should now print in the bottom status bar!

If you spend more time playing with the command map, you'll see that commands can have additional keys e.g. (->> @cmd/manager :commands vals (map keys)). One such additional key is :hidden which is used to hide commands from the command pane. Try updating the command to include information about a public or hidden commands count. Here's one possible solution for how :exec could look to include that information:

(fn []
  (notifos/set-msg!
    (str
      "Commands: "
      (->> @cmd/manager :commands vals (remove :hidden) count)
      " public / "
      (->> @cmd/manager :commands count)
      " total")))

Verify your work

Before finishing your contribution, it's important to verify this works without relying on eval. In order to do so, save your work and exit Light Table. Then from your Light Table fork directory, compile the latest ClojureScript with lein cljsbuild once. By compiling your ClojureScript to JavaScript, Light Table will be able to load the new command on startup. Open your edge Light Table and verify your new command is there.

And that's it! Congrats on working through this. Hopefully this will encourage you to make awesome contributions to Light Table.

Next Steps

Now that you have an idea of what it's like to contribute:

• See where we could use your help.
• Check out all the tutorials to make sure you understand the different aspects of Light Table as a user.
• Learn more about internals at the For Developers. If you have specific developer questions, they may already be answered in the Developer FAQ.
• Feel free to ask questions on the mailing list.

We look forward to your contribution!