REPL adventures

OSS updates March and April 2026

2026-05-04T23:59:59+00:00

In this post I'll give updates about open source I worked on during March and April 2026.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible. Without you, the below projects would not be as mature or wouldn't exist or be maintained at all! So a sincere thank you to everyone who contributes to the sustainability of these projects.

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

OSS updates January and February 2026

2026-03-05T23:59:59+00:00

In this post I'll give updates about open source I worked on during January and February 2026.

To see previous OSS updates, go here.

Sponsors

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

Babashka 1.12.215: Revenge of the TUIs

2026-02-17T23:59:59+00:00

Babashka is a fast-starting native Clojure scripting runtime. It uses SCI to interpret Clojure and compiles to a native binary via GraalVM, giving you Clojure's power with near-instant startup. It's commonly used for shell scripting, build tooling, and small CLI applications. If you don't yet have bb installed, you can with brew:

brew install borkdude/brew/babashka

or bash:

bash <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)

This release is, in my opinion, a game changer. With JLine3 bundled, you can now build full terminal user interfaces in babashka. The bb repl has been completely overhauled with multi-line editing, completions, and eldoc. deftype now supports map interfaces, making bb more compatible with existing libraries like core.cache. SCI has had many small improvements, making riddley compatible too. Riddley is used in Cloverage, a code coverage library for Clojure, which now also works with babashka (Cloverage PR pending).

Babashka conf 2026

But first, let me mention an exciting upcoming event! Babashka conf is happening again for the second time! The first time was 2023 in Berlin. This time it's in Amsterdam. The Call for Proposals is open until the end of February, so there is still time to submit your talk or workshop. We are also looking for one last gold sponsor (500 euros) to cover all costs.

Highlights

JLine3 and TUI support

Babashka now bundles JLine3, a Java library for building interactive terminal applications. You get terminals, line readers with history and tab completion, styled output, keyboard bindings, and the ability to reify custom completers, parsers, and widgets — all from bb scripts.

JLine3 works on all platforms, including Windows PowerShell and cmd.exe.

Here's a simple interactive prompt that reads lines from the user until EOF (Ctrl+D):

(import '[org.jline.terminal TerminalBuilder]
        '[org.jline.reader LineReaderBuilder])

(let [terminal (-> (TerminalBuilder/builder) (.build))
      reader   (-> (LineReaderBuilder/builder)
                   (.terminal terminal)
                   (.build))]
  (try
    (loop []
      (when-let [line (.readLine reader "prompt> ")]
        (println "You typed:" line)
        (recur)))
    (catch org.jline.reader.EndOfFileException _
      (println "Goodbye!"))
    (finally
      (.close terminal))))

babashka.terminal namespace

A new babashka.terminal namespace exposes a tty? function to detect whether stdin, stdout, or stderr is connected to a terminal:

(require '[babashka.terminal :refer [tty?]])

(when (tty? :stdout)
  (println "Interactive terminal detected, enabling colors"))

This accepts :stdin, :stdout, or :stderr as argument. It uses JLine3's terminal provider under the hood.

This is useful for scripts that want to behave differently when piped vs. run interactively, for example enabling colored output or progress bars only in a terminal.

charm.clj compatibility

charm.clj is a new Clojure library for building terminal user interfaces using the Elm architecture (Model-Update-View). It provides components like spinners, text inputs, lists, paginators, and progress bars, with support for ANSI/256/true color styling and keyboard/mouse input handling.

charm.clj is now compatible with babashka (or rather, babashka is now compatible with charm.clj), enabled by the combination of JLine3 support and other interpreter improvements in this release. This means you can build rich TUI applications that start instantly as native binaries.

Here's a complete counter example you can save as a single file and run with bb:

#!/usr/bin/env bb

(babashka.deps/add-deps
 '{:deps {io.github.TimoKramer/charm.clj {:git/sha "cf7a6c2fcfcccc44fcf04996e264183aa49a70d6"}}})

(require '[charm.core :as charm])

(def title-style
  (charm/style :fg charm/magenta :bold true))

(def count-style
  (charm/style :fg charm/cyan
               :padding [0 1]
               :border charm/rounded-border))

(defn update-fn [state msg]
  (cond
    (or (charm/key-match? msg "q")
        (charm/key-match? msg "ctrl+c"))
    [state charm/quit-cmd]

    (or (charm/key-match? msg "k")
        (charm/key-match? msg :up))
    [(update state :count inc) nil]

    (or (charm/key-match? msg "j")
        (charm/key-match? msg :down))
    [(update state :count dec) nil]

    :else
    [state nil]))

(defn view [state]
  (str (charm/render title-style "Counter App") "\n\n"
       (charm/render count-style (str (:count state))) "\n\n"
       "j/k or arrows to change\n"
       "q to quit"))

(charm/run {:init {:count 0}
            :update update-fn
            :view view
            :alt-screen true})

More examples can be found here.

Deftype with map interfaces

Until now, deftype in babashka couldn't implement JVM interfaces like IPersistentMap, ILookup, or Associative. This meant libraries that define custom map-like types, a very common Clojure pattern, couldn't work in babashka.

Starting with this release, deftype supports map interfaces. Your deftype must declare IPersistentMap to signal that you want a full map type. Other map-related interfaces like ILookup, Associative, Counted, Seqable, and Iterable are accepted freely since the underlying class already implements them.

This unlocks several libraries that were previously incompatible:

core.cache: all cache types (BasicCache, FIFOCache, LRUCache, TTLCache, LUCache) work unmodified
linked: insertion-ordered maps and sets

Riddley and Cloverage compatibility

Riddley is a Clojure library for code walking that many other libraries depend on. Previously, SCI's deftype and case did not macroexpand to the same special forms as JVM Clojure, which broke riddley's walker. Several changes now align SCI's behavior with Clojure: deftype macroexpands to deftype*, case to case*, and macroexpand-1 now accepts an optional env map as second argument (inspired by how the CLJS analyzer API works). Together these changes enable riddley and tools built on it, like cloverage and Specter, to work with bb.

Riddley has moved to clj-commons, thanks to Zach Tellman for transferring it. I'd like to thank Zach for all his contributions to the Clojure community over the years. Version 0.2.2 includes bb compatibility, which was one of the first PRs merged after the transfer. Cloverage compatibility has been submitted upstream, all 75 cloverage tests pass on both JVM and babashka.

Console REPL improvements

The bb repl experience has been significantly improved with JLine3 integration. You no longer need rlwrap to get a comfortable console REPL:

Multi-line editing: the REPL detects incomplete forms and continues reading on the next line with a #_=> continuation prompt
Tab completion: Clojure-aware completions powered by SCI, including keywords (:foo, ::foo, ::alias/foo)

Ghost text: as you type, the common completion prefix appears as faint inline text after the cursor. Press TAB to accept.

Eldoc: automatic argument help — when your cursor is inside a function call like (map |), the arglists are displayed below the prompt
Doc-at-point: press Ctrl+X Ctrl+D to show full documentation for the symbol at the cursor
Persistent history: command history saved across sessions in ~/.bb_repl_history
Ctrl+C handling: first press on an empty prompt warns, second press exits

Many of these features were inspired by rebel-readline, Leiningen's REPL, and Node.js's REPL.

SCI improvements

Under the hood, SCI (the interpreter powering babashka) received many improvements in this cycle:

Functional interface adaptation for instance targets: you can now write (let [^Predicate p even?] (.test p 42)) and SCI will adapt the Clojure function to the functional interface automatically.
Type tag inference: SCI now infers type tags from let binding values to binding names, reducing the need for explicit type hints in interop-heavy code.
Several bug fixes: read with nil/false as eof-value, letfn with duplicate function names, ns-map not reflecting shadowed vars, NPE in resolve, and .method on class objects routing incorrectly.

Other improvements

Support multiple catch clauses in combination with ^:sci/error
Fix satisfies? on protocols with proxy
Support reify with java.time.temporal.TemporalQuery
Fix reify with methods returning int/short/byte/float primitives
nREPL server now uses non-daemon threads so the process stays alive without @(promise)
Add clojure.test.junit as built-in source namespace
Add cp437 (IBM437) charset support in native binary via selective GraalVM charset Feature, avoiding the ~5MB binary size increase from AddAllCharsets. More charsets can be added on request.

For the full list of changes including new Java classes and library bumps, see the changelog.

Thanks

Thank you to all the contributors who helped make this release possible. Special thanks to everyone who reported issues, tested pre-release builds from babashka-dev-builds, and provided feedback.

Thanks to Clojurists Together and all babashka sponsors and contributors for their ongoing support. Your sponsorship makes it possible to keep developing babashka.

And thanks to all babashka users: you make this project what it is. Happy scripting!

OSS updates November and December 2025

2026-01-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during November and December 2025.

To see previous OSS updates, go here.

Sponsors

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

Thanks for giving!

2025-11-26T23:59:59+00:00

Dear sponsors,

As we approach Thanksgiving once again, I’m reminded that sustained open source software development, supported by long term sponsors, is not something to take for granted.

I’m genuinely grateful for your ongoing support through GitHub Sponsors. Your contributions make a real difference: my Clojure projects wouldn’t be nearly as polished, maintained, or ambitious without your help.

If you’d like to look back on what happened in open source this past year, you can find an overview here: https://blog.michielborkent.nl/tags/oss-updates.html. The core projects remain clj-kondo, babashka, SCI, scittle, and squint/cherry. Each of them continues to grow in capability and adoption.

I’ve also applied for Clojurists Together again for 2026. If you’re a CT sponsor, a vote in the next long-term funding round would be appreciated.

Here are the main ideas I want to explore in 2026:

Clj-kondo: run macros directly from source code
Clj-kondo: run exported configs/hooks directly from classpath (instead of having to copy files to a local dir)
Squint/Cherry: browser nREPL support
Squint/Cherry: source maps
Squint: protocolize coll functions so you can extend them to e.g. ImmutableJS or other custom collections
Scittle2 (working name): better/faster/smaller version of Scittle using Cherry (in-browser CLJS compiler)
Babashka: support CIDER middleware from source directly in bb
Babashka: distinguished parallel task output (e.g. colors or prefix)
Clj-kondo: add first-class support for Clojure dialects like ClojureDart and Jank
Clojure CLI: help improve UX via a new tools working group
Clj-kondo: performance improvements for bigger projects

I can't make any promises on hard deadlines, but I definitely intend to work toward realizing the above goals.

Aside from software development, I'm also organizing Babashka Conf 2026 the day before Dutch Clojure Days.

As always, feel free to reach out anytime, whether here, on Clojurians Slack, or by email at michielborkent@gmail.com. I love hearing about what you are doing with my projects. Also if you are struggling with something, let me know. Your feedback and use cases continue to shape the direction of my work.

Here’s to another strong year of Clojure OSS!

Thank you for making this journey possible.

With appreciation,

Michiel Borkent / @borkdude

PS: if you aren't sponsoring, but are interested, here are the main ways to do so:

Sponsor info

OSS updates September and October 2025

2025-11-02T23:59:59+00:00

In this post I'll give updates about open source I worked on during September and October 2025.

To see previous OSS updates, go here.

Sponsors

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

Reagami: a Reagent-like library in less than 100 lines of Squint CLJS

2025-10-24T23:59:59+00:00

Recently I've been excited about Eucalypt, a Reagent-clone in pure Squint. For those who don't know Squint, it is a CLJS dialect that re-uses JS features as much as possible. Maps and vectors compile directly to objects and arrays for example. The standard library mimics that of Clojure(Script). Collections, although they are mutable in JS, are treated immutably via shallow-copying. You can build small apps in Eucalypt starting at about 9kb gzip. When looking at the code, I wondered if we could make an ultra-simple Reagent-like library with less features for even smaller apps. If I understand Eucalypt correctly, it produces DOM nodes from hiccup and then patches the already mounted DOM nodes using a diffing algorithm. I tried to do this in under 100 lines, in a more basic fashion. I call this library Reagami, a library you can use to fold your state into the DOM!

Let's explain how it works.

Rendering Hiccup to DOM nodes

Below you see the create-node function, which takes hiccup, e.g. [:div "Hello"] and transforms it into a DOM node. I placed comments in the code that help you understand it, hopefully.

(defn- create-node
  ([hiccup] (create-node hiccup false))
  ([hiccup in-svg?]
   (cond
;; we compile primitives directly into TexNodes
     (or (nil? hiccup)
         (string? hiccup)
         (number? hiccup)
         (boolean? hiccup))
     (js/document.createTextNode (str hiccup))
;; vectors indicate a DOM node literal or a function call
     (vector? hiccup)
     (let [[tag & children] hiccup
;; here we pull apart id and class shortcuts like: `:div#my-id.my-class`
           [tag id class] (if (string? tag) (parse-tag tag) [tag])
           classes (when class (.split class "."))
;; hiccup vectors can have an optional map to set attributes of the DOM node
          [attrs children] (if (map? (first children))
                              [(first children) (rest children)]
                              [nil children])
;; SVG needs special handling, SVG nodes need to be created with `createElementNS`, see below
           in-svg? (or in-svg? (= :svg tag))
;; if we encounter a function as the first element, e.g. `[my-component]`, we call it
           node (if (fn? tag)
                  (let [res (apply tag (if attrs
                                         (cons attrs children)
                                         children))]
;; and then we feed the result back into create-node
                    (create-node res in-svg?))
;; so here we create the DOM element, either a normal or an SVG one
                  (let [node (if in-svg?
                               (js/document.createElementNS svg-ns tag)
                               (js/document.createElement tag))]
;; here we iterate over all the children in the hiccup vector
                    (doseq [child children]
;; in squint, vectors are also seqs, but here we want to make sure the result is list-like,
;; e.g. the result from `(for [i xs] [my-component])`
;; if that is the case, then we map create-node over those results
                      (let [child-nodes (if (and (seq? child)
                                                 (not (vector? child)))
                                          (mapv #(create-node % in-svg?) child)
;; else, we have only one node as the result of calling create-node on the child
                                          [(create-node child in-svg?)])]
;; let's add all the child-nodes to the DOM element created from the tag!
                        (doseq [child-node child-nodes]
                          (.appendChild node child-node))))
;; attribute handling: for each key and value in the attribute map:
                    (doseq [[k v] attrs]
                      (let [key-name k]
                        (cond
;; Let's create some CSS if the style attribute is a msp!
                          (and (= "style" key-name) (map? v))
                          (doseq [[k v] v]
                            (aset (.-style node) k v))
;; if the attribute starts with "on", then we add an event handler
                          (.startsWith key-name "on")
;; we support :on-click, :on-mouse-down, :onMouseDown, etc.
                          (let [event (-> (subs key-name 2)
                                          (.replaceAll "-" "")
                                          (.toLowerCase))]
                            (.addEventListener node event v))
;; if the attribute false is false or nil, we ignore it
                          :else (when v
                                  (.setAttribute node key-name (str v))))))
;; classes parsed from the tag, e.g. `:div.my-class1.my-class2`
                    (let [class-list (.-classList node)]
                      (doseq [clazz classes]
                        (.add class-list clazz)))
;; finally we handle the id parsed from the tag, e.g. `:div#my-id`
                    (when id
                      (set! node -id id))
                    node))]
       node)
     :else
     (throw (do
              (js/console.error "Invalid hiccup:" hiccup)
              (js/Error. (str "Invalid hiccup: " hiccup)))))))

That's it! Pretty simple.

Patching the DOM

If we simply just re-insert the generated hiccup DOM nodes into the DOM every time something changes, then we have several problems. E.g. when we are typing in an input field and we insert a new input field, we lose focus. Also we lose event handlers, although this isn't really an issue if we re-generate them via the hiccup-to-DOM function above. A better approach is to cleverly patch the DOM and re-use existing DOM nodes when possible.

The patch function takes a parent node, some child nodes and tries to re-use or insert the children. There are several libraries that do this far more intelligently than the below function. E.g. Idiomorph is such a library. One problem I encountered with Idiomorph is that it doesn't preserve event listeners. There's also Snabbdom, a small but effective vDOM library that you could use. But where's the fun in that, if you can make your own naive patch function. Here we go! When we render a component for the first time, Reagami calls patch with the root node (usually something like (js/document.querySelector "#app")) and the rendered hiccup as the only child. Read along with the comments again.

(defn- patch [parent new-children]
;; First we take a look at the current children of the root node, already mounted in the DOM
  (let [old-children (.-childNodes parent)]
;; If the amount of children isn't the same, we just give up and replace all the children with the new children.
;; This typically happens on first render or when elements disappear due to conditionals in the hiccup code.
;; More mature patching libraries do much more clever things here
;; but I've found this works well enough for the basic use cases I tested.
    (if (not= (count old-children) (count new-children))
      (parent.replaceChildren.apply parent new-children)
;; When the number of children is the same we compare them one by one.
      (doseq [[old new] (mapv vector old-children new-children)]
        (cond
          (and old new (= (.-nodeName old) (.-nodeName new)))
;; Only when the node names are the same, we consider it the same node.
;; If it's Text node, we need to copy over the text content.
          (if (= 3 (.-nodeType old))
            (let [txt (.-textContent new)]
              (set! (.-textContent old) txt))
            (let [new-attributes (.-attributes new)
                  old-attributes (.-attributes old)]
;; Here we just set all the attribues from the new node to the old node.
              (doseq [attr new-attributes]
                (.setAttribute old (.-name attr) (.-value attr)))
              (doseq [attr old-attributes]
;; When an existing attribute in the old node, doesn't occur in the new node, we remove it
                (when-not (.hasAttribute new (.-name attr))
                  (.removeAttribute old (.-name attr))))
;; Then we recursively descend into the children of the new node.
              (when-let [new-children (.-childNodes new)]
                (patch old new-children))))
;; If the node names aren't the same, we replace the node completely with the new node.
          :else (.replaceChild parent new old))))))

Putting it all together

Reagami's only public function is called render which is just:

(defn render [root hiccup]
  (let [new-node (create-node hiccup)]
    (patch root [new-node])))

With this single function, you can write a small reactive app, if we combine it with atom and add-watch. Here's an example of this:

(ns my-app
  (:require ["https://esm.sh/reagami@0.0.8" :as reagami]))

(def state (atom {:counter 0}))

(defn my-component []
  [:div
   [:div "Counted: " (:counter @state)]
   [:button {:on-click #(swap! state update :counter inc)}
    "Click me!"]])

(defn render []
  (reagami/render (js/document.querySelector "#app") [my-component]))

(add-watch state ::render (fn [_ _ _ _]
                            (render)))

(render)

(Open this example on the Squint playground)

That's it: a Reagent-like library in less than 100 lines of code!

Further ideas:

Blending hiccup and patching so we don't even need to create DOM nodes for stuff that hasn't changed
Or remember the hiccup we generated on the previous change, compare that since that's more efficient? (I believe Eucalypt does this).
Better patching by looking at IDs or keys

Examples

Here are some examples you can play with on the Squint playground:

OSS updates July and August 2025

2025-08-05T23:59:59+00:00

In this post I'll give updates about open source I worked on during July and August 2025.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible. Without you the below projects would not be as mature or wouldn't exist or be maintained at all! So a sincere thank you to everyone who contributes to the sustainability of these projects.

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

OSS updates May and June 2025

2025-07-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during May and June 2025.

To see previous OSS updates, go here.

Sponsors

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

OSS updates March and April 2025

2025-05-02T23:59:59+00:00

In this post I'll give updates about open source I worked on during March and April 2025.

To see previous OSS updates, go here.

Sponsors

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

Babashka Java interop, reflection and type hints

2025-04-26T23:59:59+00:00

Consider the following Clojure code:

(def thread-pool (java.util.concurrent.Executors/newCachedThreadPool))
(def fut (.submit thread-pool (fn [] 3)))
@fut ;;=> ?

I didn't use any type hints, but the names of the vars should give you an idea what's happening:

a thread pool is created
a piece of work in the form of a function is submitted
the thread pool returns a future which we can dereference to do a blocking wait and get the result.

What result would you expect this program to give? My initial guess would be 3.

However, in babashka the result would sometimes be nil (version 1.12.199 on macOS Apple silicon does for example). I've seen this happen in JVM Clojure too in CI (given no type hints, and thus relying on Clojure reflection). I discovered this problem when trying to make bb run the fusebox library and executing its test suite in CI using babashka.

What's the mechanism behind this flakiness? The .submit method in the snippet above is overloaded. When Clojure is doing reflection, it finds the most suitable method for .submit given the instance object and the arguments. In this case the type of the instance object (the thread-pool value) is of type java.util.concurrent.ThreadPoolExecutor, which has three overloads (inherited from java.util.concurrent.AbstractExecutorService):

public Future submit(Runnable task)
public Future submit(Runnable task, T result)
public Future submit(Callable task)

Only two of those match the number of arguments we used in the snippet, so we are left with:

public Future submit(Runnable task)
public Future submit(Callable task)

Clojure's reflector will try to see if the argument type to .submit matches any of these methods. Since we called it with a function, in this case it matches both. If multiple methods match, it will try to pick the most specific method using clojure.lang.Compiler/subsumes. Since Runnable and Callable are two distinct types (one doesn't inherit from the other), Clojure's reflector just returns the first method it deemed most suitable. So it could be either method. The java documentation mentions the submit method with the Runnable argument first, but this isn't necessarily the order in which Java reflection will list those methods. I have found out that the order may even be indeterministic over multiple CI runs and JVM implementations or versions. What the exact cause of this indeterminism is, I don't know, but I found out the hard way that it exists 😅.

So when does the above snippet return nil? When the Runnable overload is chosen, since Runnable is an interface with run method that returns void (which is nil in Clojure). Let me show this using a snippet that uses JVM Clojure type hinting, where we don't rely on reflection:

(set! *warn-on-reflection* true)

(def ^java.util.concurrent.ThreadPoolExecutor thread-pool
  (java.util.concurrent.Executors/newCachedThreadPool))
(def fut (.submit thread-pool ^Runnable (fn [] 3)))
@fut  ;; => nil

Now let's do the same with Callable:

(set! *warn-on-reflection* true)

(def ^java.util.concurrent.ThreadPoolExecutor thread-pool
  (java.util.concurrent.Executors/newCachedThreadPool))
(def fut (.submit thread-pool ^Callable (fn [] 3)))
@fut ;; => 3

So we see the issue: depending on the overload of .submit we get a different value when we dereference the future, either nil or the value returned from the function.

So far, babashka has relied exclusively on runtime reflection to implement Java interop. So we do get into a problem with the above snippet, unless we add type hints. But so far babashka, or more specifically, SCI hasn't made use of type hints to determine the most suitable method. The Clojure compiler does this, but as you know, SCI interprets code and doesn't make use of the clojure Compiler. It does use a forked version of clojure.lang.Reflector, clojure's runtime reflection code, aptly renamed to sci.impl.Reflector. So far, pretty much the only change to that code was making some methods public that were used internally by SCI. To fix the above problem, SCI now actually makes use of type hints and passes these to sci.impl.Reflector. So in the newly published version of babashka, this code:

(def thread-pool (java.util.concurrent.Executors/newCachedThreadPool))
(def fut (.submit thread-pool ^Callable (fn [] 3)))
@fut ;;=> 3

will consistently return 3 and when changing Callable to Runnable, you'll get nil. Note that the above snippet will still have the ambiguous behavior in JVM Clojure, since it doesn't have enough type hints to figure out the right method at compile time and clojure.lang.Reflector does nothing with type hints. Once the Clojure compiler finds out that you're calling .submit on a java.util.concurrent.ExecutorService though, the code will run with the expected method.

Can you think of more methods in the Java standard library which have this ambiguity when relying solely on Clojure reflection? I'd love to hear about those to see if they work reliably in babashka given some extra help through type hints.

Thanks to Tim Pote for thinking along when fixing the issues in babashka and reading a preview of this blog post.

OSS updates January and February 2025

2025-02-28T23:59:59+00:00

In this post I'll give updates about open source I worked on during January and February 2025.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible. Without you, the below projects would not be as mature or wouldn't exist or be maintained at all.

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

OSS updates November and December 2024

2024-12-31T23:59:59+00:00

In this post I'll give updates about open source I worked on during November and December 2024.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible. Without you, the below projects would not be as mature or wouldn't exist or be maintained at all.

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

Thanks for giving!

2024-11-27T23:59:59+00:00

Dear sponsors,

It's almost Thanksgiving again. We don't have this tradition here in The Netherlands, but I do think it's a good to have a special day to count our blessings. I feel very blessed because of your ongoing support. My Clojure projects wouldn't be as well maintained and fully featured if I didn't have the sponsoring that I have currently.

You can read about the past year of OSS updates (and further back) here. Main projects are still clj-kondo, babashka, SCI, scittle, squint.

You can read about my plans for the next year here (a vote would be appreciated as well if you happen to be a CT sponsor!).

Feel free to reach out if you want to contact me about anything. Here, on Clojurians Slack, e-mail (michielborkent@gmail.com) or otherwise. I'd love to chat and catch up with you about how you are using (some of) my projects.

Here's to another year of Clojure OSS! Thanks for your support!

I'd like to thank all the sponsors and contributors that make this work possible. Like you can read on Bozhidar Batsov's blog these aren't the easiest times for Open Source sponsored software. I have no reason to complain, but I did see a similar drop in sponsoring in the last year. I'm thankful for those who sponsored my projects in the past and even more for those who keep doing so!

Without you, the below projects would not be as mature or wouldn't exist or be maintained at all.

Current top tier sponsors:

Open the details section for more info about sponsoring.

Sponsor info

OSS updates December 2023

2023-12-31T23:59:59+00:00

In this post I'll give updates about open source I worked on during December 2023.

To see previous OSS updates, go here.

Happy new year!

First all, as this is the last day of 2023, I wish you all a happy new year. Hopefully many goods things may happen in the Clojure ecosystem. I'm grateful many of you have sponsored my work in 2023!

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible. Without you, the below projects would not be as mature or wouldn't exist or be maintained at all. Open the details section for more info.

Sponsor info

OSS updates November 2023

2023-12-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during November 2023.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible! Without you, the below projects would not be as mature or wouldn't exist or be maintained at all.

Open the details section for more info.

Sponsor info

Playing Advent of Code with Squint

2023-11-24T23:59:59+00:00

In the previous post I described how I built a Cloudflare worker with squint. This worker is part of my attempt to build a playground for squint in which you can play Advent of Code. Advent of Code is a series of programming puzzles published each day through December 1-25. By exercising puzzles solutions on squint, I'm able to detect missing or incompatible features compared to ClojureScript.

Playground

The Advent of Code playground can be loaded here.

This link redirects you to the most recent version and I'll be updating the redirected-to link if necessary.

Puzzle input

To play Advent of Code, you need to download your puzzle input:

(def input (str/trim (js-await (fetch-input 2017 1))))

The fetch-input function is pre-defined in this boilerplate gist and is loaded via the boilerplate query parameter. Advent of Code input is personalized and based on your Advent of Code account. This is why you are asked to fill in your Advent of Code token in the top of the UI. You can obtain this token by visiting Advent of Code, registering + logging in and then find the session cookie in the developer console. Copy paste this value into the UI and hit Save!. After doing so, the session token is saved in local storage for next puzzles you might want to solve. The session token is only saved in your browser. The Cloudflare worker doesn't store anything and only serves as a proxy.

REPL-mode

The playground has two ways of compiling Squint Clojurescript to JS: the normal ES6 mode and REPL-mode. In REPL-mode you're able to incrementally evaluate squint snippets. This works by compiling vars in keys of global objects, much like CLJS does it. E.g.:

(defn foo [])

is compiled to

var squint_core = await import('squint-cljs/core.js');
globalThis.user = globalThis.user || {};
globalThis.user.foo = (function () {
return null;
});
var foo = globalThis.user.foo;

in REPL-mode. This output certainly isn't optimal for JS bundlers like esbuild so it's only intended for development.

By hitting "Compile" the whole editor is compiled + evaluated. The compiled JavaScript is visible in the right output pane. When in REPL-mode, hitting Cmd-Enter (or Windows-Enter) with the cursor after a form will compile only that expression. Use the comment form to evaluate sub-expressions while working towards a complete solution.

While working on your puzzle, the state of the editor is saved to local storage, so if you accidentally close the browser, the input re-appear next time you visit the playground.

Let me know if you're enjoying this and feel free to post issues in the #squint channel on Clojurians Slack!

Writing a Cloudflare worker with squint and bun

2023-11-19T23:59:59+00:00

In this post I'll describe how to write a Cloudflare worker with squint and bun.

Introduction

As I tried to build an Advent of Code playground for squint, I wanted to support downloading puzzle input from adventofcode.com. Doing this directly from the playground resulted in CORS issues. Mario Trost in the #adventofcode channel on Clojurians Slack suggested that this could be solved using a Cloudflare worker and indeed it could. Thanks Mario!

A Cloudflare worker is tiny "serverless" application that scales automatically. The first 100k requests a day are free. A worker can be written in JavaScript, among other languages. Workers written in JavaScript can use the Fetch API which comprises of fetch, Request, Response and more standardized stuff, available as global objects in browsers, Node.js, deno, bun and other browser-inspired JavaScript runtimes. These APIs are basically all you need to build a worker.

Squint is a ClojureScript dialect designed for easier JS interop and smaller bundle output. As such, it seems like a good fit for Cloudflare workers. The smaller the code, the better the (cold) startup time.

Bun is a fast all-in-one JavaScript runtime / bundler / toolkit. Bun seems a good tool to use for developing Cloudflare workers since with little boilerplate you can get something running quickly. Bun supports hot reloading of worker code too.

Hello world

To produce a "hello world" worker only the following is necessary:

squint.edn:

{:paths ["src"]
 :extension "js"
 :output-dir "out"}

The Squint CLJS files are going into src and compiled .js files will be written to out.

The only source file:

src/index.cljs:

(ns index)

(defn ^:async handler [{:keys [method] :as req} _env _ctx]
  (js/Response. "hello world"))

(def default
  {:fetch handler})

Beware that your handler isn't going to be called fetch since this will conflict with js/fetch, something that tripped me up. So I just called it handler. Calling a var default in squint will make it the default export, which is something Cloudflare workers use.

Now run bun install squint-cljs and then bun squint watch. In parallel, run bun --hot out/index.js. This will spin up a server. You can make change to the code and new requests will see the changes. This is very convenient for local development and testing.

To bundle everything to a single file, run:

bun build --minify --outdir=dist/out/index.js

Then you can run bun dist/index.js to prove to yourself that the standalone JS works.

The standalone JavaScript file is somewhere around 2 kilobytes. Seriously: 2kb, that's it :)!

To deploy to Cloudflare, I'm using wrangler. It needs a small config file, called wrangler.toml which describes the name of the application and the location of the main JS file:

name = "hello-world"
main = "dist/index.js"
compatibility_date = "2023-09-04"

After writing the config file, you can run bun wrangler deploy. You will be asked to log in to the Cloudflare dashboard, etc. Eventually your application will be running at https://hellow-world..workers.dev.

Proxy

The final worker code can be seen below. The handler looks at an incoming request, and decides whether it's a GET or OPTION request. In the handling of the GET request, the URL params day, year and aoc-token are pulled out. While developing I noticed that the URLSearchParams object implements a Map-like ad-hoc interface, but squint's get function wasn't aware of this, so initially I couldn't use destructuring like this:

(let [{:keys [foo]} (-> (js/URL. "https://foo.com?foo=1") :searchParams)] foo)

to get foo out of this object. Similarly for the Headers object from Response. Both have a get method. I decided to make the squint get function work with any JS datastructure that has a get method. I'm not entirely sure if that is a good idea though since arbitrary methods called get may perform side effects... Let me know in the comments! But after doing so, destructuring worked on the search params.

Then a request is made to https://adventofcode.com to retrieve the input. When doing this from a non-browser, you don't get into any CORS issues. Note that we can nicely use js-await for waiting for promise results. The text that adventofcode.com returned is passed back along with "Access-Control-Allow-Origin" "* headers to satisfy all the CORS ... stuff.

I also noticed the browser playground was doing an OPTION request so I also need to handle those, returning the most permissive headers to satisfy the CORS gods.

src/index.cljs

(ns index)

(defn ^:async handler [{:keys [method] :as req} _env _ctx]
  (if (= :GET method)
    (let [params (-> req :url (js/URL.) :searchParams)
          {:keys [aoc-token day year]} params]
      (if (and aoc-token day year)
        (let [resp (js-await (js/fetch (str "https://adventofcode.com/" year "/day/" day "/input")
                                       {:headers {:cookie (str "session=" aoc-token)}}))
              body (js-await (.text resp))
              resp (js/Response. body {:headers {"Access-Control-Allow-Origin" "*"}})]
          resp)
        (js/Response. "Set 'aoc-token, 'day' and 'year' as a URL query parameter" {:status 400
                                                                                   :headers {"Access-Control-Allow-Origin" "*"}})))
    ;; response for :OPTION
    (js/Response. nil {:status 200
                       :headers {"Access-Control-Allow-Origin" "*"
                                 "Access-Control-Allow-Methods" "GET,HEAD,POST,OPTIONS"
                                 "Access-Control-Allow-Headers" "*"}})))

(def default
  {:fetch handler})

The final production JS is still around 2-3kb. After another bun wrangler deploy this browser playground for Advent of Code started working:

Advent of Code playground

You need to insert your Advent of Code session token in the input box, run Compile and after that it's stored in local storage, for other puzzles you might want to solve this year! Give it a spin and let me know what you think.

The source code for the worker is available here.

OSS updates October 2023

2023-11-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during October 2023.

To see previous OSS updates, go here.

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible! Open the details section for more info.

Sponsor info

Porting a ClojureScript project to Squint

2023-11-01T23:59:59+00:00

Squint

Squint is a ClojureScript syntax to JS compiler. I deliberately don't call it a CLJS compiler, since it has some differences with CLJS: all data structures in squint are just JS objects, arrays and iterators/generators. The standard library mimics ClojureScript in that it never mutates if CLJS doesn't mutate, e.g. assoc returns a new object and doesn't mutate the object argument. This approach has a few benefits and of course a few drawbacks. Some of the benefits are that JS interop becomes considerably easier, the bundle size becomes way smaller, in some cases performance is better (but as always, this is very contextual) and sharing a library to NPM to be consumed by other JavaScript projects becomes easier as well. A few drawbacks of this approach are that we lose structural sharing of CLJS data structures (the squint lib mostly uses copy-on-write like how CLJS once started) and you lose the fast equality checks you can get from structural sharing. Note that there is also squint's sister project, cherry which does use CLJS's immutable data structures, but you get a minimum of 350kb project size due to CLJS's standard library being bundled with it and not being optimizable by ES6 bundlers. Perhaps the extra bundle size offsets the drawbacks of squint's direct JS interop approach for you. But let's just see how far we can get with just squint in porting a ClojureScript project!

Clojure-mode

As a case study in this blog, we're going to look at clojure-mode, a project by Nextjournal which offers a Clojure mode for CodeMirror 6. A request was made some time ago to make this library usable directly from JavaScript as an NPM library. Since most of the code in this project is JS interop (using the excellent js-interop library) it seemed like a good candidate for a squint port. In Martin Kavalar of Nextjournal's own words:

I feel that codemirror and prosemirror extensions are especially well suited for squint as they are interop heavy and the libraries takes care of state using their own re-frame/redux like architecture

Martin asked me if I could do this in a way such that the library would still be usable from ClojureScript as well. One of the ways to accomplish this is to use .cljc files.

Reader conditionals

When porting the project, I added features and fixed bugs in squint to accommodate targeting both CLJS and squint. So almost every .cljs file was renamed to a .cljc file and CLJS-specific code like goog-define was re-implemented using a squint override:

#?(:squint (def node-js? (some? js/globalThis.process))
   :cljs (goog-define node-js? false))

The above expression checks whether we are inside NodeJS, which arguably could have been done without goog-define but my goal was to leave the original code as is.

Watcher

To ease developing, I added a watcher to the squint compiler, which reads the squint.edn file in your project and then automatically compiles all .cljs and .cljc files in your project to a corresponding .mjs file in an :output-dir (the extension is configurable):

squint.edn:

{:paths ["src-shared" "src-squint" "test"]
 :output-dir "dist"}

The watcher can be started with npx squint watch (or yarn squint watch or bun squint watch). In src-shared I put the files which are ported from the src directory, while src-squint has extra files that are specific for the squint port. The src directory contains CLJS-specific files that are not in scope for test.

When running npx squint compile all the files in :paths are re-compiled, which is handy when you want to distribute the project to NPM.

Symbolic namespaces

Before doing this port, other JS files had to be referenced using the JS library notation in the ns form:

(:require ["./my_other_ns.mjs"])

To increase sharing of code, I supported loading namespaces from squint.edn's :paths using the notation we're using to from Clojure(Script):

(:require [nextjournal.my-other-ns])

Stub macros

In a lot of places the js-interop library was used to create literals, functions with JS object destructuring, etc, most of which squint already does out of the box. To accommodate this, I wrote a bunch of macros which basically did nothing and replaces the j alias with a namespace which mocks the js-interop library:

(ns nextjournal.clojure-mode
  (:require ...
            #?@(:squint []
                :cljs [[applied-science.js-interop :as j]])
            ...)
  #?(:squint (:require-macros [applied-science.js-interop :as j])))

In squint, macros are (currently) loaded via the :require-macros section in a ns form. The squint compiler looks for a .cljc file within :paths, then loads this file using SCI, makes the transformation and the resumes compilation of the transformed form. The reason SCI is used is that squint doesn't know Clojure's data structures at run-time, but you can still use them at compile time. This model is pretty similar how CLJS executes macros on the JVM.

The stub macros for js-interop look like this:

(ns applied-science.js-interop
  (:refer-clojure :exclude [defn get get-in fn let select-keys assoc!]))

(defmacro lit [x] x)

(defmacro defn [& body]
  `(clojure.core/defn ~@body))

(defmacro get-in [& body]
  `(clojure.core/get-in ~@body))

(defmacro fn [& body]
  `(clojure.core/fn ~@body))

(defmacro let [& body]
  `(clojure.core/let ~@body))

(defmacro call-in [obj path & fs]
  `(.. ~obj ~@(map #(symbol (str "-" %)) path) ~@(map list fs)))

...

As you can see, most of the macros just defer to squint's default behavior. But a macro like call-in, which isn't part of squint, transforms to just raw JS interop.

Tests

Luckily the clojure-mode project has a lot of tests. They generally have this shape:

(deftest enter-and-indent
  (are [input expected]
      (= (apply-cmd commands/enter-and-indent input) expected)

    "(|)" "(\n |)"
    "((|))" "((\n  |))"
    "(()|)" "(()\n |)"
    "(a |b)" "(a\n  |b)"
    "(a b|c)" "(a b\n  |c)"))

Squint does not have a testing framework. Currently my thinking is that users should just use Node's built-in testing framework when writing squint projects or whatever else people use for front-end testing. Initially I started porting the tests to top level doseq forms, like:

(doseq [[input expected]
        (partition 2
                   ["(|)" "(\n |)"
                    "((|))" "((\n  |))"
                    "(()|)" "(()\n |)"
                    "(a |b)" "(a\n  |b)"
                    "(a b|c)" "(a b\n  |c)"])]
  (assert.equal (apply-cmd commands/enter-and-indent input) expected))

but this got old really fast since I needed to duplicate 17 tests with dozens of test cases each. So I wrote a really hacky macro which took the deftest + are forms and rewrote them to the doseq forms I initially wrote manually, yielding the following ns form in the test namespace:

(ns nextjournal.clojure-mode-tests
  (:require #?@(:squint []
                :cljs [[cljs.test :refer [are testing deftest]]])
            ...
            #?(:squint ["assert" :as assert]))
  #?(:squint (:require-macros [nextjournal.clojure-mode-tests.macros :refer [deftest are testing]])))

Note that instead of (is (= ...)) I'm using Node's assert.equal which performs deep equality and gives nice error messages about non-equal cases. Running the squint tests in CI is now just a matter of running:

$ node dist/nextjournal/clojure_mode_tests.mjs

Truthiness

Once I got the tests running, I discovered some interesting bugs. Before doing the port, squint just used JS's own truthiness. This causes unexpected bugs with code like (or (foo) 1) when foo was a function that could return 0. In JavaScript, 0 is falsey. This was by far the most important cause of bugs in the squint port. After experiencing this pain, I decided to adopt CLJS truthiness in squint, such that (or 0 1) returns 0.

Data structures as functions

Another source of bugs was code like:

({:foo :bar} :foo)

In Squint, {:foo :bar} is just a JavaScript object and those cannot be called as functions as of now. Squint could be clever and just support literal collections in function position by emitting (get {:foo :bar} :foo) but this would break down when the user would push the data literal to a local or var (unless you add some kind of inference). I chose to just rewrite those expressions to use get or contains? instead, which works both in CLJS and squint:

(get {:foo :bar} :foo)

Miscellaneous

Several other things were missing in squint, like:

Support for :pre and :post in fn
Macro usages via an alias instead of :refer
Several core functions like bit-and, bit-or, re-seq, fn?, subs, max, min, every-pred , etc. All of those got added while doing the port.

Development

Aside from running tests I used vite which is very easy to set up. Just create an index.html page, load your .mjs file from there using:

and run:

$ npx vite --config vite.config.js public

where public is the directory that contains the index.html page.

The most basic vite config:

export default {
  base: './',
};

This spins up a development server and automatically hot-reloads all compiled JavaScript.

Publishing to NPM

Since the .mjs files are written to dist (as configured in squint.edn), publishing the project to NPM can be done by adding "files": "dist" to package.json To make the dist/nextjournal/clojure_mode.mjs file available when writing

import { default_extensions, complete_keymap } from '@nextjournal/clojure-mode';

I had to add

"exports": {".": "dist/nextjournal/clojure_mode.mjs"}

to package.json.

After that it was just a matter adding a package name and version and hitting npm publish (the first time you're doing this, you need to add --access public when you want to publish the package publically).

The package now lives on NPM!

Use directly from CDN

Having the package on NPM also lets you directly use it from an HTML page using a CDN. The jspm tool can convert a package.json into an importmap. I did this for the squint demo page. There you can see clojure-mode compiled with squint in action, without having to use any build tooling, since everything is loaded directly from a CDN!

Babashka-conf is happening June 10th in Berlin. Only a few tickets left!

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible! Open the details section for more info.

Sponsor info

OSS updates April 2023

2023-04-30T23:59:59+00:00

In this post I'll give updates about open source I worked on during April 2023.

To see previous OSS updates, go here.

Babashka-conf

Babashka-conf is happening June 10th in Berlin. Save the date and/or submit your babashka/clojure-related talk or workshop in the CfP!

Sponsors

I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work in the following ways. Thank you!

If you're used to sponsoring through some other means which isn't listed above, please get in touch.

On to the projects that I've been working on!

Projects

The following projects had updates in the last month. Note that only highlights are mentioned and not a full overview of all changes. See the project's changelogs for all changes.

clj-kondo: static analyzer and linter for Clojure code that sparks joy.
- #1196: show language context in .cljc files with :output {:langs true}. See docs.
- #2030: Add a new :discouraged-tag linter for discouraged tag literals. See the docs.
- #2058: warn about #() and #"" in `.edn files
babashka: native, fast starting Clojure interpreter for scripting
- Released 1.3.177 - 1.3.179
- #1541: respect bb.edn adjacent to invoked file. This eases writing system-global scripts from projects without using bbin. See docs.
- See the complete CHANGELOG.
cherry Experimental ClojureScript to ES6 module compiler
- Improve cherry.embed
SCI: Configurable Clojure/Script interpreter suitable for scripting and Clojure DSLs
- Better error message when trying to recur across try
- Improvement for error locations in multiple threads
edamame: Configurable EDN/Clojure parser with location metadata
- Improvements for reading namespaced maps
babashka.book: Babashka manual
- Several corrections
- Dynamic :exec-args
- Script-adjacent bb.edn docs
CLI: Turn Clojure functions into CLIs!
- Support --no-option and parse as {:option false}
- Support grouped aliase like -ome as {:o true, :m true, :e true}
http-client: Babashka's http-client
- Support java.net.URI directly in :uri option
- Better :ssl-config option support
- Better :proxy option support
pod-babashka-go-sqlite3: A babashka pod for interacting with sqlite3
- Better error message when connection is not a string
nbb: Scripting in Clojure on Node.js using SCI
- Fix :local/root deps in nbb.edn when not invoking from current working directory
- Fix regression, cljs.core/PersistentQueue.EMPTY no longer working
instaparse-bb
- Add transform function
jet: CLI to transform between JSON, EDN, YAML and Transit using Clojure
- Add option to elide commas
deps.clj: A faithful port of the clojure CLI bash script to Clojure
- Catch up with clojure CLI changes

Contributions to other projects

clojurescript:
- PR 202: a macroexpand fix
- PR 203: a symbol optimization fix
malli: cherry integration
clerk: cherry integration
clojure-lsp: integrated a new clj-kondo feature: showing the languages in a CLJC context

Other projects

These are (some of the) other projects I'm involved with but little to no activity happened in the past month.

process: Clojure library for shelling out / spawning sub-processes
quickdoc: Quick and minimal API doc generation for Clojure
rewrite-clj: Rewrite Clojure code and edn
sql pods: babashka pods for SQL databases
squint: CLJS syntax to JS compiler
pod-babashka-buddy: A pod around buddy core (Cryptographic Api for Clojure).
gh-release-artifact: Upload artifacts to Github releases idempotently
neil: A CLI to add common aliases and features to deps.edn-based projects
cljs-showcase: Showcase CLJS libs using SCI
carve - Remove unused Clojure vars
grasp: Grep Clojure code using clojure.spec regexes
scittle: Execute Clojure(Script) directly from browser script tags via SCI
quickblog: Light-weight static blog engine for Clojure and babashka
sci.configs: A collection of ready to be used SCI configs
lein2deps: leiningen to deps.edn converter
4ever-clojure - Pure CLJS version of 4clojure, meant to run forever!
fs - File system utility library for Clojure
pod-babashka-lanterna: Interact with clojure-lanterna from babashka
pod-babashka-fswatcher: babashka filewatcher pod
joyride: VSCode CLJS scripting and REPL (via SCI)
clj2el: transpile Clojure to elisp
deflet: make let-expressions REPL-friendly!
babashka.json: babashka JSON library/adapter

Babashka news of February and March 2023

2023-04-07T23:59:59+00:00

If you want to help me keep track of babashka-related news, please contribute to news.md or use the #babashka hashtag on Twitter or Mastodon.

2023-03

Releases

1.3.176, 1.3.175, 1.2.174:

Biggest highlight: Switch to GraalVM 19 and enable virtual threads!

Videos

Blambda! The sound of babashka and AWS colliding, by Josh Glover from Pitch!

Projects

babashka.json: JSON abstraction library
martian is now babashka compatible!
panas.reload: a hot reload for babashka serving html+css (or htmx)
cljs-exif-reader: Extract information from TIFF and JPEG images (works in babashka, despite the name)

Jobs

Write babashka at Cognician!

2023-02

Releases

1.1.173: mostly bugfixes

Articles

A technique for live coding simple web pages with babashka

Videos

Stockholm Clojure Meetup Feb 23: Blambda! The sound of Babashka and Lambda colliding

Projects

debux is now babaskha-compatible
lines-of-code-bb: Babashka script to count lines of Clojure code, docs, comments, and more
deps-try: a babashka-script to try out Clojure libraries in rebel-readline
bb-dialog adds support for --treeview
A duckduck go CLI with babashka and (bbl)gum
babashka http-client now supports multipart uploads
sublime-pretty-edn: Format, Validate, Minify EDN files in Sublime Text
Play console tetris in babashka!
kaocha test runner became babashka compatible!

OSS updates March 2023

2023-04-07T23:59:59+00:00

In this post I'll give updates about open source I worked on during March 2023.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work in the following ways. Thank you!

If you're used to sponsoring through some other means which isn't listed above, please get in touch.

On to the projects that I've been working on!

cherry

Experimental ClojureScript to ES6 module compiler

This month I've been preparing cherry as a compiler that you can embed in your existing CLJS / shadow-cljs applications. This makes cherry an additional alternative to SCI and self-hosted CLJS.

Read about embedding cherry into your application here.

I've been working on several PRs to include cherry as an additional evaluator in:

clerk
malli
One project that is still unpublished but will be coming soon!

scimacs

The Small Clojure Interpreter (SCI) integrated with emacs as a loadable module.

This is a new project by Jack Rusher and I've helped him with the SCI integration.

clj2el

Transpile clojure to elisp. A brand new project to transpile Clojure to Elisp. It might be of value for those who know Clojure better than Elisp and want to have something to get started. It's far from complete. Try it in the playground here.

deflet

Make let-expressions REPL-friendly!

The deflet macro lets your write inline-def expressions, while expanding those to regular let expressions, giving you the benefits of REPL-driven development without polluting production code with top level vars.

babashka

Native, fast starting Clojure interpreter for scripting

New release: 1.3.175 (2023-03-18)), 1.3.176 (2023-03-18)

Highlights:

The clojure.core.async/go macro now uses virtual threads.

Many small fixes and upgrades.

See the complete CHANGELOG.

babashka.json

This is a JSON abstraction library that you can include in babashka and JVM projects while also including your own favorite JSON implementation. The idea is that babashka libraries can include this, while JVM projects don't have to switch their JSON implementation to cheshire.core.

Babashka compatibility in external libs

I worked together with the maintainers of the following libraries to make them compatible with babashka:

martian: HTTP abstraction library for Clojure/script, supporting OpenAPI, Swagger, Schema, re-frame and more

clj-kondo

Static analyzer and linter for Clojure code that sparks joy

New release: 2023.03.17

Some highlights:

#2010: Support inline macro configuration. See docs
#2010: Short syntax to disable linters: {:ignore [:unresolved-symbol]} or {:ignore true}, valid in ns-metadata, :config-in-ns, :config-in-call
#2009: new :var-same-name-except-case linter: warn when vars have names that differ only in case (important for AOT compilation and case-insensitive filesystems)
#1269: warn on :jvm-opts in top level of deps.edn
#2003: detect invalid arity call for function passed to update, update-in, swap!, swap-vals!, send, send-off, and send-via

Check the changelog for details.

SCI

Configurable Clojure/Script interpreter suitable for scripting and Clojure DSLs

New release: 0.7.39 (2023-03-07)

#874: Keyword arguments as map support for CLJS

See changelog for more.

Contributions to other projects

clojurescript:
- PR 202: a macroexpand fix
- PR 203: a symbol optimization fix
clojure-lsp: fix reflection issue on JDK 19
http-kit: add native-image tests
promesa: fix GraalVM native-image compilation
etaoin: JDK 19 + babashka issue

Brief mentions

The following projects also got updates, mostly in the form of maintenance and performance improvements. This post would get too long if I had to go into detail about them, so I'll briefly mention them in random order:

CLI: Turn Clojure functions into CLIs!
quickdoc: Quick and minimal API doc generation for Clojure
rewrite-clj: Rewrite Clojure code and edn
sql pods: babashka pods for SQL databases
squint: CLJS syntax to JS compiler
pod-babashka-buddy: A pod around buddy core (Cryptographic Api for Clojure).
gh-release-artifact: Upload artifacts to Github releases idempotently
edamame: Configurable EDN/Clojure parser with location metadata
Nbb: Scripting in Clojure on Node.js using SCI
neil: A CLI to add common aliases and features to deps.edn-based projects
jet: CLI to transform between JSON, EDN, YAML and Transit using Clojure
http-client: Babashka's http-client

Other projects

These are (some of the) other projects I'm involved with but little to no activity happened in the past month.

cljs-showcase: Showcase CLJS libs using SCI
carve - Remove unused Clojure vars
deps.clj: A faithful port of the clojure CLI bash script to Clojure
grasp: Grep Clojure code using clojure.spec regexes
scittle: Execute Clojure(Script) directly from browser script tags via SCI
quickblog: Light-weight static blog engine for Clojure and babashka
sci.configs: A collection of ready to be used SCI configs
lein2deps: leiningen to deps.edn converter
4ever-clojure - Pure CLJS version of 4clojure, meant to run forever!
instaparse-bb
fs - File system utility library for Clojure
process: Clojure library for shelling out / spawning sub-processes
pod-babashka-lanterna: Interact with clojure-lanterna from babashka
joyride: VSCode CLJS scripting and REPL (via SCI)

Embedding cherry for runtime CLJS compilation

2023-03-30T23:59:59+00:00

Cherry is a new, experimental ClojureScript compiler. One of the main ideas behind cherry is to reduce friction between ClojureScript and JS tooling. It can be used as a standalone compiler directly as an NPM package without a JVM.

Since v0.0.1, cherry can be embedded into an existing vanilla CLJS or shadow-cljs project. To facilitate this, cherry exposes the cherry.embed namespace. It contains the following:

preserve-ns: a macro to define a CLJS namespace as globals, so cherry output can access functions after advanced compilation.
eval-form, eval-string, compile-form and compile-string functions to evaluate or compile an s-expr or string

An example shadow-cljs project:

deps.edn:

{:aliases {:cherry {:extra-deps {io.github.squint-cljs/cherry
                                 {:git/sha "4e948708cb20ab0a1a892c30fe87842a2efcc380"}}}
           :shadow {:extra-deps {thheller/shadow-cljs {:mvn/version "2.22.9"}}
                    :main-opts ["-m" "shadow.cljs.devtools.cli"]}}}

package.json:

{"type": "module"}

shadow-cljs.edn

{:deps true
 :builds
 {:cli
  {:target :esm
   :runtime :node
   :output-dir "out"
   :modules {:eval {:init-fn my.cherry/init}}
   :build-hooks [(shadow.cljs.build-report/hook
                  {:output-to "report.html"})]}}}

src/my/cherry.cljs:

(ns my.cherry
  (:require [cherry.embed :as cherry]))

(cherry/preserve-ns 'cljs.core)
(cherry/preserve-ns 'clojure.string)

(defn init []
  (let [[_ expr] (.slice js/process.argv 2)]
    (cherry/eval-string expr)))

Note that when you don't want to "preserve" an entire namespace, you can just (defn ^:export foo []) a function or value in your CLJS namespace.

When compiling this with clojure -M:cherry:shadow release cli, we get a single out/eval.js file of about 550kb of which roughly 330kb comes from preserving the cljs.core namespace.

We can invoke it with:

$ node out/eval.js -e '(do (prn :hello) (js/console.log (clojure.string/join , [1 2 3])))'
:hello
123

Note that you can enable eval in your CLJS/shadow app with:

(set! *eval* cherry/eval-form)

Full example:

(ns my-shadow.app
  (:require [cherry.embed :as cherry]))

(cherry/preserve-ns 'cljs.core)

(set! *eval* cherry/eval-form)

(def x (eval '(+ 1 2 3)))

Since cherry is a compiler, the code generally runs faster than with SCI which is an interpreter. For many cases SCI is fast enough, but numerical computations in a hot loop isn't one of its strenghts:

$ npx nbb@latest -e '(time (print (loop [i 0 j 10000000] (if (zero? j) i (recur (inc i) (dec j))))))'
10000000
"Elapsed time: 566.194958 msecs"

With cherry:

$ node out/eval.js -e '(time (print (loop [i 0 j 10000000] (if (zero? j) i (recur (inc i) (dec j))))))'
10000000
"Elapsed time: 8.812375 msecs"

The execution time is similar to self-hosted ClojureScript:

$ plk -e '(time (print (loop [i 0 j 10000000] (if (zero? j) i (recur (inc i) (dec j))))))'
10000000"Elapsed time: 9.894542 msecs"

Cherry is still experimental and looking for feedback. Please try it out and join the Clojurians Slack channel for discussion.

OSS updates February 2023

2023-03-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during February 2023.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work in the following ways. Thank you!

If you're used to sponsoring through some other means which isn't listed above, please get in touch.

Attention

If you are using Github Sponsors and are making payments via Paypal, please update to a creditcard since Github Sponsors won't support Paypal from February 23rd 2023. Read their statement here. If you are not able to pay via a creditcard, you can still sponsor me via one of the ways mentioned above.

On to the projects that I've been working on!

Babashka

Native, fast starting Clojure interpreter for scripting

New release: 1.2.174

Highlights:

Use GraalVM 22.3.1 on JDK 19.0.2. This adds virtual thread support. See demo.
Add more java.time and related classes with the goal of supporting juxt.tick (issue)

See the complete CHANGELOG.

Babashka compatibility in external libs

I worked together with the maintainers of the following libraries to make them compatible with babashka:

kaocha: test runner
multiformats: Clojure(Script) implementations of the self-describing multiformat specs

Http-client: Babashka's http-client

The babashka.http-client namespace mostly replaces babashka.curl.

This month support for :multipart uploads was added, mostly based on and inspired by hato's implementation.

Clj-kondo

Static analyzer and linter for Clojure code that sparks joy

New release: 2023.02.17

Some highlights:

#1976: warn about using multiple bindings after varargs (&) symbol in fn syntax
Add arity checks for core def
#1954: new :uninitialized-var linter. See docs.
#1996: expose hooks-api/resolve. See docs.

Check the changelog for details.

SCI

Configurable Clojure/Script interpreter suitable for scripting and Clojure DSLs

This month:

Adding JS libraries to a SCI context. See docs
Keyword arguments as map support for CLJS
Making loading of libraries thread-safe in JVM
Several fixes with respect to deftype and toString + equals

Fs

File system utility library for Clojure

Highlights:

several xdg-*-home helper functions, contributed by @eval
babashka.fs/zip now takes a :root option to elide a parent folder or folders. E.g. (fs/zip "src" {:root "src"}) will zip src/foo.clj into the zip file under foo.clj.

See changelog for more details.

Process

Clojure library for shelling out / spawning sub-processes

This month I looked into wrapping output of processes with a prefix so when ran in parallel, you can easily distuingish them. A preliminary solution is in this thread.

Pod-babashka-lanterna

Interact with clojure-lanterna from babashka

A very experimental 0.0.1 release was published.

You can try it out by playing tetris in the console with babashka:

bb -Sdeps '{:deps {io.github.borkdude/console-tetris {:git/sha "2d3bee34ea93c84608c7cc5994ae70480b2df54c"}}}' -m tetris.core

Nbb

Scripting in Clojure on Node.js using SCI

Finally nbb has gotten support for passing maps to keyword argument functions:

(defn foo [& {:keys [a b c]}])
(foo :a 1 :b 2 :c 3)
(foo {:a 1 :b 2 :c 3})

Several other improvements have been made in the area of macros and resolving JS library references and resolving dependencies in an nbb.edn file, relative to an invoked script which is not in the current directory.

See changelogs here.

Joyride

VSCode CLJS scripting and REPL (via SCI)

This month I contributed a built-in version of rewrite-clj to joyride, so joyriders can rewrite their code from within VSCode.

Cljs-showcase

Showcase CLJS libs using SCI

A little project to show how you can use SCI to showcare your CLJS library in an interactive way.

Brief mentions

CLI: Turn Clojure functions into CLIs!
quickdoc: Quick and minimal API doc generation for Clojure
process: Clojure library for shelling out / spawning sub-processes
rewrite-clj: Rewrite Clojure code and edn
sql pods: babashka pods for SQL databases
squint: CLJS syntax to JS compiler

Other projects

These are some of the other projects I'm involved with but little to no activity happened in the past month.

carve - Remove unused Clojure vars
deps.clj: A faithful port of the clojure CLI bash script to Clojure
edamame: Configurable EDN/Clojure parser with location metadata
cherry: Experimental ClojureScript to ES6 module compiler
grasp: Grep Clojure code using clojure.spec regexes
jet: CLI to transform between JSON, EDN, YAML and Transit using Clojure
scittle: Execute Clojure(Script) directly from browser script tags via SCI
neil: A CLI to add common aliases and features to deps.edn-based projects
quickblog: Light-weight static blog engine for Clojure and babashka
sci.configs: A collection of ready to be used SCI configs
lein2deps: leiningen to deps.edn converter
4ever-clojure - Pure CLJS version of 4clojure, meant to run forever!
instaparse-bb
pod-babashka-buddy: A pod around buddy core (Cryptographic Api for Clojure).

Babashka news of January 2023

2023-02-05T23:59:59+00:00

If you want to help me keep track of babashka-related news, please contribute to news.md or use the #babashka hashtag on Twitter or Mastodon.

Releases

New releases in the past month: 1.0.170 - 1.1.173 Release highlights:

Support for data_readers.clj(c)
Include http-client as built-in library
Compatibility with clojure.tools.namespace.repl/refresh
Compatibility with clojure.java.classpath (and other libraries which rely on java.class.path and RT/baseLoader)
Compatibility with eftest test runner (see demo)
Compatibility with cljfmt
Support for *loaded-libs* and (loaded-libs)
Support add-watch on vars (which adds compatibility with potemkin.namespaces)
BREAKING: make printing of script results explicit with --prn

Events

Babashka Workshop at ClojureStream with Rahul De
Blambda! The sound of Babashka and Lambda colliding: sthlm.clj (Stockholm, Sweden)

Articles

One new book this month:

Babooka: write command line Clojure by Daniel Higginbotham

and several blog posts:

Blambda analyses sites by Josh Glover
Babashka: How GraalVM Helped Create a Fast-Starting Scripting Environment for Clojure in Japanese
The wizard of HOP - How we built the web based HOP CLI Settings Editor using Babashka and Scittle by Bingen Galartza
Simple TUIs with Babashka and Gum by Rattlin.blog
Babashka And Dialog Part Ii: Announcing The Bb-Dialog Library by A.C. Danvers
Re-Writing a GlobalProtect OpenConnect VPN Connect script in Babashka by Tory Anderson

Projects

Projects that were new, had updates or were made compatible with babashka:

asdf-babashka: babashka plugin for the asdf version manager
babashka-htmx-todoapp: Quick example of a todo list SPA using Babashka and HTMX
bblgum: An extremely tiny and simple wrapper around charmbracelet/gum
bb-dialog: A simple wrapper library for working with dialog from Babashka
carve: Remove unused Clojure vars
chr: native commands history report for the default terminal users
clj-kondo-bb: Invoke clj-kondo from babashka scripts!
cljfmt: A tool for formatting Clojure code
drepl: Node JS dependency-repl. The node repl you already know with easy library installations
instaparse-bb: Wrapper library aroud pod-babashka-instaparse
lein2deps: Lein project.clj to deps.edn converter
neil: A CLI to add common aliases and features to deps.edn-based projects
obsidian-babashka: Run Obsidian Clojure(Script) codeblocks in Babashka
pod-babashka-buddy: A pod around buddy core (Cryptographic Api for Clojure)
quickblog: Light-weight static blog engine for Clojure and babashka
solenoid: A small clojure tool for making little control UIs while using the REPL!
tools.bbuild: babashka version of tools.build
weather: command line util for grabbing current weather for a city using OpenWeather API

OSS updates of January 2023

2023-02-05T23:59:59+00:00

In this post I'll give updates about open source I worked on during January 2023.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work in the following ways. Thank you!

If you're used to sponsoring through some other means which isn't listed above, please get in touch.

Attention

If you are using Github Sponsors and are making payments via Paypal, please update to a creditcard since Github Sponsors won't support Paypal from February 23rd 2023. Read their statement here. If you are not able to pay via a creditcard, you can still sponsor me via one of the ways mentioned above.

Projects

Babashka

Native, fast starting Clojure interpreter for scripting.

New releases in the past month: 1.0.170 - 1.1.173 Highlights:

Support for data_readers.clj(c)
Include http-client as built-in library
Compatibility with clojure.tools.namespace.repl/refresh
Compatibility with clojure.java.classpath (and other libraries which rely on java.class.path and RT/baseLoader)
Compatibility with eftest test runner (see demo)
Compatibility with cljfmt
Support for *loaded-libs* and (loaded-libs)
Support add-watch on vars (which adds compatibility with potemkin.namespaces)
BREAKING: make printing of script results explicit with --prn

Babashka compatibility in external libs

I contributed changes to the following libraries to make them compatible with babashka:

cljfmt - A tool for formatting Clojure code
carve - Remove unused Clojure vars
debux - A trace-based debugging library for Clojure and ClojureScript

Check the changelog for all the changes!

Http-client

The new babashka http-client project mostly replaces babashka.curl.

This month the default client was improved to accept gzip and deflate as encodings by default, reflecting what babashka.curl did.

Also babashka.http-client is now available as a built-in namespace in babashka v1.1.171 and higher.

Clj-kondo

Static analyzer and linter for Clojure code that sparks joy

Three new releases with many fixes and improvements in the last month. Check the changelog for details.

Some highlights:

#1742: new linter :aliased-namespace-var-usage: warn on var usage from namespaces that were used with :as-alias. See demo.
#1926: Add keyword analysis for EDN files. This means you can find references for keywords throughout your project with clojure-lsp, now including in EDN files.
#1902: provide :symbols analysis for navigation to symbols in quoted forms or EDN files. See demo.

The symbol analysis is used from clojure-lsp for which I provided a patch here.

A new project around clj-kondo is clj-kondo-bb which enables you to use clj-kondo from babashka scripts.

Also lein-clj-kondo got an update.

Instaparse-bb

This is a new project and gives you access to a subset of instaparse via a pod.

Instaparse was request a few times to have as a library in babashka and instaparse-bb is a good first step, without making a decision on that yet. See the relevant discussion here.

Carve

Remove unused Clojure vars

In the 0.3.5 version, Carve got the following updates:

Upgrade clj-kondo version
Make babashka compatible by using the clj-kondo-bb library
Discontinue the carve binary in favor of invocation with babashka. Instead you can now install carve with bbin:
```
bbin install io.github.borkdude/carve
```
Implement babashka.cli integration
Implement --help

Jet

CLI to transform between JSON, EDN, YAML and Transit using Clojure

Version 0.4.23:

#123: Add base64/encode and base64/decode
Add jet/paths and jet/when-pred
Deprecate interactive mode
Deprecate --query in favor of --thread-last, --thread-first or --func

Fs

File system utility library for Clojure.

Fs has gotten a few new functions:

unifixy, to turn a Windows path into a path with Unix-style path separators. Note that that style is supported by the JVM and this offers a more reliable way to e.g. match filenames via regexes.
several xdg-*-home helper functions, contributed by @eval

See changelog for more details.

Neil

A CLI to add common aliases and features to deps.edn-based projects.

This month there were several small fixes, one of them being to always pick stable versions when adding or upgrading libraries. See full changelog for details.

Quickblog

Light-weight static blog engine for Clojure and babashka.

The blog you're currently reading is made with quickblog.

Version 0.2.3 was released with contributions from several people, mostly enabling you to tweak your own blog even more, while having good defaults.

Instances of quickblog can be seen here:

If you are also using quickblog, please let me know!

A collection of ready to be used SCI configs for e.g. Reagent, Promesa, Re-frame and other projects that are used in nbb, joyride, scittle, etc. See recent commits for what's been improved.

Edamame

Edamame got a new function: parse-next+string which returns the original string along with the parsed s-expression.

lein2deps

Lein to deps.edn converter

This tool can convert a project.edn file to a deps.edn file. It even supports Java compilation and evaluation of code within project.clj. There is now a lein plugin which enables you to sync your project.clj with your deps.edn every time you start lein. Several other minor enhancements were made. See changelog.

4ever-clojure

I added the ability to build and deploy 4ever-clojure to Github Actions. Every time a commit is merged, the site is automatically updated.

Brief mentions

jna-native-image-sci: Compile a program that uses JNA to native-image and allow dynamic evaluation using SCI!
deps.clj: A faithful port of the clojure CLI bash script to Clojure
joyride: VSCode CLJS scripting and REPL (via SCI)
squint: CLJS syntax to JS compiler
tools-deps-native: Run tools.deps as a native binary
tools.bbuild: Library of functions for building Clojure projects
scittle: Execute Clojure(Script) directly from browser script tags via SCI
pod-babashka-buddy: A pod around buddy core (Cryptographic Api for Clojure).
nbb: Scripting in Clojure on Node.js using SCI
CLI: Turn Clojure functions into CLIs!
process: Clojure library for shelling out / spawning sub-processes
SCI: Configurable Clojure/Script interpreter suitable for scripting and Clojure DSLs
scittle: Execute Clojure(Script) directly from browser script tags via SCI
sci.configs: A collection of ready to be used SCI configs

Babashka news in 2022

2023-01-06T23:59:59+00:00

This is an overview of all the news collected about babashka in 2022! It is a collection of links to scripts, libraries, blog posts, talks and tweets about babashka. If you want to help me keep track of babashka-related news, please contribute to news.md.

2022-12

Releases: 1.0.168.
How GraalVM Helped Create a Fast-Starting Scripting Environment for Clojure
http-client: a new HTTP client library for babashka
How to Do Things With Babashka by Paulus Esterhazy (2022-12)
Using Babashka to Get Electricity Prices by Kari Marttila
Adding prompts to your babashka scripts with dialog by A.C. Danvers
Scraping an HTML dictionary with Babashka and Bootleg by exupero
quickblog v0.1.0: Light-weight static blog engine for Clojure and babashka
bb-excel: Read Excel Files in babashka scripts
Get paginated list of issues from gitlab with clojure/babashka by Steffen Glückselig
Install development builds: bash <(curl https://raw.githubusercontent.com/babashka/babashka/master/install) --dev-build --dir /tmp
JVM interop improvements in bb
A little trick to have conditional code for babashka in a .clj file without resorting to .cljc reader conditionals
Get Advent of Code input in babashka by Jan Seeger
Grabbing current weather for a city using OpenWeather API by Dmitri Sotnikov

2022-11

Releases: 1.0.165 - 1.0.167.
Registration for a Babashka workshop with Rahul De at ClojureStream is now open!
Tutkain, a Sublime plugin for clojure based on socket REPL now with support for babashka
Manage git hooks in babashka by Mykhaylo Bilyanskyy
[Messing around with babashka](Messing around with Babashka) by Ian Muge
A babashka one liner to inspect data in portal
Using nREPL as a system interface by Dmitri Sotnikov
deep-diff2 is now babashka-compatible!
A script to normalize auto-resolved keywords
Sum up page counts of books from Calibre library with babashka by Jan Seeger
Tiny babashka script that returns a random clojure doc by Carnun Marcus-Page

2022-10

Releases: 1.0.164.
bb-pod-racer: Speed up development of Babashka pods by Nate Jones
Babashka tasks VSCode plugin by Ferdinand Beyer
A PR to get Clerk working in babashka
lein2deps: lein to deps.edn converter
awyeah-api by Michael Glaesemann v0.8.41 is now available! aws-api for Babashka. Aw yeah!
bbssh by Crispin Wellington, v0.2.0 released
safely use rsync --archive --delete to backup a directory by Stel Abrego

2022-09

Releases: 0.9.162 - 0.10.163.
Introducing bbin: a tool to install babashka scripts on your system by Radford Smith
bbssh: Babashka pod for SSH support by Epic Castle
Loom virtual threads are coming to babashka
Tiny script to cycle through pulseaudio outputs (aka sinks) by Stel Abrego
Tetris in the console via pod-babashka-lantera
org-mode gets support for babashka
docs for combining babashka process with promesa exoscale/interceptor became babashka-compatible!
Tutkain, socket REPL Sublime plugin, gets better support for babashka
babashka tweepy: kicking the tires on using the tweepy library from a babashka task by Dav Clark
aoc helper by Josh Comer
Dogfooding blambda part 5 by Josh Glover

2022-08

It's babashka's third birthday on August 9th 2022!
etaoin, Pure Clojure Webdriver protocol implementation, is now babashka-compatible!
xforms is now babashka-compatible!
squint and cherry are CLJS-compilers that work with babashka!

2022-07

Releases: 0.8.157 - 0.9.161.
Recursive document transformations with Pandoc and Clojure by Teodor Heggelund
Babashka toolbox: A categorised directory of libraries and tools for Babashka
Quickblog: Light-weight static blog engine for Clojure and babashka
Win a babashka t-shirt by participating in this contest!
AWS Lambda, now with first class parentheses by Ray McDermott (about nbb)
bb-github-app: An example Babashka Script authenticating as a Github App and interacting with the Checks API
Ruuter is a routing library which works very well with bb
Blambda! by Josh Glover
Files with the .bb extension are now correctly highlighted as Clojure code on Github! See this tweet.
Encode and decode files as kroki url diagrams, a gist by Henry Widd
Customized bb builds with clj-nix: tweet
Expose Clojure functions in the CLI with babashka and nix: tweet
Meander is now compatible with bb: tweet
Deleting AWS Glacier vaults with babashka by Tim Zöller

2022-06

Releases: 0.8.156.
AWS wiki page
blambda: Blambda! is a custom runtime for AWS Lambda that lets you write functions using Babashka
Babashka CLI: turn Clojure functions into CLIs!
Http-server: Serve static assets
Deps-bundler: Bundle dependencies on a computer that has access to maven and clojars (PC-A) and bring these over to a computer with limited access (PC-L).
Prismatic/schema and babashka are now compatible
Logseq bb tasks: Reusable babashka tasks used by logseq team
[Breakneck Babashka on K8s](Breakneck Babashka on K8s) by Heow Goodman

2022-05

Releases: 0.8.2.
Etaoin moved to clj-commons and now works with babashka as well.
Nix docs for babashka
Fly.io docs for babashka
Babashka survey results
Quickdoc: (Quick and minimal API doc generation for Clojure
Awyeah-api - Cognitect's aws-api for babashka

2022-04

Releases: 0.8.0 - 0.8.1.
Babashka and Clojure by Rahul Dé at North Virginia Linux Users Group
Setup-Clojure Github action is now able to install babashka!
Control Chrome via devtools using clj-chrome-devtools which runs with bb!
Use pods directly in bb.edn: tweet

2022-03

Releases: 0.7.7 - 0.7.8.
Create a password manager with Clojure using Babashka, sqlite, honeysql and stash by Daniel Amber
Detecting inconsistent aliases in a clojure codebase by Oxalorg
Clj-konmari by Oxalorg
Logseq-query by Gabriel Horner (announcement tweet with video)
The loom library is now compatible (tweet)
The at-at library is now compatible

2022-02

Releases: 0.7.5 - 0.7.6.
Spire is available as a babashka pod
Babashka Clojure template on Repl.it by Eccentric J
Create a self-contained executable with caxa
Cli-matic is now compatible due to this PR
I, too, Wrote Myself a Static Site Generator by Daw-Ran Liou
Staplegun: Single file clipboard-manager
Bbb: make executable CLI tools from bb scripts
Apptemplate: Application project template for Clojure featuring bb tasks

2022-01

Releases: 0.7.4.
Babashka dev builds
Writing Clojure-living-cookbooks by Cyprien Pannier
HTMX Todo App
Better linting for bb.edn
Unwordle: solver for wordle puzzles
Using babashka with PHP by Michiel Borkent

OSS updates of November - December 2022

2023-01-06T23:59:59+00:00

In this post I'll give updates about open source I worked on during November and December 2022.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work via the following organizations. Thank you!

Github Sponsors
OpenCollective (also see the clj-kondo one)
Clojurists Together

Projects

http-client

The new babashka http-client aims to become default HTTP client solution in babashka.

Babashka has several built-in options for making HTTP requests, including:

In addition, it allows to use several libraries to be used as a dependency:

The built-in clients come with their own trade-offs. E.g. babashka.curl shells out to curl which on Windows requires your local curl to be updated. Http-kit buffers the entire response in memory. Using java.net.http directly can be a bit verbose.

Babashka's http-client aims to be a good default for most scripting use cases and is built on top of java.net.http and can be used as a dependency-free JVM library as well. The API is mostly compatible with babashka.curl so it can be used as a drop-in replacement. The other built-in solutions will not be removed any time soon.

Babashka

Native, fast starting Clojure interpreter for scripting.

I had the honor to write a guest blog post for the GraalVM blog about babashka. You can read it here.

Daniel Higginbotham from Brave Clojure wrote Babashka Babooka which I helped reviewing.

I also wrote a blog on how to test babashka scripts.

Versions 1.0.165 - 1.0.169 were released. Visit the changelog for details. Highlights:

Compatibility with Cognitest test-runner and tools.namespace
#1433: spec source as built-in fallback. When not including the clojure.spec.alpha fork as a library, babashka loads a bundled version, when clojure.spec.alpha is required.
Many performance improvements (via SCI)
Several non-special forms are now regular macros rather than treated special (via SCI)
Update to babashka process to v0.4.13: support (process opts? & args) syntax everywhere

Squint and Cherry

Squint and cherry are two flavors of the same CLJS compiler.

Squint is a CLJS syntax to JS compiler for use case where you want to write JS, but do it using CLJS syntax and tooling instead. Cherry comes with the CLJS standard library and is as such much closer to the normal ClojureScript, but the minimal amount of JS is a little bigger.

The video of the talk I did on ClojureDays 2022 came online!

In the past two months, I've been restructuring code between squint and cherry: a bit boring but necessary to keep going forward. Along with some minor bugfixes and features, one new JSX feature landed: you can pass a props map using a new notation inspired by helix.

You can read details in the changelog.

SCI

Configurable Clojure interpreter suitable for scripting and Clojure DSLs.

This is the workhorse that powers babashka, nbb, Joyride, and many other projects.

Many improvements have happened over the last two months, both in Clojure compatibility and performance. JS and JVM interop has become up to 5x faster. All of these changes benefit babashka, nbb, joyride, etc.

See changelog for more details.

Clj-kondo

Static analyzer and linter for Clojure code that sparks joy

Two new releases with many fixes and improvements. Check the changelog for details.

Some highlights:

#609: typecheck var usage, e.g. (def x :foo) (inc x) will now give a warning
#1846: new linters: :earmuffed-var-not-dymamic and :dynamic-var-not-earmuffed. See docs.
#1875: add :duplicate-field-name linter for deftype and defrecord definitions.

Scittle

Execute Clojure(Script) directly from browser script tags via SCI. See it in action.

Version 0.4.11 introduced the re-frame plugin. You can play around with it in the playground here. Several other releases were made. Details in the changelog.

Process

Clojure library for shelling out / spawning subprocesses

This library traditionally had the syntax: (process [ & cmd-args ] ?opts) but in practice, it turned out that having the syntax (process ?opts & cmd-args) is more convenient, since you can use it with apply and *command-line-args*. All functions in babashka.process have been rewritten to support this syntax.

See changelog for details.

Quickdoc

Fs

File system utility library for Clojure.

Fs has gotten one new function: update-file, that alters the contents of a (text) file using a function. The function is reminiscent of swap!.

See changelog for more details.

Neil

A CLI to add common aliases and features to deps.edn-based projects.

A NEIL_GITHUB_TOKEN can now be configured to avoid hitting the rate limit of the Github API, thanks to Russ Matney.

Quickblog

Light-weight static blog engine for Clojure and babashka.

The blog you're currently reading is made with quickblog.

Version 0.1.0 was finally released with much thanks to Josh Glover. See changelog for more details.

Rewrite-edn

Utility lib on top of rewrite-clj with common operations to update EDN while preserving whitespace and comments.

Minor fixes and enhancements. Several functions have been added like fnil and conj. See changelog.

Sci.configs

A collection of ready to be used SCI configs for e.g. Reagent, Promesa, Re-frame and other projects that are used in nbb, joyride, scittle, etc. See recent commits for what's been improved.

Nbb

Scripting in Clojure on Node.js using SCI

Because it's so easy to deploy to npm, I usually publish a new version for each issue that is resolved.

No big changes, but many small bugfixes and improvements in the last two months. See changelog.

Edamame

Configurable EDN/Clojure parser with location metadata. It has been stable for a while and reached version 1.0.0. The API is exposed now in babashka and nbb as well.

Changelog

lein2deps

Lein to deps.edn converter

This tool can convert a project.edn file to a deps.edn file. It even supports Java compilation and evaluation of code within project.clj. Several minor enhancements were made. See changelog.

Joyride

Modify VSCode by executing ClojureScript (SCI) code in your REPL and/or run scripts via keyboard shortcuts.

I'm working on this project together with Peter Strömberg (known for his work on Calva) and I'm mostly reviewing Peter's PR instead of writing code.

Read the changelog here.

Deps.clj

Regular maintainance, keeping up with the official Clojure CLI and tools jar!

Clj-kondo configs

Library configurations as dependencies for clj-kondo.

The claypoole configuration was improved.

Babashka CLI

Turn Clojure functions into CLIs!

Minor fixes. See changelog.

Babashka pods

The pods library contains the code that supports using pods in babashka and the JVM. A critical error was fixed that would hang babashka and a new JVM release was pushed to Clojars (v0.1.0).

Babashka compatibility in external libs

I contributed to RCF, deep-diff2 and clj-diff to make these libraries babashka compatible.

Babashka: How GraalVM Helped Create a Fast-Starting Scripting Environment for Clojure

2022-12-08T23:59:59+00:00

I'm happy to announce a blog post written by me about babashka that was published on the GraalVM medium blog. You can read the full article here.

Testing babashka scripts

2022-11-24T23:59:59+00:00

For testing babashka scripts, you can write your own test runner from scratch, which is easy enough:

(ns my-test.runner
  (:require
   [clojure.test :as t]))

(def test-namespaces '[my-test])

(defn -main [& _]
  (doseq [test-ns test-namespaces] (require test-ns))
  (let [{:keys [fail error]}
        (apply t/run-tests test-namespaces)]
    (when (and fail error (pos? (+ fail error)))
      (System/exit 1))))

and then run it with bb -m my-test.runner.

Not too bad, but still, it's work and boilerplate and even more so when you want to make a runner with CLI argument parsing to support running a subset of your tests. Since a year or so, you can use the cognitect-labs/test-runner with babashka. But this required a fork of tools namespace to be on your babashka classpath (using :deps in your bb.edn file).

No more! Since babashka version 1.0.166 you can use org.clojure/tools-namespace unmodified. The fix for this was to add the clojure.tools.reader namespace with the read function in babashka as a built-in. Babashka doesn't support the whole clojure.tools.reader namespace yet, but this is a good start to make it compatible with tools.namespace and now also the cognitect test runner.

To use it with babashka, add the following to your bb.edn.

{:tasks
 {test:bb {:extra-paths ["test"]
           :extra-deps {io.github.cognitect-labs/test-runner
                        {:git/tag "v0.5.1" :git/sha "dfb30dd"}}
           :task (exec 'cognitect.test-runner.api/test)
           :exec-args {:dirs ["test"]}
           :org.babashka/cli {:coerce {:nses [:symbol]
                                       :vars [:symbol]}}}}}

The exec function call, :exec-args and :org.babashka/cli coercion is there so we can call a Clojure function from the command line. See Babashka tasks meets babashka CLI for more details.

Now create a test file in test/my_test.clj:

(ns my-test
  (:require [clojure.test :refer [deftest is testing]]))

(deftest my-first-test
  (testing "equality works"
    (is (= 1 1))))

(deftest my-second-test
  (testing "equality still works"
    (is (= 2 2))))

And run the tests:

$ bb test:bb

Running tests in #{"test"}

Testing my-test

Ran 2 tests containing 2 assertions.
0 failures, 0 errors.

To run a single test you can specify the name of a var:

$ bb test:bb --vars my-test/my-second-test

Running tests in #{"test"}

Testing my-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

$ bb test:bb --vars my-test/my-first-test my-test/my-second-test

Running tests in #{"test"}

Testing my-test

Ran 2 tests containing 2 assertions.
0 failures, 0 errors.

Perhaps this will come in handy for Advent of Code 2022!

OSS updates of September - October 2022

2022-10-31T23:59:59+00:00

In this post I'll give updates about open source I worked on during September and October 2022.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors:

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work via the following organizations. Thank you!

Github Sponsors
OpenCollective (also see the clj-kondo one)
Clojurists Together

Projects

Babashka

Native, fast starting Clojure interpreter for scripting.

The first 1.0 release was released!
Optimizations for let (in SCI) which is now up to 8x faster.
Many small improvements. See the changelogs.

Squint and Cherry

Squint and cherry are two flavors of the same CLJS compiler.

Squint is a CLJS syntax to JS compiler for use case where you want to write JS, but do it using CLJS syntax and tooling instead. Squint comes with a standard library that resembles CLJS but is built on bare JS ingredients. As such, squint comes with the usual JS caveats, but we can still have our parens and enjoy a slim bundle size.

Cherry comes with the CLJS standard library and is as such much closer to the normal ClojureScript, but the minimal amount of JS is a little bigger.

I've working on unifying the compiler code of cherry and squint into one code base, which is still in progress. I've also worked on REPL code.

I've also given a presentation on squint and cherry at the Dutch Clojure Days. The video will appear online in the future!

Clj-kondo

Static analyzer and linter for Clojure code that sparks joy

Two new releases with many fixes and improvements. Check the changelogs for details.

Among several new linters, there is a new :unused-value linter which detects unused values, which is particularly helpful for detecting unused transient operation results which can lead to bugs.

Clj-kondo configs

Library configurations as dependencies for clj-kondo.

The idea of this repository is that you can add configuration for libraries as a dependency to your deps.edn or project.clj. If you invoke the right command or if you are using Clojure LSP, then the configuration is written into your .clj-kondo directory and clj-kondo will understand custom constructs in your library. Normally you can provide these configurations as part of your library, but this is not always an option, so the remaining configurations can live over here.

SCI

Configurable Clojure interpreter suitable for scripting and Clojure DSLs.

This is the workhorse that powers babashka, nbb, Joyride, and many other projects.

Several bugfixes and enhancements were made in the last two months in two new releases. Performance of let bindings are now up to 8x faster, as already mentioned in the babashka entry of this post.

See changelogs for more details.

Nbb

Scripting in Clojure on Node.js using SCI

The first 1.0 version was released.

Many small bugfixes and improvements in the last two months. See changelogs.

Clj-yaml

In the past two month, I became one of the maintainers, together with @lread, of clj-yaml. Clj-yaml is a built-in library of babashka.

Deps.clj

A faithful port of the clojure CLI bash script to Clojure

A lot of Windows improvements in the last two months. Deps.clj is now also available as part of an MSI installer that installs deps.exe as clj.exe. This installer might form the basis for an official Clojure MSI installer.

Gh-release-artifact

Upload artifacts to Github releases idempotently

This tool has been in use within babashka, clj-kondo and other projects to automate uploading release artifacts from various CI systems to Github releases, idempotently. It is now open source and ready to be used by others.

Jet

CLI to transform between JSON, EDN, YAML and Transit, powered with a minimal query language.

The latest release adds support for YAML (by using clj-yaml), thanks to @qdzo.

Babashka CLI

Turn Clojure functions into CLIs!

See changelogs.

Process

Clojure library for shelling out / spawning subprocesses

Minor updates and fixes. See changelogs.

Quickdoc

Quickdoc is a tool to generate documentation from namespace/var analysis done by clj-kondo. It's fast and spits out an API.md file in the root of your project, so you can immediately view it on Github. It has undergone significant improvements in the last two months. I'm using quickdoc myself in several projects. In the last two months, there have been improvements in the table of contents linking and linking to source code.

Fs

File system utility library for Clojure.

Minor updates and fixes. See changelogs.

Carve

Carve out the essentials of your Clojure app by removing unused vars

Version 0.2.0 was released, after a long hiatus, with an updated version of clj-kondo and some minor fixes.

Grasp

Grep Clojure code using clojure.spec regexes.

I use this tool to analyze code patterns to make informed choices for e.g. SCI and clj-kondo. E.g. see this example that shows how many let bindings are typically used. See the example in action here.

A new version was released with minor fixes.

Rewrite-edn

Utility lib on top of rewrite-clj with common operations to update EDN while preserving whitespace and comments.

Minor fixes and enhancements. Repeated usage of assoc is now a safe operation. Thanks to @lread for the improvements.

lein2deps

Lein to deps.edn converter

This new little tool can convert a project.edn file to a deps.edn file. It even supports Java compilation and evaluation of code within project.clj.

Neil

A CLI to add common aliases and features to deps.edn-based projects.

Neil now comes with a dep upgrade command, thanks to @teodorlu and @russmatney, together with other improvements.

Respeced

Finally, after 4 years, a new release of respeced, a testing library for clojure.spec fdefs.

Quickblog

Light-weight static blog engine for Clojure and babashka

Small improvements. See changelog. The blog you're currently reading is made with quickblog.

Sci.configs

A collection of ready to be used SCI configs

Added a doseq macro in promesa which also is available via this configuration. Sci.configs is used in Clerk, nbb, Joyride and other SCI-based CLJS projects.

Deploying a Clojure project with neil and tools.build

2022-10-22T23:59:59+00:00

In a previous blog post, I described how you can kick off a Clojure project with neil.

Today I want to show you how easy it is how to deploy a Clojure project to Clojars with neil.

Assuming you already have a deps.edn, but you don't yet have a build.clj, you can run:

$ neil add build

This creates a tools.build build.clj file with functions you typically need for building and deploying a Clojure project.

The build.clj looks for the project name and version in your deps.edn under [:aliases :neil :project].

You can set the project name and version like this:

{:deps {}
 :paths ["resources"]
 :aliases
 {:neil {:project {:name io.github.clj-kondo/config-rum-rum
                   :version "1.0.0"}}
  :build ;; added by neil
  {:deps {io.github.clojure/tools.build {:git/tag "v0.8.3" :git/sha "0d20256"}
          slipset/deps-deploy {:mvn/version "0.2.0"}}
   :ns-default build}}}

Now all you have to do to deploy your project is run clojure -T:build deploy. This runs the deploy function in build.clj which uses deps-deploy.

Whenever you want to bump your patch version, you can run:

$ neil version patch

or set the version manually using:

$ neil version set 1.0.1

and then deploy again.

The neil version command is similar to NPM's version command.

For a full project that uses this setup, check out this one that I just created today in a couple of keystrokes.

Happy deploying!

OSS updates of July - August 2022

2022-09-01T23:59:59+00:00

In this post I'll give updates about open source I worked on during July and August 2022.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors: Clojurists Together, Roam Research, Nextjournal, Adgoji, Cognitect, Kepler16, .

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work via the following organizations:

Github Sponsors
OpenCollective (also see the clj-kondo one)
Clojurists Together

Projects

ClavaScript

This is a new project: a CLJS syntax to JS compiler for the niche use case where you want to write JS, but do it using CLJS syntax and tooling instead. ClavaScript comes with a standard library that resembles CLJS but is built on bare JS ingredients. As such, Clava comes with the usual JS caveats, but we can still have our parens and enjoy a slim bundle size!

Cherry

Cherry is similar to ClavaScript, but it does emit CLJS-compatible code (with the persistent data structures, etc). The compiler code is almost identical to Clava's, but with a few tweaks here and there. E.g. {:a 1} in Clava means: a JS object with a "a" key and 1 value, but in cherry, {:a 1} means the same as in CLJS. The goal of both Clava and Cherry are to reduce friction between CLJS and JS tooling. Both projects should be considered experimental for now. Challenges in both Clava and Cherry is the REPL, since both projects compile to ES6 modules and ES6 module imports are immutable.

On ClojureDays 2022 I will give a talk titled "ClojureScript reimagined" which will shed more light on both projects.

Scittle

Execute Clojure(Script) directly from browser script tags via SCI. See it in action.

Scittle received two new plugins: one for promesa.core and one for cljs.pprint. Also error messages were improved.

Babashka toolbox

Babashka toolbox is a port of Clojure toolbox and gives an overview of bb-compatible libraries and projects.

Babashka CLI

Turn Clojure functions into CLIs!

Several new options have been added: :validate, :require, :restrict. Also error handling was made more flexible.

Babashka CLI proper is now part of babashka. Also see my blog posts about it:

Babashka

Native, fast starting Clojure interpreter for scripting.

Compatibility with malli
-x: a way to execute functions from the command line using babashka CLI
Many bugfixes and enhancements

Nbb

Scripting in Clojure on Node.js using SCI

A new bundle command to bundle nbb scripts to standalone scripts, which can then be processed further with e.g. esbuild to minify and tree-shake them.
nbb.edn: you can now declare dependencies within this file, e.g. from Clojars and nbb will add them automatically to the classpath, so you can require them.
Malli compatibilty
Many small bugfixes and improvements

Clj-kondo

Static analyzer and linter for Clojure code that sparks joy

Bebo

Run Clojure scripts on Deno via SCI. I'm not exactly sure how useful this is to the wider Clojure community, but I got curious about deno and decided to give this a go.

Quickblog

Light-weight static blog engine for Clojure and babashka

A lot has been happening in this project, with the help of Josh Glover. Check out the changelog. The blog you're currently reading is made with quickblog.

SCI

Configurable Clojure interpreter suitable for scripting and Clojure DSLs.

This is the workhorse that powers babashka, nbb, bebo, and many other projects.

Several bugfixes and enhancements were made in the last two months.

Neil

A CLI to add common aliases and features to deps.edn-based projects.

Neil now has a new subcommand which defers to deps-new. Also neil test was added to run tests using the Cognitect-labs test runner. Much thanks to rads who contributed a lot.

Process

Clojure library for shelling out / spawning subprocesses

Minor updates and fixes.

Fs

File system utility library for Clojure.

Minor updates and fixes.

Pod-babashka-buddy

A babashka pod around buddy core (Cryptographic Api for Clojure).

The latest release adds wrappers for buddy.sign.jwt and provides an aarch64 binary.

See changelogs.

Dynaload

The dynaload logic from clojure.spec.alpha as a library

This library was made compatible with nbb.

Deps.clj

Upgrades and minor fixes.

Sci.configs

A collection of ready to be used SCI configs

Moved cljs.pprint config from nbb into this project.

Babashka tasks meets babashka CLI

2022-08-02T23:59:59+00:00

In a previous blog post (link) I introduced babashka CLI. It offers you similar benefits as clojure -X but with a more Unixy command line interface.

In version 0.9.160 of babashka, babashka CLI was integrated. It is available as a built-in library so you don't need to declare it anymore in :deps in bb.edn unless you want to use a newer version than the built-in one.

-x

For invoking functions from the command line, you can use the new -x flag (a pun to Clojure's -X of course!):

bb -x clojure.core/identity --hello there
{:hello "there"}

What we see in the above snippet is that a map {:hello "there"} is constructed by babashka CLI and then fed to the identity function. After that the result is printed to the console.

What if we want to influence how things are parsed by babashka CLI and provide some defaults? This can be done using metadata. Let's create a bb.edn and make a file available on the classpath:

bb.edn:

{:paths ["."]}

tasks.clj:

(ns tasks
  {:org.babashka/cli {:exec-args {:ns-data 1}}})

(defn my-function
  {:org.babashka/cli {:exec-args {:fn-data 1}
                      :coerce {:num [:int]}
                      :alias {:n :num}}}
  [m]
  m)

Now let's invoke:

$ bb -x tasks/my-function -n 1 2
{:ns-data 1, :fn-data 1, :num [1 2]}

As you can see, the namespace options are merged with the function options. Defaults can be provided with :exec-args, like you're used to from the clojure CLI.

Tasks

What about task integration? Let's adapt our bb.edn:

{:paths ["."]
 :tasks {doit {:task (let [x (exec 'tasks/my-function)]
                       (prn :x x))
               :exec-args {:task-data 1234}}
         }}

and invoke the task:

$ bb doit --cli-option :yeah -n 1 2 3
:x {:ns-data 1, :fn-data 1, :task-data 1234, :cli-option :yeah, :num [1 2 3]}

As you can see it works similar to -x, but you can provide another set of defaults on the task level with :exec-args. Executing a function through babashka CLI is done using the babashka.task/exec function, available by default in tasks.

Hope you will enjoy this!

New Clojure project quickstart

2022-08-02T23:59:59+00:00

Clojure beginners sometimes struggle with setting up a new Clojure deps.edn project compared to setting up a lein project. This is one of the reasons I've built neil. But not only for beginners, I've been using neil myself a ton too, to add common features to existing deps.edn projects. You may think that neil is a pun on lein. Of course it is. But the name is also an hommage to Neil Peart, one of the greatest progressive rock drummers to have ever lived.

The intent of this post is to give you a starting point from where you can figure out things further. This post isn't going to explain any details of how deps.edn and related tooling works. For that I'm going to refer you to here.

Let's install neil which is available for brew, scoop (Windows), nix, Clojure JVM or can easily be installed manually. Unless you use clojure JVM, neil runs with babashka for fast startup time.

If you've already installed babashka (perhaps indirectly by installing neil) but didn't yet install the clojure CLI or have problems doing so, then you can run bb clojure instead of clojure for launching Clojure. Instead of clj, on linux/macOS you'll want to use rlwrap bb clojure. If you are on Windows and struggle with the official clojure Powershell-based installation, bb clojure may come in handy too.

New

To start a new Clojure project, run neil new --name myproject. This produces a myproject directory with a very basic project layout based on the deps-new scratch template. Now we are are going to incrementally add some functionality to this project. If you like to skip most of these steps, you can start from the more fully featured app template with neil new app --name myproject.

Adding library

Let's decide that we're going to need a library to deal with files. Let's search for one:

$ neil dep search "file system"
:lib fs/fs :version 1.3.3 :description "File system utilities for clojure"
:lib me.raynes/fs :version 1.4.6 :description "File system utilities for clojure"
:lib babashka/fs :version 0.1.6 :description "Babashka file system utilities."

Let's go with the babashka/fs library:

$ neil dep add :lib babashka/fs :version 0.1.6

Now the library is added to deps.edn and we can use it in our project:

$ clj
Clojure 1.11.0
user=> (require '[babashka.fs :as fs])
nil

Test

Let's start by adding a test runner. Type: neil add test. After doing this, you will be able to run:

clojure -M:test

We don't have any tests in this project, so let's add one by adding a file:

test/myproject/core_test.clj

(ns myproject.core-test
  (:require [clojure.test :as t :refer [deftest is testing]]))

(deftest failing-test
  (testing "TODO: fix test"
    (is (= 3 4))))

Now run clojure -M:test again:

$ clojure -M:test

Running tests in #{"test"}

Testing myproject.core-test

FAIL in (failing-test) (core_test.clj:6)
TODO: fix test
expected: (= 3 4)
  actual: (not (= 3 4))

Ran 1 tests containing 1 assertions.
1 failures, 0 errors.

The test runner we added is the Cognitect Labs test-runner so check out the README of that project if you need to know more.

Update 2022-08-06: neil now comes with a new subcommand: test, so you can replace clojure -M:test with neil test. Also when you've created a project with neil new, neil add test will generate one default test for you.

REPL

Run:

neil add nrepl

to add a :nrepl alias to your project. Now you can run clj -M:nrepl to get a console REPL, but also a running nREPL server that you can connect to from your editor. Note that many editors also support jack-in and if you prefer to use that, you won't need this.

Uberjar

What's the equivalent of lein uberjar in the deps.edn world? You're going to need tools.build. To create a build.clj file (the program that is going to build your uberjar), run:

neil add build

Since the default build.clj file is going to assume your project is under git version control, let's initialize a git repo first:

git init
git add deps.edn src test
git commit -m "initial commit"

Before creating the uberjar, we have to add :gen-class to src/scratch.clj:

(ns scratch
  (:gen-class))

and we add :main 'scratch in the call to b/uber:

(b/uber {:class-dir class-dir
         :uber-file uber-file
         :basis basis
         :main 'scratch})

Now let's compile the uberjar:

clojure -T:build uber

And then let's run it:

$ java -jar target/lib1-1.2.1-standalone.jar 1 2 3
-main with (1 2 3)

Babashka tasks

If you have difficulty remembering the above invocations, you can write a bb.edn with some tasks:

bb.edn:

{:tasks
 {:requires ([babashka.fs :as fs])

  test {:doc "Run tests"
        :task (apply clojure "-M:test" *command-line-args*)}

  nrepl {:doc "Start REPL"
         :task (if (fs/windows?)
                 (clojure "-M:nrepl")
                 (shell "rlwrap bb clojure -M:nrepl"))}

  uber {:doc "Build uberjar"
        :task (clojure "-T:build uber")}}}

The clojure function is built into babashka and is a drop-in replacement for the clojure CLI which does not require any installation. With

(apply ... *command-line-args*)

we send any args you pass to a task invocation to clojure. So to run a specific test, you can write:

bb test -v myproject.core-test/failing-test

If you prefer to use the installed clojure CLI, you can do this by using:

(apply shell "clojure" ... *command-line-args*)

Now whenever you forget what to do in the current project, run bb tasks:

$ bb tasks
The following tasks are available:

test  Run tests
nrepl Start REPL
uber  Build uberjar

Hope this helps!

OSS Updates of May - June 2022

2022-06-30T23:59:59+00:00

In this post I'll give updates about open source I worked on during May and June 2022.

Sponsors

But first off, I'd like to thank all the sponsors and contributors that make this work possible! Top sponsors: Clojurists Together, Roam Research, Adgoji, Cognitect, Nextjournal.

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work via the following organizations:

Github Sponsors
OpenCollective (also see the clj-kondo one)
Clojurists Together

Projects

Babashka CLI

Turn Clojure functions into CLIs!

This is one of my newest projects. It aims to close the gap between good command line UX and calling Clojure functions. It is very much inspired by the clojure CLI, but solves a problem which sometimes causes frustration, especially among Windows users: having to use quotes in a shell. It also offers support for subcommands. One project benefiting from that is neil. I blogged about babashka CLI here.

Http-server

Serve static assets.

Another new project is http-server, which can be used in Clojure JVM and babashka to serve static assets in an http server.

Clj-kondo workshop

In June I had the honor and pleasure to give a workshop about clj-kondo at ClojureD. You can work through the material yourself if you'd like here. Feel free to join the clj-kondo channel on Clojurians Slack for questions. Here are some pictures from the event.

Jet

CLI to transform between JSON, EDN and Transit, powered with a minimal query language.

Changelog

The jet binary is now available for Apple Silicon and adds specter as part of the standard library for transforming data. Also, the output is colorized and pretty-printed using puget now.

Edamame

Changelog

Configurable EDN/Clojure parser with location metadata. It has been stable for a while and reached version 1.0.0. The API is exposed now in babashka and nbb as well.

Quickdoc

Nbb

Scripting in Clojure on Node.js using SCI.

Changelog

Added edamame.core, cljs.math, nREPL improvements and now has significant faster startup due to an improvement in SCI.

Clojure-lsp

Clojure/Script Language Server (LSP) implementation.

This project is driven by the static analysis done by clj-kondo and used by many people to get IDE-like features in editors like emacs and VSCode.

I added support for Apple Silicon using Cirrus CI.

Babashka

Native, fast starting Clojure interpreter for scripting.

Changelog

Two new version of babashka were released:

0.8.2 and 0.8.156. The last segment of the version number now indicates the release count, so the last release is the 156th release.

Babashka now also has a new Apple Silicon binary built on Cirrus CI. What is very exciting is that babashka can now execute schema from source. Compatibility with malli is underway.

Clj-kondo

A linter for Clojure code that sparks joy.

Changelog

New linters:

Clj-kondo now also has a new Apple Silicon binary built on Cirrus CI.

SCI

Configurable Clojure interpreter suitable for scripting and Clojure DSLs. Powering babashka, nbb, joyride and many other projects.

Changelog

New releases: 0.3.5 - 0.3.32

Highlights:

New sci.async namespace for asynchronous loading of code
Reduce advanced compiled JS output with about 20% (~900kb -> ~740kb)
Many improvements to defrecord

SCI configs

A collection of ready to be used SCI configurations.

This project contains configurations for reagent, promesa, etc. and are used in nbb, clerk and other projects.

A recent addition was a configuration for cljs.test which is now shared by nbb and joyride.

Process

Changelog

New releases: 0.1.2 - 0.1.4

Highlights:

Support exec call in GraalVM native-images - this means you can replace the current process with another one.

Scittle

The Small Clojure Interpreter exposed for usage in browser script tags.

Added support developing CLJS via nREPL. See docs.

Etaoin

Pure Clojure Webdriver protocol implementation.

This project is now compatible with babashka! Most of the work on this project was done by Lee Read. If you appreciate his work on this, or other projects like rewrite-clj, consider sponsoring him.

Misc

Brief mentions of miscellaneous other projects I worked on:

nbb-action-example - example of how to build a Github Action with nbb.
joyride - Making VS Code Hackable since 2022
dynaload - The dynaload logic from clojure.spec.alpha as a library
deps.clj - A faithful port of the clojure CLI bash script to Clojure.
fs - File system utility library for Clojure
fly-io-clojure - A fly.io example for Clojure. Also see examples for babashka and nbb.
pod-babashka-etaoin - Babashka pod wrapping Etaoin
pod-babashka-fswatcher - Babashka filewatcher pod

Babashka CLI: turn Clojure functions into CLIs

2022-06-24T23:59:59+00:00

Babashka CLI is a new library for command line argument parsing. The main ideas:

Put as little effort as possible into turning a Clojure function into a CLI, similar to -X style invocations. For lazy people like me! If you are not familiar with clj -X, read the docs here.
But with a better UX by not having to use quotes on the command line as a result of having to pass EDN directly: :dir foo instead of :dir '"foo"' or who knows how to write the latter in cmd.exe or Powershell.
Open world assumption: passing extra arguments does not break and arguments can be re-used in multiple contexts.
Because the line between calling functions from the command line and Clojure itself is blurred, validation of arguments should happen in your Clojure function, using your favorite tools (manually, spec, schema, malli...). As such, the library only focuses on coercion: turning argument strings into data which is then passed to your function.

Given the function:

(defn foo [{:keys [force dir] :as m}]
  (prn m))

and with a little bit of config in your deps.edn, you can call the function from the command line using:

clj -M:foo --force --dir=src

or:

clj -M:foo --force --dir src

which will then print:

{:force true, :dir "src"}

We did not have to teach babashka CLI anything about the expected arguments.

Another accepted syntax is:

clj -M:foo :force false :dir src

and this is parsed as:

{:force false, :dir "src"}

Booleans, numbers and keywords are auto-coerced, but if you want to make things strict, you can use metadata. E.g. if we want to accept a keyword for the option mode:

clj -M:foo :force false :dir src :mode overwrite

and parse it as:

{:force false, :dir "src" :mode :overwrite}

you can teach babashka CLI using metadata:

(defn foo
  {:org.babashka/cli {:coerce {:mode :keyword}}}
  [{:keys [force dir mode] :as m}]
  (prn m))

A leading colon is also accepted (and auto-coerced as keyword):

clj -M:foo :force false :dir src :mode :overwrite

The metadata format is set up in such a way that libraries need not have a dependency on babashka CLI itself.

Did you notice that the -M invocation now becomes almost identical to -X, but without quotes?

clj -M:foo :force true :dir src :mode :overwrite
clj -X:foo :force true :dir '"src"' :mode :overwrite

Let's look at a recent project, http-server, where I used babashka CLI to serve both -X, and -M needs.

The only argument hints defined there right now are:

(def ^:private cli-opts {:coerce {:port :long}})

although that could have been left out since numbers are auto-coerced.

The -main function simply defers to the clojure exec API function (intended for -X usage) with the parsed arguments:

(defn ^:no-doc -main [& args]
  (exec (cli/parse-opts args cli-opts)))

In turn, the exec function adds some light logic making it suitable for command line usage. It prints help when :help is true. Because I'm lazy, I just print the docstring of serve, the function that's going to be called:

(defn exec
  "Exec function, intended for command line usage. Same API as serve but
  blocks until process receives SIGINT."
  {:org.babashka/cli cli-opts}
  [opts]
  (if (:help opts)
    (println (:doc (meta #'serve)))
    (do (serve opts)
        @(promise))))

Also the exec function blocks, preventing the process from immediately exiting.

Now when I add this function to deps.edn using:

:serve {:deps {org.babashka/http-server {:mvn/version "0.1.3"}}
        :main-opts ["-m" "babashka.http-server"]
        :exec-fn babashka.http-server/exec}

it can be called both with -M and -X:

$ clj -M:serve --port 1339

or:

$ clj -M:serve :port 1339

or:

$ clj -X:serve :port 1339

And help printing is supported in both styles:

$ clj -M:serve --help
Serves static assets using web server.
Options:
  * `:dir` - directory from which to serve assets
  * `:port` - port

or:

$ clj -X:serve :help true

The -main function can also be used in babashka scripts:

#!/usr/bin/env bb

(require '[babashka.deps :as deps])
(deps/add-deps
 '{:deps {org.babashka/http-server {:mvn/version "0.1.3"}}})

(require '[babashka.http-server :as http-server])

(apply http-server/-main *command-line-args*)

$ http-server --help
$ http-server --port 1339

I hope you're convinced that with very little code, babashka CLI can let you support both -M, -X style invocations and babashka scripts, while improving command line UX!

Babashka survey Q1 2022 results!

2022-05-12T23:59:59+00:00

In Q1 of 2022 I ran the babashka survey again. I've done this once before (in November 2020) to see how people are using babashka and what they think could be improved. This year about 200 people responded. That is double the amount since the previous survey!

Here follows every question of the survey with a summary of the reactions.

How are you using babashka?

Shell scripting / bash replacement: 90%
Makefile replacing using babashka tasks: 43%
Small or internal web apps: 18%
Continuous integration: 29%

The first two options were selected in the majority of answers. Unsurprisingly most people are using babashka as a shell-scripting replacement for bash, exactly how it was intended. Babashka tasks is catching on: almost half of babashka users are using it to replace their Makefiles.

Are you using babashka for personal projects, at work, or both?

Personal projects: 73%
At work: 74%

About 50% of people used babashka both for personal projects and work. Only personal and only work was about 25% each. Some people use babashka to sneak in some Clojure at their non-Clojure jobs.

Where do you think babashka should be improved?

This question was free format. Some common themes:

Stacktraces, better error messages
better nREPL / CIDER-middleware support
documentation:
- overview of all available vars + docstrings in babashka
- cookbook
- videos
pods:
- documentation
- http proxy support
- make it easier to create pods
REPL integration for bb tasks
Producing standalone binaries
Tasks: sharing/importing tasks from other files/remote hosts
More compatibility with Clojure: deftype

What features / libraries / namespaces in babashka do you use the most?

This question was also free format. Probably the top 5 most named libraries:

What features or namespaces in babashka are redundant and could be left out?

The majority answer here was: none. People seem to be happy with the current selection of libraries.

What features or libraries would you like to see in babashka in the future, if any?

It's hard to see common patterns here. A random pick:

clojure.spec.alpha
html parsing
time library
native interop
ssh support
malli
specter

Note that spec is available in babashka via this library. Specter also works from source now since :mvn/version "1.1.4". Dealing with time is done via java.time and cljc.java-time is one of the java.time based libraries that work in babashka.

Are you using babashka.* libraries with Clojure on the JVM?

In order of mentions:

It's great that people are using fs and process on the JVM. I didn't expect so many people to be using babashka.curl on the JVM too!

Is the binary size of babashka important to you?

84% of the people didn't care, 12% cared and 4% had a nuanced answer.

Note that bigger binary size in babashka is correlated with a longer compilation time and more strain on CI resources. That is the primary reason I'm trying to keep it down.

What operating system are you using babashka on?

linux: 76%
macOS: 58%
Windows: 17%

Which babashka pods are you using, if any?

The top 7:

Note that for AWS we now also have a source-compatible library: awyeah-api.

When would you use babashka instead of JVM Clojure?

A pick of the free-formatted answers:

Everything I can use bb for.
Where deployment for bb is easier.
Short lived, small scripts.
Command line apps.
When performance isn't a strict requirement, but resource usage is
For small websites.

Any other feedback on babashka you would like to give?

Lots of thank you's and compliments... *blush*

Favorite pick:

My personal website, saltosti.com, is a scittle app running via a Also check out this nbb serverless example that Valtteri Harmainen made.



Using babashka with PHP: guestbook example
2022-01-07T23:59:59+00:00
One of the recurring themes in Clojure land is:
There is a popular widely used platform (JVM, browser, .NET, Node.js, ...).
We may not like the language that comes with that platform.
Adding Clojure on top of that platform might make the platform more tolerable and fun to use.
Enter PHP. PHP isn't a platform / language I like to use, but it sure is practical and widely adopted. I already have a PHP server running, so I thought, let's try some Clojure on top of this in the form of babashka. Babashka already has a built-in http server, but using this approach it isn't used. We just rely on PHP calling babashka when the PHP script is requested via nginx. The babashka script prints HTML and then exits. PHP sends the HTML to the browser as it would normally do. If you have already paid the operational costs of installing and maintaining PHP, this approach doesn't add much cost to it. A closely related CGI-based approach, but one that doesn't use PHP at all, has been explored before by Eccentric-J and you can read his blog post here.
The example described in this blog post is a guestbook.  You can view the guestbook here and the code is on Github. Below is a brief explanation of the components involved.
Database table
I created the following database table to store a name, greeting and some metadata:
CREATE TABLE public.guestbook
(
name text,
message text,
_created timestamp without time zone,
_session text,
CONSTRAINT session_unique UNIQUE (session)
)
PHP Babashka wrapper
This small PHP script forwards some of the request data to babashka:

The passthru command calls a locally installed version of babashka, in the same directory as the PHP script and adds some environment variables. It encodes posted data and query parameters as JSON, which in the babashka script we will decode as JSON:
(def post-data (-> (System/getenv "POST_DATA")
                   (cheshire/parse-string
                    true)))
Babashka guestbook script
In the babashka script, I use the babashka PostgreSQL pod to interact with the database:
(require '[babashka.pods :as pods])
(pods/load-pod "./pod-babashka-postgresql")
(require '[pod.babashka.postgresql :as sql])
Note that I also downloaded the pod locally into the directory. I needed to do this because the PHP server runs under a different user which doesn't have a home directory, so installing from the pod
registry didn't work for that reason.
Here I check if a user already posted a greeting before, using the session id:
(def session-id (System/getenv "SESSION_ID"))

(def db {:dbtype "postgresql"
         :user "guestbook"
         :password "guestbook"
         :database "guestbook"
         :port 5434})

(def posted-before
  (-> (sql/execute-one! db ["select count(*) from guestbook where _session = ?" session-id])
      :count))
The script uses hiccup to render HTML. E.g here is the code for the guestbook:
(defn render-messages []
  [:table.table
   [:thead
    [:tr
     [:th "Name"]
     [:th "Greeting"]]]
   [:tbody
    (for [{:guestbook/keys [name message]} entries]
      [:tr
       [:td name]
       [:td message]])]])
The guestbook form has some fields to protect against spambots: the user is supposed to fill in the outcome of a sum or multiplication. Also it is required to post the data using the same session id that you got when you entered the data. You can see that in the function process-post-data here.
The babashka script can print at any time and the output is rendered via the PHP wrapper as HTML. This is pretty handy for debugging. I wrote the script remotely on a server and just refreshed my browser any time I added some debug information, old school style.
One downside of this approach is whenever an exception happens you might not see any useful output in the page, so some defensive programming using try/catch is sometimes necessary.
So here you have it, documented for any PHP + Clojure user who might find it useful.


OSS Highlights of November - December 2021
2021-12-31T23:59:59+00:00
Like the previous OSS highlights, I'll give an overview of OSS work I did in November and December of 2021. I'd like to emphasize that I can do this work because of sponsoring via:
Clojurists Together
Github Sponsors
OpenCollective (also see the clj-kondo one)
for which I'm very grateful. I love helping peoeple by providing OSS software and this is now my main activity.
Enterprise support

I'd like to add that I'm also offering enterprise support for my OSS projects. It might be good to know there are options beyond sponsoring if your company needs an extra level of support for my OSS libraries. Recurring sponsors are eligible for a discount. Feel free to reach out via Twitter DM, e-mail or on Clojurians Slack to discuss options.
Do you need help with #clojure #graalvm compilation, #clojure static analysis/linting tools, or anything related to my #oss projects? I'm available for USD 150/hr. I also do custom license/support contracts if @github sponsors doesn't fit your business.#cljkondo #babashka #sci
— (λ. borkdude) (@borkdude) December 27, 2021
 Babashka
Native, fast starting Clojure interpreter for scripting.
Releases: 0.7.3 , 0.7.2 , 0.7.0 , 0.6.8 , 0.6.7 , 0.6.6 , 0.6.5
Highlights:
Load tasks and deps from other bb.edn file using --config and --deps-root options #1110
Add compatibility with clojure.spec.alpha. See babashka/spec.alpha and this blog
  post.
Compatibility with a fork of
  tools.namespace. This allows running the Cognitect test-runner (Cognitest) from source.
tools.bbuild.
Compatiblity with markdown-clj (see blog)
Clj-kondo
A linter for Clojure (code) that sparks joy.
Releases: 2021.12.19 , 2021.12.16 , 2021.12.01
Highlights:
Automatically load configurations from .clj-kondo/*/*/config.edn. This can be disabled with :auto-load-configs false.  See issue #1492. This makes life easier for those using clojure-lsp which already uses the --copy-configs option by default.
Several new linters: :reduce-without-init, :duplicate-case-test-constant, :unexpected-recur, :used-underscored-binding and a few around docstrings. See the linters.md docs for details.
better-cond now bundles a clj-kondo config!
Note that most new linters in clj-kondo are going to default to :level :off unless they detect a compile time error, like :duplicate-case-test-constant.
Special thanks to new contributor @mknoszlig who has been quite active in adding new linters in collaboration with me.
SCI
Configurable Clojure interpreter suitable for scripting and Clojure DSLs.
Releases: 0.2.8
Highlights:
Add copy-ns macro for copying an entire Clojure or ClojureScript namespace into a SCI context
clojure.core/read improvements
Lots of little 'devil is in the details' correctness improvements
Nbb
Ad-hoc CLJS scripting on Node.js using SCI.
Releases: v0.0.108 - v0.1.0. See npm.
Highlights:
Add nbb.classpath which is also available in the JS API.
Add cljs.bean as built-in library.
Add --help and --main command line options (finally!)
Neil
Automatically use newest tool.build with add build
Edamame
Configurable EDN/Clojure parser with location metadata
Releases: 0.0.13 , 0.0.14 , 0.0.15 , 0.0.16 , 0.0.17 , 0.0.18 , 0.0.19
Many small improvements. Edamame now supports reading with a reader which is not an indexing reader too, for compatibility with clojure.core/read.
Babashka.fs
File system utility library.
Releases: 0.1.2 , 0.1.1
Highlights: improve fs/which on Windows, add with-temp-dir macro.
Babashka.process
Clojure wrapper for java.lang.ProcessBuilder.
Releases: 0.1.0
Highlights:
Resolve binaries on Windows using fs/which
Support deref with timeout #50 (@SevereOverfl0w)
tools.namespace
In this core library I contributed two ClojureScript fixes:
TNS-51
TNS-57


Using clojure.spec.alpha with babashka
2021-12-10T23:59:59+00:00
Tl;dr
If you want to use clojure.spec.alpha with babashka, upgrade to 0.7.0 or newer and use babashka/spec.alpha as a library.
The issue
Spec is a library for validating and conforming (destructuring) data that comes with Clojure. For over a year there was an open issue in the babashka Github repo about whether to include clojure.spec into babashka, a fast starting native Clojure scripting environment. Clojure.spec is used in many libraries and adding it would add compatibility with more of them. I already knew that from a technical perspective SCI (the interpreter used by babashka) and clojure.spec can work together well. I've put this into practice in grasp, a tool to "grep" Clojure source using clojure specs. It provides a binary which includes clojure spec in the same way that babashka would. The question is: should we include clojure.spec.alpha in babashka?
What does built-in mean?
Adding a library as a built-in in babashka means that it is compiled into babashka's native image. The functions are pre-compiled to native machine code and aren't run through the SCI interpreter. This is much better for performance, but also for startup time. Loading libraries from source in babashka involved parsing and analyzing code before using it. Adding a library as a built-in means that this work is already done at compile time, by the Clojure compiler instead of SCI.
Alpha
So far all built-in third party libraries in babashka are well established projects that have been around for years and whose APIs are unlikely to change. Boring in the good sense. Clojure spec, as of now, is alpha. That doesn't mean that clojure.spec.alpha is unstable, but what does it mean? Will it ever disappear from Clojure once it's not alpha anymore? In 2019 Alex Miller gave an inspiring talk at ClojuTRE in which he announced that spec 2 was soon coming. I'm still hoping it will soon come, but I understand that a lot of good things happened at Cognitect and they had other things to work on. In the open babashka issue I've asked for feedback on including clojure.spec.alpha as it is and most people were in favor of waiting for clojure spec 2. I decided to be patient and investigate alternatives. If we aren't going to include clojure.spec.alpha as a built-in, what alternatives do we have? We could try to run clojure.spec.alpha from source instead of a built-in so people can use it as an optional library.
Test.check
The test.check library is used by clojure.spec to generate random data from specs. Libraries operating in the same space as spec, like Malli, are using this library for the same purpose. I decided to go ahead and add this library in babashka as a preparation for the soon coming spec 2. This was done in 0.2.8, released in January 2021. Since then you could already use namespaces from test.check in babashka, without using it with spec.
Spartan.spec
When babashka was only a few months old, it didn't cover as many clojure features as it does today. Running clojure.spec.alpha from source wasn't something within reach, mostly because babashka didn't support protocols. Protocols were introduced in version 0.1.1 in June of 2020, but by then I already made a rewrite of clojure.spec.alpha that used plain hashmaps instead of protocols. This version was called spartan.spec: spartan, because it supported the basic features of spec, but not all. It did not support generators, fdef and instrumentation. Although I could have made that work, just validating and conforming data is what most people were doing with spec in the libraries that I've been trying to run with babashka. Upon requiring spartan.spec it would create the namespace clojure.spec.alpha for you, so libraries loaded after that point would think they were using the original. This approach proved out to work pretty well. Even tools like expound worked with spartan.spec. But spartan.spec was a rewrite of spec and needed more work if we wanted to cover the other features. An effort that could be spared if babashka could just load the original spec from source.
Clojure.spec.alpha from source
When introducing protocols, I hadn't thought of revisiting running clojure.spec.alpha from source again. For some reason this only occurred to me in the past few days. I discovered that the remaining incompatibilities were minimal. Here are some things I found and what I did in a fork to solve the compatibility with babashka:
Spec uses clojure.lang.Compiler/demunge to turn function names into symbols for displaying information about them. This functionality is also provided by clojure.main/demunge and clojure.repl/demunge, and both functions were already in babashka. I didn't want to expose clojure.lang.Compiler in babashka, since babashka doesn't have a compiler at all, so I replaced these calls with the clojure.main/demunge function. I raised an issue on ask.clojure to see if we can get this function into clojure.core.
Spec uses Java interop on clojure.lang.Var to get the namespace and name symbols from a var. In babashka there is no clojure.lang.Var: SCI has its own var type which works both in the JVM / GraalVM native and in JavaScript. I used the metadata on SCI vars to get this information instead.
The function clojure.spec.alpha/multi-spec-impl uses Java interop on multimethods, so I had to expose clojure.lang.MultiFn in babashka to make that possible. I noticed this when trying to use multi-spec in babashka when I thought I was already done porting. Surprisingly spec's tests didn't catch this, which I had been using to verify if the port worked. I pulled out some examples from the spec guide and turned those into tests for multi-spec. Alex Miller included those tests upstream after I poked him about it. Thanks Alex!  The multi-spec-impl function pulls out the dispatch function from a multimethod with (.dispatchFn mm). This is not a method call, since dispatchFn is a public field. I needed to improve SCI to support public field lookups in Java classes. The expression could have been written like (.-dispatchFn mm) to make the field lookup explicit and this is what I changed it to, in order to not have to support this ambiguity in SCI. This issue would have been easier to deal with if clojure.core exposed dispatch-fn like ClojureScript does. Vote here to make that happen. Also, get-method is a core function, the .getMethod interop wasn't really necessary, but perhaps it is there for performance reasons. This is now supported in babashka without changes.
clojure.lang.RT/checkSpecAsserts is not available in babashka. I replaced this with an atom in the clojure.spec.alpha namespace.
With these minimal changes and some functions I needed to expose in babashka which weren't there before (inst-ms being one of them), babashka is now able to run clojure.spec. All tests are passing:
$ bb test

Testing clojure.test-clojure.spec

Testing clojure.test-clojure.instr

Testing clojure.test-clojure.multi-spec

Ran 13 tests containing 168 assertions.
0 failures, 0 errors.
In addition to spec's own tests, I've added tests from the following libraries that are using spec to babashka's CI: better-cond, coax, orchestra and integrant.
The benefit of maintaining a fork with minimal changes is that I can easily pull in changes from upstream.  The fork is available here and works with the newly released babashka 0.7.0.
A demo of data generation using spec:
(require '[babashka.deps :as deps])

(deps/add-deps '{:deps {org.babashka/spec.alpha {:git/url "https://github.com/babashka/spec.alpha"
                                                 :git/sha "644a7fc216e43d5da87b07471b0f87d874107d1a"}}})

(require '[clojure.spec.alpha :as s]
         '[clojure.spec.gen.alpha :as gen]
         '[clojure.string :as str])

(prn (gen/sample (s/gen int?)))

(s/def ::street (s/and string? (complement str/blank?)))
(s/def ::street-number int?)
(s/def ::address (s/keys :req-un [::street ::street-number]))
(s/def ::name (s/and string? (complement str/blank?)))
(s/def ::contact (s/keys :req-un [::name ::address]))
(prn (gen/sample (s/gen ::contact)))
(0 -1 0 -1 -6 -1 -2 0 9 1)
({:name "r", :address {:street "Y", :street-number -1}} {:name "m", :address {:street "k8", :street-number -1}} {:name "5", :address {:street "s1E", :street-number 0}} {:name "o4H", :address {:street "4", :street-number -1}} {:name "nkhf", :address {:street "4Fh92", :street-number 1}} {:name "e", :address {:street "X", :street-number 4}} {:name "5v76a9B", :address {:street "bEf7e", :street-number 23}} {:name "213V", :address {:street "fNX3wr", :street-number 5}} {:name "8336lvbb9", :address {:street "fVP", :street-number -1}} {:name "x8X", :address {:street "utPQA", :street-number -7}})
The above example executes in about 120ms on my machine.


Making markdown-clj babashka-compatible
2021-11-17T23:59:59+00:00
Recently I migrated the highlighting of Clojure code in this blog from CLJS to pure babashka code. See this blog post.
For rendering markdown files to html files I was using bootleg as a pod. A pod is a binary which can act as an RPC server for babashka. Learn more about that here.
Today I noticed a new PR in bootleg. The user who submitted the PR also used bootleg for markdown compilation in babashka, but bootleg didn't expose an option that the underlying library, markdown-clj, supports. The PR fixes that.
Then I wondered, can babashka run markdown-clj from source, rather than via a pod? Babashka supports a large subset of Clojure and a large subset of classes from the JVM. By now it can run a fair share of Clojure libraries from source, but sometimes minor tweaks are necessary. I looked at the dependencies of markdown-clj. The only dependency it uses is clj-commons/clj-yaml which is luckily included in babashka. If it wasn't, I'm pretty sure that dependency could be made optional for those that do not need any YAML support in their markdown compilation. When looking closer, I learned that this dependency is used in a small corner of markdown-clj to parse front-matters. I stripped those front-matters out when I migrated from Octopress to
babashka, but I realize now I could have left those in. Since the rest of markdown-clj is pure Clojure, there's a reasonable chance it will work with babashka. Let's try and see.
I cloned the repo locally and tried this:
$ git clone git@github.com:yogthos/markdown-clj.git
$ cd markdown-clj
$ bb -cp src/clj:src/cljc -e "(require '[markdown.core :as md])
  (md/md-to-html-string \"# 100\")"
----- Error --------------------------------------------------------------------
Type:     java.lang.IllegalStateException
Message:  Can't dynamically bind non-dynamic var #'markdown.common/*substring*
Location: 73:3
The issue here is that SCI, the interpreter running Clojure code in babashka, doesn't understand this way of defining dynamic vars yet:
(declare ^{:dynamic true} *substring*)
Of course this should be fixed, so I filed an issue with SCI here.
But changing the code in markdown-clj to:
(def ^{:dynamic true} *substring*)
doesn't seem to have any downsides and would make that part compatible with babashka. There was another dynamic var that had the same problem. After fixing that, I got:
$ bb -cp src/clj:src/cljc -e "(require '[markdown.core :as md])
  (md/md-to-html-string \"# 100\")"
"100"
It worked!
To be sure all markdown-clj tests pass with babashka, I added a test runner. The Cognitect Labs test-runner (Cognitest :-D) works with babashka, provided that you include the babashka compatible tools.namespace fork in your dependencies. The bb.edn so far:
{:deps {markdown-clj/markdown-clj {:local/root "."}}
 :tasks
 {test:bb {:doc "Runs tests with babashka"
           :extra-paths ["test"]
           :extra-deps {io.github.cognitect-labs/test-runner
                        {:git/tag "v0.5.0" :git/sha "b3fd0d2"}
                        org.clojure/tools.namespace
                        {:git/url "https://github.com/babashka/tools.namespace"
                         :git/sha "3625153ee66dfcec2ba600851b5b2cbdab8fae6c"}}
           :requires ([cognitect.test-runner :as tr])
           :task (apply tr/-main "-d" "test" *command-line-args*)}
 ,,,}}
After that, you can run bb test:bb:
Running tests in #{"test"}
----- Error --------------------------------------------------------------------
Type:     clojure.lang.ExceptionInfo
Message:  Could not resolve symbol: org.apache.commons.lang.StringEscapeUtils/unescapeHtml
Location: /private/tmp/markdown-clj/test/markdown/md_test.cljc:331:11
Phase:    analysis
Ouch. The class org.apache.commons.lang.StringEscapeUtils, which is used in the tests, isn't available in babashka. Let's comment that one out. Luckily, the tests are already in a .cljc file, so using the :bb reader conditional lets us make changes specifically for babashka while leaving it the same for the other targets:
#?(:bb nil
   :default
   (is (= "abc@google.com"
          (#?(:clj  org.apache.commons.lang.StringEscapeUtils/unescapeHtml
              :cljs goog.string/unescapeEntities)
           (entry-function "")))))

#?(:bb nil
   :default
   (is (= "abc_def_ghi@google.com"
          (#?(:clj  org.apache.commons.lang.StringEscapeUtils/unescapeHtml
              :cljs goog.string/unescapeEntities)
           (entry-function "")))))
Yes, reader conditionals can be nested. You didn't see that one coming did you? After this change, bingo!
$ bb test:bb

Running tests in #{"test"}

Testing markdown.md-file-test

Testing markdown.md-test

Ran 84 tests containing 146 assertions.
0 failures, 0 errors.
While I was at it, I also added a deps.edn and tasks for running the Clojure and ClojureScript tests.
deps.edn:
{:paths ["src/clj" "src/cljs" "src/cljc"]
 :deps {clj-commons/clj-yaml {:mvn/version "0.7.107"}}
 :aliases
 {:test
  {:extra-paths ["test"]
   :extra-deps {io.github.cognitect-labs/test-runner
                {:git/tag "v0.5.0" :git/sha "b3fd0d2"}
                criterium/criterium {:mvn/version "0.4.4"}
                commons-lang/commons-lang {:mvn/version "2.6"}}
   :main-opts ["-m" "cognitect.test-runner"]
   :exec-fn cognitect.test-runner.api/test}
  :cljs-test
  {:extra-paths ["test"]
   :extra-deps {olical/cljs-test-runner {:mvn/version "3.8.0"}
                org.clojure/clojure {:mvn/version "1.10.1"}
                org.clojure/clojurescript {:mvn/version "1.10.520"}}
   :main-opts ["-m" "cljs-test-runner.main"]}}}
bb.edn:
{:deps {markdown-clj/markdown-clj {:local/root "."}}
 :tasks
 {,,,
  test:clj {:doc "Runs tests with JVM Clojure"
            :task (clojure "-X:test")}
  test:cljs {:doc "Runs tests with ClojureScript"
             :task (clojure "-M:cljs-test")}}}
$ bb test:clj

Running tests in #{"test"}

Testing markdown.md-file-test

Testing markdown.md-test

Ran 84 tests containing 148 assertions.
0 failures, 0 errors.

$ bb test:cljs

Testing markdown.md-test

Ran 75 tests containing 136 assertions.
0 failures, 0 errors.
After that change, I could use markdown-clj directly in the code for rendering this blog. You can see the diff here. Previously I also used bootleg for hiccup, but babashka already has hiccup as a built-in dependency so that wasn't necessary anymore either.  So the blog rendering code is pure babashka now.
I submitted a PR with these changes to the markdown-clj repository. This PR was merged and a new
version was published tn Clojars, which is used in the deps.edn of this blog.
Performance considerations
What about performance? Previous re-rendering all of the blog posts took 4 seconds and now it takes a second longer. Running markdown-clj from source is slower than using the pod since the code in the pod is all pre-compiled and doesn't run through SCI. Compiling a single blog post isn't noticeably slower. The difference is small enough to move forward with markdown-clj from source for now. Since it's easy to move between pure babashka, using the bootleg pod or running JVM Clojure, I keep my options open.
After writing the last paragraph, I made this blog's code run with JVM Clojure. Let's compare the time for recompiling all blog posts (which is triggered by a change to e.g. render.clj):
$ touch render.clj
$ time bb render
...
bb render   3.51s  user 0.17s system 75% cpu 4.891 total

$ touch render.clj
$ clojure -M -m render
...
clojure -M -m render   21.97s  user 1.21s system 276% cpu 8.386 total
Recompiling the entire blog with babashka is still faster, likely because the startup time on the JVM isn't that good because Clojure has to load more libraries at startup.
If we AOT those libraries then JVM Clojure becomes faster but still the startup time doesn't outweigh the performance of the JVM:
$ mkdir -p classes
$ clojure -M -e "(compile 'render)"
$ time clojure -M -m render
...
clojure -M -m render   13.91s  user 1.05s system 259% cpu 5.753 total
Most of the time I won't recompile all my blog posts but just one:
$ touch posts/markdown-clj-babashka-compatible.md
$ time bb render
Processing markdown for file: posts/markdown-clj-babashka-compatible.md
bb render   0.42s  user 0.12s system 79% cpu 0.682 total

$ touch posts/markdown-clj-babashka-compatible.md
$ time clojure -M -m render
Processing markdown for file: posts/markdown-clj-babashka-compatible.md
clojure -M -m render   5.58s  user 0.60s system 189% cpu 3.266 total
nbb
Dmitri Sotnikov, the author of markdown-clj, suggested that markdown-clj could also be made compatible with scittle and nbb. The only change I had to make to the original source was to change cljs.reader into clojure.edn and then it worked:
$ nbb -cp src/clj:src/cljc:src/cljs -e "(require '[markdown.core :as md])
  (md/md->html \"# 100\")"
"100"
After adding a runner:
(ns nbb-runner
  (:require [clojure.string :as str]
            [clojure.test :refer [run-tests]]
            [nbb.classpath :as cp]))

(cp/add-classpath (str/join ":" ["src/cljs" "src/cljc" "test"]))

(require '[markdown.md-test])

(run-tests 'markdown.md-test)
and a few minor tweaks to the tests, the library runs with nbb:
Testing markdown.md-test

Ran 75 tests containing 134 assertions.
0 failures, 0 errors.



Publishing an nbb project to npm
2021-11-10T23:59:59+00:00
This post describes how to publish an nbb based project to npm. It is extracted from this entry from the nbb documentation.
Nbb is an ad-hoc CLJS scripting environment for Node.js. You could say that it is to CLJS on Node.js what babashka is to JVM Clojure.
As an example we will build a CLI, print-cli-args that prints command line arguments.
First, create a new directory print-cli-args and cd into it. Then create a package.json:
{
  "name": "print-cli-args",
  "version": "0.0.1",
  "dependencies": {
    "nbb": "0.0.109"
  },
  "bin": {
    "print-cli-args": "index.mjs"
  }
}
The CLI depends on a specific version of nbb and exposes itself as a binary called print-cli-args, which is linked to index.mjs in our project. It is important to use .mjs rather than .js so Node.js recognizes the file as an ES6 module.
The index.mjs file is a small wrapper that sets up the classpath for nbb to the src directory relative to the wrapper using addClassPath. It also calls the initial CLJS file using loadFile.
#!/usr/bin/env node

import { addClassPath, loadFile } from 'nbb';
import { fileURLToPath } from 'url';
import { dirname, resolve } from 'path';

const __dirname = fileURLToPath(dirname(import.meta.url));

addClassPath(resolve(__dirname, 'src'));
await loadFile(resolve(__dirname, 'src/print_cli_args/core.cljs'));
Finally, in src/print_cli_args/core.cljs we write the CLJS code:
(ns print-cli-args.core
  (:require [clojure.string :as str]))

(def cmd-line-args (not-empty (js->clj (.slice js/process.argv 2))))

(println "Your command line arguments:"
         (or (some->> cmd-line-args (str/join " "))
             "None"))
To test the CLI in development, run node index.mjs 1 2 3.
When you npm install -g from within the project, you can call print-cli-args from anywhere on your system.
When everything looks good, it's time to npm publish so everyone can enjoy your new CLI.
After you have done so, you can run this example from npm using:
$ npx print-cli-args 1 2 3
Your command line arguments: 1 2 3
or:
$ npm install -g print-cli-args
$ print-cli-args 1 2 3
Your command line arguments: 1 2 3



Writing a Clojure highlighter from scratch
2021-11-08T23:59:59+00:00
In the aftermath of my previous blog post about using Nextjournal's clojure-mode for better highlighting, I tried optimizing the JS output and got a look at the internals of CodeMirror 6. I realized that writing a Clojure highlighter from scratch wasn't that hard if you had the right tools at hand:
A tool which can break Clojure code into parts, tells you what each part is (symbol, keyword, vector, etc.)  and also provides a way to put the parts together again, with preservation of whitespace. This tool is already available in babashka and is a library called rewrite-clj.
A tool that can provide additional semantic information: is a symbol a local or a var? The static analysis output of clj-kondo provides that information. This part is optional for incrementally better highlighting.
I spent my Sunday afternoon combining these tools which resulted in a 160 line script called highlighter.clj which is now used to do the highlighting of this blog.
This blog post is a high level walkthrough of the code. Let's begin with the first step.
1. Parse blocks of Clojure code from markdown and apply highlighting.
(defn highlight-clojure [markdown]
  (str/replace markdown #"(?m)```\s*clojure\n([\s\S]+?)\n\s*```"
               (fn [[_ code]]
                 (try (-> (str/trim code)
                          (htmlize)
                          (str/replace "[" "[")
                          (str/replace "]" "]")
                          (str/replace "*" "*")
                          (str/replace "_" "_"))
                      (catch Exception e
                        (log "Could not highlight: " (ex-message e) code)
                        markdown)))))
Parsing blocks of Clojure code from a markdown post is done using a basic regex. Then we pass the Clojure code to the htmlize function. After that we escape some markdown-specific characters, so the markdown compiler won't be confused by them.. If the highlighting failed for some reason, we log it and fall back on the unprocessed markdown. During the implementation I found several snippets of Clojure code with unbalanced parens which I had to fix, since rewrite-clj doesn't accept it. So all examples from this blog should be copy-pastable into your Clojure editor without problems from now on.
2. Parse and analyze Clojure using clj-kondo and rewrite-clj:
(defn htmlize [code]
  (binding [*analysis*
            (let [ana (analysis code)]
              {:locals (locals ana)
               :var-defs (var-defs ana)})]
    (let [html (-> code p/parse-string-all node->html)]
      (format "%s" html))))
Clj-kondo provides information about vars, keywords and locals. We will apply special styling to var definitions and locals and their usages.
3. Clj-kondo analysis
(pods/load-pod 'clj-kondo/clj-kondo "2021.10.19")

(require '[pod.borkdude.clj-kondo :as clj-kondo])

(defn analysis [code]
  (let [tmp (doto (fs/file (fs/create-temp-dir) "code.clj")
              fs/delete-on-exit)]
    (spit tmp code)
    (-> (clj-kondo/run!
         {:lint [(str tmp)]
          :config {:output {:analysis {:locals true}}}})
        :analysis)))
To call clj-kondo from babashka, we use the binary from the pod
 registry which is automatically downloaded via load-pod if you provide a fully qualified symbol and version. We write the code to a temp file and lint it. We ask for the static analysis data. Locals are not included by default, so we set :locals to true. Later on we want to detect if a symbol is a local or a var. We do this by making a set of locations from the analysis data for each group:
(defn locals [analysis]
  (->> analysis
       ((juxt :locals :local-usages))
       (apply concat)
       (map (juxt :row :col)) set))

(defn var-defs [analysis]
  (->> analysis
       :var-definitions
       (map (juxt :name-row :name-col)) set))
4. Rewrite-clj nodes
Next, we parse the code to rewrite-clj nodes. Each node has a tag for which we write a multi-method to dispatch on:
(defmulti node->html tag)
For each kind of node we will emit a  element with an associated class. For instance, :foo will become :foo and so on.
A small helper function:
(defn span [class contents]
  (format "%s"
          class contents))
Here is the implementation for a map node:
(defmethod node->html :map [node]
  (span "map" (format "{%s}"
                      (str/join (map node->html (:children node))))))
A map node has :children so we just call node->html for each child and join the strings together.
I wrote a :default implementation that logs a warning for nodes that I hadn't implemented yet:
(defmethod node->html :default [node]
  (log "Unhandled tag:" (tag node))
  (span (name (tag node))
        (if (:children node)
          (str/join "" (map node->html (:children node)))
          (str node))))
and added implementations for all of the nodes that occurred in Clojure snippets in all the posts of this blog so far, by working through the list of unhandled tags.
Rewrite-clj doesn't give different tags for symbols, strings, numbers and so on: it groups them under the :token tag. So there is some extra work needed to get different highlighting for different types of tokens. I wrote a function that returns a CSS class by looking at the contents of the node or at the type of value of the node. For a symbol node, I want different highlighting for vars and locals. This is where I check in the clj-kondo analysis if the symbol on that location is a local or var and else fall back on the general symbol CSS class.
(defn token-class [node]
  (cond (:k node) "keyword"
        (:lines node) "string"
        (contains? node :value)
        (let [v (:value node)]
          (cond (number? v) "number"
                (string? v) "string"
                (boolean? v) "boolean"
                (nil? v) "nil"
                (symbol? v)
                (cond (contains? (:locals *analysis*)
                                 ((juxt :row :col) (meta node)))
                      "local"
                      (contains? (:var-defs *analysis*)
                                 ((juxt :row :col) (meta node)))
                      "def"
                      :else
                      "symbol")
                :else (name (tag node))))
        ;; fallback, log missing case
        :else (log (tag node) (keys node) (sexpr node) (type (sexpr node)))))

(defmethod node->html :token [node]
  (span (token-class node)
        (escape (str node))))
5. Styling
Finally I wrote some styling:
.def { color: #00f; }
.symbol { color: #708; }
.local { color: cadetblue; }
.string { color: #a11; }
.number { color: blue; }
.keyword { color: #219; }
.uneval { filter: opacity(0.5); }
For :uneval nodes, which is rewrite-clj's name for expressions that are ignored using the reader underscore dispatch macro: #_(+ 1 2 3), I set opacity to 0.5. Can you see the difference?
(+ 1 2 3)
#_(+ 1 2 3)
That's it really. A Sunday afternoon well spent. The code for the highlighter is here. In the future I might pull out this code into a library. The renderer could support ANSI escape code sequences for the terminal as well. Let me know what you think.


Better Clojure highlighting with nextjournal/clojure-mode
2021-11-05T23:59:59+00:00
Almost two weeks ago I wrote about how I replaced my Octopress blog with about 200 lines of babashka. I also wrote that I used highlight.js for highlighting. This blog is mostly about Clojure/Script, so improvements in highlighting of Clojure code are welcome. Highlight.js does a good job, but it's not as good as it can be. E.g. Nextjournal's clojure-mode, which is a CodeMirror 6 integration for Clojure, covers a lot more detail. So I tried to strip the demo of clojure-mode to the bare mininum for just for highlighting. I ended up with about 320kb (117kb gzipped) of optimized JS based on a CLJS implementation. Trying to squeeze the last bit out by rewriting it to JS and bundling it with Rollup.js like the CodeMirror docs suggest yielded 600kb at first. But it turned out I needed to enable the terser output
plugin and this got the bundle size down to 200kb (79kb gzipped).
In the future it might be possible to get even smaller builds when CodeMirror 6 gets better support for 'just highlighting'. There is a discussion about it here.
To automate building the highlighter code when I re-render this blog, I again used babashka tasks:
{:paths ["."]
 :tasks
 {:requires ([babashka.fs :as fs]
             [tasks-helper :as th])
  ...
  build-highlighter {:doc "Build Clojure highlighter JS"
                     :task
                     (when
                         (seq (fs/modified-since "public/clojure_highlighter.js"
                               ["src"]))
                       (shell "npx rollup -c rollup.config.js"))}
  render {:doc "Render blog"
          :depends [build-highlighter]
          :task (load-file "render.clj")}
  ...}}
If the public/clojure_highlighter.js file is already there and JavaSceipt sources hasn't changed, the build-higlighter step won't take any significant time due to the use of fs/modified-since which I blogged about here.
$ bb clean
$ time bb render

src/clojure_highlighter/main.js → public/clojure_highlighter.js...
created public/clojure_highlighter.js in 2.7s
bb render   6.26s  user 0.84s system 155% cpu 4.557 total

$ time bb render
bb render   0.09s  user 0.05s system 81% cpu 0.174 total
The above snippet is still highlighted with Highlight.js, but ... is highlighted with clojure-mode.
To show off the highlighting, here is the CLJS code for the highlighter, which I ported to JS later on.
(ns clojure-highlighter.main
  (:require ["@codemirror/highlight" :as highlight :refer [tags]]
            ["@codemirror/language" :as language]
            ["@codemirror/state" :refer [EditorState]]
            ["@codemirror/view" :as view :refer [EditorView]]
            ["lezer-clojure" :as lezer-clj]
            [clojure.string :as str]
            [goog.object]))

(def theme
  (.theme EditorView
          #js {".cm-content" #js {:white-space "pre-wrap"
                                  :padding "10px 0"}
               "&.cm-focused" #js {:outline "none"}
               ".cm-line" #js {:padding "0 9px"
                               :line-height "1.6"
                               :font-size "16px"
                               :font-family "var(--code-font)"}
               ".cm-matchingBracket"
               #js {:border-bottom "1px solid var(--teal-color)"
                    :color "inherit"}
               ".cm-gutters" #js {:background "transparent"
                                  :border "none"}
               ".cm-gutterElement" #js {:margin-left "5px"}
               ;; only show cursor when focused
               ".cm-cursor" #js {:visibility "hidden"}
               "&.cm-focused .cm-cursor" #js {:visibility "visible"}}))

(def style-tags
  (doto #js {:DefLike (.-keyword tags)
             "Operator/Symbol" (.-keyword tags)
             "VarName/Symbol" (.definition tags (.-variableName tags))
             :Boolean (.-atom tags)
             "DocString/..." (.-emphasis tags)
             :Discard! (.-comment tags)
             :Number (.-number tags)
             :StringContent (.-string tags)
             :Keyword (.-atom tags)
             :Nil (.-null tags)
             :LineComment (.-lineComment tags)
             :RegExp (.-regexp tags)}
    (goog.object/set "\"\\\"\"" (.-string tags))))

(def parser lezer-clj/parser)

(def the-parser
  (.configure parser
              #js {:props #js [(highlight/styleTags style-tags)]}))

(def syntax
  (.define language/LezerLanguage
           #js {:parser the-parser}
           #js {:languageData
                #js {:commentTokens {:line ";;"}}}))

(defonce extensions #js[theme
                        (.of (.-editable EditorView) false)
                        highlight/defaultHighlightStyle
                        #js[syntax]])

(defn ^:dev/after-load render []
  (let [elts (js/document.querySelectorAll "code.clojure")]
    (.forEach elts
              (fn [elt]
                (new EditorView
                     #js {:state
                          (.create EditorState
                                   #js{:doc (str/trim (.-innerText elt))
                                       :extensions #js [extensions]})
                          :parent elt})
                (.remove (.-firstChild elt))))))
You can find the code for this blog on Github, including the above code.
Edits:
2021-11-06: Include Rollup.js terser output plugin in blog post.


OSS Highlights of September - October 2021
2021-11-03T23:59:59+00:00
This year I'm receiving a long term grant from Clojurists
Together. CT asked me to do a bimonthly report on my activities or write a blog post and link to that. That's what I'm doing here. I'll be going over the releases of existing and new projects and will mention highlights in some of them. Often, the devil is in the details and there aren't any new user-facing features, but still a lot of work has gone into refining existing features.
Donations from Github Sponsors, OpenCollective and the year long CT grant directly allow me to spend more time on open source. The list you are seeing here is a result of this. I love working on open source so thank you for allowing me to do this. In this ClojureScript podcast episode, Jacek Schae interviewed me on my decision to quit my previous job and work more on Clojure OSS. Have a listen if you want to know more about my motivations. If aside from sponsoring, you or your company needs work done on any of these or related projects and want to make a custom arrangement, please do reach out.
Note that the projects listed below are not exclusively my effort and are worked on by a number or regular contributors. My thanks also goes out to them.
Nbb
Ad-hoc CLJS scripting on Node.js using SCI.
Many releases on npm.
Highlights:
Console REPL. If you have Node.js simply type npx nbb and you will be dropped into a REPL.
Socket server REPL
nREPL server for development with Calva
Add clojure.test so you can now use nbb to develop e.g. browser tests using puppeteer or playwright
Support for reader conditionals using :org.babashka/nbb
Print nicer stacktrace when error happens (similar to bb)
Misc. fixes and enhancements.
Add js-interop module
Add Javascript API
Many exciting things are happening around this project in the community. It's now possible to run nbb on lambda. Exercism is using babashka and nbb to run Clojure exercise submissions. Sitefox is a CLJS + Node.js web framework that works well with nbb.
Clj-kondo
A linter for Clojure (code) that sparks joy.
Releases: 2021.10.19 , 2021.09.25 , 2021.09.15 , 2021.09.14
Highlights:
New linter: warn on missing gen-class when writing -main function. See docs.
New loop without recur linter. See docs.
Several inference improvements, e.g. (def f (fn [])) (f 1 2) will now give an arity warning.
Return arbitrary metadata in analysis data. See docs.
Babashka
Native, fast starting Clojure interpreter for scripting.
Releases: 0.6.4 , 0.6.3 , 0.6.2 , 0.6.1 , 0.6.0
Highlight:
Support for java.net HTTP Client (via raw Java interop). This enables running java-http-clj from source.
Api-diff
Print API diffs between library versions.
This is a new project.
SCI
Configurable Clojure interpreter suitable for scripting and Clojure DSLs.
0.2.7
Releases: 0.2.7
Highlights:
Loads of JS improvements coming from usage in nbb. Printing in JS targets can now be controlled via *print-fn* like in ClojureScript.
Neil
A CLI to add common aliases and features to deps.edn-based projects.
This is a new project.
Edamame
Configurable EDN/Clojure parser with location metadata
Releases: 0.0.12
Scittle
The Small Clojure Interpreter exposed for usage in browser script tags.
Releases: 0.0.4
Babashka.fs
File system utility library.
Releases: 0.1.0
Highlight: add fs/zip function.
Deps.clj
A faithful port of the clojure CLI bash script to Clojure. Used as native CLI, deps resolver in babashka and getting started REPL in Calva.
Various releases
Graal-build-time
Library to initialize Clojure packages at build time with GraalVM native-image.
This is a new project.
Graal-config
GraalVM native-image configurations distribution for Clojure libraries.
This is a new project.
Jet
Releases: 0.0.16
Highlight: allow keywordize fn to access all available conversion functions from camel-snake-kebab lib. e.g. csk/->PascalCase.
Digest
Digest algorithms (md5, sha1 ...) for Clojure.
I took over this library from Miki Tebeka and I'm maintaining it under clj-commons.
Carve
Carve out the essentials of your Clojure app.
Fixed a regression.


Speeding up builds with fs/modified-since
2021-10-30T23:59:59+00:00
Babashka tasks
When designing babashka tasks I was aiming to create something like make, just, npm run: run tasks with almost no startup time overhead, possibly with dependencies between them, but with a language I like to work with: Clojure. One thing I deliberately left out for now was a mechanism that talks about targets and whether to rebuild those targets or not. Another inspiration for babashka tasks was Mach by JUXT which does have such a mechanism, which leans heavily on one function: (mach.core/modified-since [file dir]).
Babashka.fs
Instead of deciding on a built-in mechanism for rebuilding targets, I included the modified-since function in babashka.fs, which is a library for common file system operations like copying, deleting or moving files, creating symlinks, etc. The babashka.fs library is included in babashka but can also be used as a library within Clojure JVM programs. Now let's see what this function does.
fs/modified-since
Let's first take a look at the docstring:
(modified-since anchor file-set)
Returns seq of regular files (non-directories, non-symlinks) from file-set that were modified since the anchor path.  The anchor path can be a regular file or directory, in which case the recursive max last modified time stamp is used as the timestamp to compare with.  The file-set may be a regular file, directory or collection of files (e.g. returned by glob). Directories are searched recursively.
In other words:
The anchor argument can be a file or directory.
The file-set argument can be a file or directory.
The returned value is a seq of regular files from file-set that were modified since the maximum of all the modified timestamps in anchor.
Let's see it in action.
$ touch a
$ touch b
$ bb -e '(fs/modified-since "a" "b")'
(#object[sun.nio.fs.UnixPath 0x108eff48 "b"])
We see that the file b was modified since a. This is because we touched b after we touched a.
Now let's touch a again:
$ touch a
$ bb -e '(fs/modified-since "a" "b")'
()
In other words, if a was a build target and b was a source file, then we didn't have to rebuild a again since it was already up to date.
What if a doesn't exist? In real scenarios this would probably mean that we have to build a for the first time or that it was deleted, possibly because of clean task. In that case b is returned as well:
$ rm a
$ bb -e '(fs/modified-since "a" "b")'
(#object[sun.nio.fs.UnixPath 0x108eff48 "b"])
When the file-set is a directory, you get all of the files that were modified since anchor:
$ mkdir -p src
$ touch src/a src/b
$ bb -e '(fs/modified-since "a" "src")'
(#object[sun.nio.fs.UnixPath 0x69351174 "src/a"] #object[sun.nio.fs.UnixPath 0x40a401b4 "src/b"])
$ touch a src/a
$ bb -e '(fs/modified-since "a" "src")'
(#object[sun.nio.fs.UnixPath 0x778e11d9 "src/a"])
Real world examples
Today I used this function to speed up the rendering of this blog (which reminded me to blog about this function):
(doseq [{:keys [file title date legacy]} posts]
  (let [cache-file (fs/file ".work" (html-file file))
        markdown-file (fs/file "posts" file)
        stale? (seq (fs/modified-since cache-file markdown-file))
        body (if stale?
               (let [body (markdown->html markdown-file)]
                 (spit cache-file body)
                 body)
               (slurp cache-file))
        ...]
    ...)
...)
Here I used fs/modified-since simply as a predicate to check if the cached HTML output was newer than the markdown input file: if the result is non-empty, we have to rebuild the markdown to HTML and then store it in a .work directory. The rendering of this blog went down from rougly 1 second to 200ms after building it for the first time. There are more places where I could do a similar optimization but for now it's fast enough.
I've already used this function several times in bb.edn tasks file to speed up Clojure builds. Here is an example of not rebuilding a jar file when it's already up to date, without starting a JVM:
  jar {:doc "Build jar"
       :depends [compile-sources]
       :task (if (seq (fs/modified-since bs/jar-file [bs/class-dir]))
               (clojure "-T:build jar")
               (println "Jar is already up to date" bs/jar-file))}
The technique I used there is to make a build_shared.clj file which is loaded both by tools.build and babashka. Before launching a JVM, babashka can check if there's anything to rebuild. If the sources for the jar aren't modified since the jar itself, then we can skip launching a JVM entirely. But also within the build.clj which runs inside of a JVM the same technique can be used.
Here is one more example of how I used fs/modified-since to skip a lein uberjar invocation.
build-server {:doc "Produces lsp server standalone jar"
              :depends [java1.8 update-project-clj -uberjar]
              :task (when (seq (fs/modified-since -uberjar ["server/project.clj"
                                                            "server/src"]))
                      (shell {:dir "server"}
                        "lein with-profiles -user do clean, uberjar"))}
The usage of this function isn't tied to any specific build system or scenario: it's just a comparison of some files with another bunch of files, which makes it generally applicable. This form of optimization does come with a trade-off: e.g. when you forget to take into account changes to deps.edn or so, you might get a false positive 'nothing to do here'. It might be a good idea to put .cpcache in the fileset in a deps.edn project as a sign that the classpath changed. Soon TDEPS-83 will land in the clojure CLI (and soon after that in bb itself via deps.clj) and then even transitive :local/root changes will be picked up in this directory.
Hope you enjoyed this little write-up about fs/modified-since. Thanks again to JUXT Mach where I got the inspiration from.
Happy rebuilding!


Replacing my Octopress blog with 200 lines of Babashka
2021-10-25T23:59:59+00:00
Octopress
Seven years ago I started writing about my adventures with Clojure. I started using Octopress back then and was still using it until today. Octopress worked great for my blogging purposes and I'm grateful that it existed. However, in recent years I became frustrated with the experience of using it, which is probably due to a lack of my familiarity with the Ruby ecosystem. On every new system I had to install a version of Ruby that happened to work with Octopress, which wasn't always the case. When it did work, I started getting deprecation warnings from Ruby while compiling this blog. On top of this, Octopress seemed no longer maintained. The website says "Octopress 3.0 is Coming" but this announcement was from 2015 and the website hasn't been updated ever since. It felt like time to move on.
Requirements for replacement
I started thinking of what was essential for me when writing blog posts and came up with this list of requirements / wishes:
Port the existing blog with as little effort as possible
Writing blog posts in a convenient format: markdown is good enough, let's keep it
Don't use a framework like Octopress again: it isn't worth the learning curve for me
Don't get stuck in a language I don't use every day. The deprecation warnings in Ruby scared me and it was time-consuming to install or update the tooling that I didn't use on a daily basis.
My blog has the following essential components:
Archive page with list of all blog posts written so far
Index page that lists the most recent blog posts
Each post has its own HTML page
An atom.xml feed and a bespoke planetclojure.xml feed for Planet
  Clojure
Highlighting for Clojure code snippets: not super important, but I'd like to at least have this back after a rewrite.
The primary goal of this blog is to share some of my experiences. Of secondary importance:
A way for users to directly react. For now I can live with users reacting via Twitter, Clojurians Slack, etc. and I can figure this out later.
A fancy web design.
The language I am most fluent in is Clojure. Babashka is a scripting tool that has similar startup characteristics as Ruby so it would be nice to keep that from my Octopress experience. Let's see if I can rewrite my blog with a babashka script.
Rewriting in babashka
I started with copying each markdown file in source/_posts and moved them to a directory posts.  In Octopress, blog posts start with a section like:
---
layout: post
title: Figwheel keep Om turning!
date: 2014-09-25 21:00:50 +0200
comments: true
published: true
categories: [clojure, clojurescript, figwheel, om]
---
I removed these sections replaced them with maps in a file called posts.edn:
{:title "Figwheel keep Om turning!"
 :file "figwheel-keep-om-turning.md"
 :date "2014-09-25"
 :categories #{"clojure" "clojurescript" "figwheel" "om"}
 :legacy true}
The maps are top level values so I can easily append new ones programmatically. The :legacy true flag is for blog posts that existed before the rewrite so I can create redirect pages for them. I plan to no longer include the date in the direct blog post URLs, but I don't want to break the web for older blog posts. I might switch back to including this metadata in the blog posts themselves and parse them out, but so far this worked out well.
Then I started writing the render.clj script which iterates over every entry in posts.edn and renders markdown files to HTML.
To do markdown rendering from babashka I'm using bootleg by Crispin Wellington which is available in the pod
registry.
I had to fix a couple of things to get the rendering back that I had with Octopress. Links without markup: https://foobar.com instead of [foobar](https://foobar.com), were rendered as an a element before, but bootleg, which uses markdown-clj doesn't do this out of the box.
Another tweak I had to implement is support line breaks in the middle of markdown link syntax, since emacs's fill-paragraph sometimes causes that to happen:
[foo
bar](https://foobar.com)
The tweaks:
(pods/load-pod 'retrogradeorbit/bootleg "0.1.9")

(require '[pod.retrogradeorbit.bootleg.markdown :as md])

(defn markdown->html [file]
  (let [markdown (slurp file)
        ;; make links without markup clickable
        markdown (str/replace markdown #"http[A-Za-z0-9/:.=#?_-]+([\s])"
                              (fn [[match ws]]
                                (format "[%s](%s)%s"
                                        (str/trim match)
                                        (str/trim match)
                                        ws)))
        ;; allow links with markup over multiple lines
        markdown (str/replace markdown #"\[[^\]]+\n"
                              (fn [match]
                                (str/replace match "\n" "$RET$")))
        html (md/markdown markdown :data :html)
        html (str/replace html "$RET$" "\n")]
    html))
Since this is my personal blog solution, I'm not too worried about these hacks and not being able to use $RET in the text of my blogs. If I were to publish this as a framework or library I would have solved it at the root level, but that wasn't a cost I was ready to pay now. After these workarounds, it was pretty straightforward to support the most essential things my Octopress blog did.
Highlighting
Clojure syntax highlighting works pretty well with highlight.js which I include like this:



After that it just pretty much worked. The Clojure syntax highlighting isn't perfect, but good enough for a blog with the occasional snippet in my opinion.
Feeds
The generation of atom.xml and planetclojure.xml (which only contains Clojure-related posts) were easy to implement with a bit of clojure.data.xml code:
(def blog-root "https://blog.michielborkent.nl/")

(defn atom-feed
  [posts]
  (-> (xml/sexp-as-element
       [::atom/feed
        {:xmlns "http://www.w3.org/2005/Atom"}
        [::atom/title "REPL adventures"]
        [::atom/link {:href (str blog-root "atom.xml") :rel "self"}]
        [::atom/link {:href blog-root}]
        [::atom/updated (rfc-3339-now)]
        [::atom/id blog-root]
        [::atom/author
         [::atom/name "Michiel Borkent"]]
        (for [{:keys [title date file]} posts
              :let [html (str/replace file ".md" ".html")
                    link (str blog-root html)]]
          [::atom/entry
           [::atom/id link]
           [::atom/link link]
           [::atom/title title]
           [::atom/updated (rfc-3339 date)]
           [::atom/content {:type "html"}
            [:-cdata (get @bodies file)]]])])
      xml/indent-str))

(spit (fs/file out-dir "atom.xml") (atom-feed posts))
(spit (fs/file out-dir "planetclojure.xml")
      (atom-feed (filter
                  (fn [post]
                    (some (:categories post) ["clojure" "clojurescript"]))
                  posts)))
This feed validator gave pretty good feedback on what should and should not go into this XML file.
Rake -> bb tasks
Finally I wrote a bb.edn file with babashka
tasks to create new blog posts. E.g. I created this very blog post using:
$ bb new :file migrating-octopress-to-babashka.md :title "Migrating this blog from octopress to babashka"
All implemented tasks so far:
$ bb tasks
The following tasks are available:

new     Create new blog article
render  Render blog
watch   Watch posts and templates and call render on file changes
publish Publish to blog.michielborkent.nl
This replaces the rake stuff I used to have with Octopress.
Conclusion
I'm pretty happy with how far I got with a couple of hours hacking on the babashka scripts and tasks. The meat of the work is in render.clj which is under 170 lines of Clojure. I feel in control over my own blog again. From here on I can look for a plugin which lets users respond to blog posts and perhaps a fancier design. If you have anything useful to share regarding this, please let me know on e.g. Twitter.
The code for this blog is available here.
Aftermath
Since writing this blog post, this blog has undergone some progressions which you can read about here:
I wanted better Clojure highlighting using nextjournal/clojure-mode.
But then I realized that Clojure highlighting isn't that hard can be done using a home-made solution.
Instead of the pod, the blog is now using markdown-clj from source.


Porting a macOS Clojure dev setup to Windows WSL2
2020-07-26T23:59:59+00:00
EDIT 2020-09-16: this post is now also available as a talk. The slides are available here.
In the last few years I've been developing predominantly on Apple MacBooks. Recently I built myself a new PC with a fast processor and lots of memory. I wanted to move some of my development tasks to that machine. I still like the freedom that laptops give me to work from wherever I want. Be it from the couch in my own home or from a random coffee place in the city where I live, I just like to change environment every few hours and not sit behind my desk all day long. I hadn't used Windows as my primary OS for almost 10 years. But since Windows 10 (still) comes with RDP, which is better than VNC in terms of performance, and with WSL2, which offers a "real" and well integrated linux experience, I was curious if I could create a setup for remotely working on the new machine. It also would give me an environment to debug Windows specific problems on, which should come in handy for my side projects like babashka and clj-kondo. If it didn't work out, I could always go dual boot with Ubuntu as the primary dev OS and use VNC if I needed to do anything graphical. For what it is worth, here is a report of setup process I went through.
The pristine smell and beauty of a new PC contrasted with the chaotic reality of my home. pic.twitter.com/3zLIzYg4XB
— (λ. borkdude) (@borkdude) July 8, 2020
 Because I had no other Windows machines in my home, I tried creating a USB Windows installation drive in macOS based on this blog post. No matter what I tried, at the end of the installation process Windows would complain with
Windows installation encountered an unexpected error. Verify that the installation sources are accessible, and restart the installation.
Installing Ubuntu on new PC. The installer is surprisingly smooth, detects my wifi, even nvidia video card apparently. Whereas Windows be like pic.twitter.com/FQNzeJ6V2X
— (λ. borkdude) (@borkdude) July 8, 2020
 A good friend offered help and created an installation drive using Rufus on his Windows Home installation, which did work.
Once Windows was installed, I enabled RDP and installed WSL2, Ubuntu 20.04, Windows Terminal and Docker Desktop for WSL2.
To be able to run WSL2, I had to enable a virtualization option in my BIOS first.
I intend to use Ubuntu WSL2 as my primary dev environment on this machine, so it made sense to tweak the Terminal configuration to open Ubuntu by default, instead of PowerShell. I found it annoying that Ubuntu in Terminal starts in the Windows home directory (/mnt/c/Users/borkdude), so I set "startingDirectory": "//wsl$/Ubuntu-20.04/home/borkdude" in my Ubuntu profile.
I use zsh as my default shell on macOS and wanted that in WSL2 as well so I installed that using sudo apt update && sudo apt install zsh followed by chsh -s $(which zsh). I also installed ohmyzsh and enabled the only two plugins I use on a daily basis: git and jump.
Then I started porting the dev setup I use for work on my MacBook, mainly consisting of Docker images, a couple of Clojure projects, knitted together with some bash scripts. I use a couple of shell scripts to set all my development environment variables and aliases for easily setting up ssh tunnels. These worked after only making a few tweaks (for example, the ethernet card is called differently in macOS and Ubuntu in WSL2). Of course I needed to install git to clone my work projects. To run Clojure projects I installed OpenJDK version 8 and 11 via apt. I use jenv to manage Java versions on a project basis, which worked perfectly:
sudo apt-get install openjdk-8-jdk
jenv add /usr/lib/jvm/java-1.8.0-openjdk-amd64/
Also I installed boot, a Clojure build tool and the Clojure CLI which are all well supported in linux.
Before running my work projects, I wanted to copy over a PostgreSQL database and other data from my MacBook using rsync. Before I could do that, I needed to enable ssh in Ubuntu. I found out I could do this by running sudo service ssh start but I still could not log in from my MacBook. It turns out you also have to forward and open up the port in the Windows Firewall. I found this PowerShell script that lets you do that. As the comment suggests, I also created a scheduled task that runs this script upon Windows login. I did the same thing for running the ssh service using wsl -u root sudo service ssh start. Be sure to select Run using the highest privileges. I'm sure there is a better way to do this via systemd in WSL2, but this works for me. So now I could rsync my the data from macOS to WSL2. I started the Docker containers, the Clojure projects and it worked! We have a fairly I/O intensive process as part of our stack, which seems to perform well in WSL2.
Enabling SSH in WSL also lets me use Emacs from my laptop and edit files on the remote machine using tramp mode. I ran into one issue with this. Since I use a non-standard prompt in zsh, emacs tramp could not parse the output from the remote shell. So I added this hack to my ~/.zshrc:
case "$TERM" in
    "dumb")
        bash
esac
Emacs sets TERM to "dumb" when opening files using tramp. When this is the case, I just invoke bash instead of continuing with zsh. There may be a better solution, but this works.
Of course I also wanted to be able to run Emacs on the machine itself. I first tried to run Emacs in Windows natively, but I read somewhere that editing WSL2 files directly from Windows is not recommended. Also you might run into the line ending differences between Windows and linux/macOS. I decided to play it safe and install emacs inside WSL2 using apt. If you do decide to use the Windows-native Emacs and have trouble finding where emacs expects configuration files, you can find this using M-x describe-variable user-init-file. On my machine that was C:\Users\borkdude\AppData\Roaming\.config\emacs\init.el.. To get a graphical UI for the emacs started from WSL2, I needed to install an X-server on Windows. There are plenty of free and open source solutions to choose from, but I chose to buy X410 on sale for 9.99 instead of 49.99. It seems to be actively worked on and has good documentation. To automatically start X410 on Windows startup I followed these instructions. When started, in the tray there is an X icon where you can modify settings for X410. I have enabled Windowed Apps, Allow Public Access, DPI Scaling (High Quality) and Shared Clipboard. To export the right DISPLAY value for GUI applications in WSL2 I have this in my .zshenv:
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0
and then run emacs using setsid emacs from a zsh session (I created an alias for this in my .zshenv).
I'm using the exact same emacs config I use on macOS, which is based on @bbatsov's prelude. It looks and feels the same as on macOS, although now I probably have to learn the "real" emacs keybindings for copying (M-w) and pasting (C-y) instead of using the macOS keybindings, which may be in fact a nice side effect of this experiment.
Even connecting to an nREPL server with cider-connect works seemlessly from my laptop, provided that I forward and open up the port in Windows Firewall like described above.
Some closing tips.
There is a known issue with memory usage of WSL2. Since linux uses non-allocated memory for filesystem caching, Windows thinks this memory is really used. As time goes by, Windows could end up allocating all your system's memory to WSL2. To put a limit to this, I use this config in C:\Users\borkdude\.wslconfig:
[wsl2]

memory=92GB
My PC has a whopping 128GB of memory so this still leaves 36GB of memory to Windows.
As I will mainly use this PC for work, I turn it off at night and during the weekends. To get back where I left, without restarting all my development processes from scratch, I use the Hibernate setting.
I use Tailscale to set up a VPN between my laptop and Windows machine so I can connect through RDP, emacs tramp and/or nREPL when I go outside of my home.
For RDP I use Microsoft Remote Desktop.app. Since I have a Retina screen, I enabled the "optimize for Retina displays" setting which gives a better resolution.
As a bonus I can re-use some licenses I already owned for apps I am using on macOS: Beyond Compare and Acronis True Image.
I'm pleasantly surprised with WSL2, the Terminal app and Docker integration. I've only been using this setup for week but so far so good.
Pretty good startup time of #babashka in WSL2 on Windows on new machine (Ryzen 3950X): 4ms on average@graalvm pic.twitter.com/TKPPoeFZlL
— (λ. borkdude) (@borkdude) July 10, 2020
 


Clj-kondo hooks
2020-06-21T23:59:59+00:00
Clj-kondo is a Clojure linter that uses static analysis. This means it only looks at source code, but does not execute it. While the information available to produce good lint warnings is more limited with static analysis, static analyzing is generally more performant, and works independently from a runtime (JVM, nodeJS, browser, etc.). Static analysis does not suffer from causing unwanted side effects when executing code. It often yields good enough results. Where static analysis falls short, clj-kondo offers configuration options where the user can help clj-kondo understand more of their code.
One area where static analysis of Clojure code becomes hard is macros. Macros can introduce new syntactical constructs. Often macros are syntactically similar to existing Clojure core macros. This is where you can use clj-kondo's :lint-as configuration. In places where this isn't possible, for example because the macro had irregular binding patterns, one could use :unresolved-symbol + :exclude which would simply ignore unresolved symbol errors in an entire s-expression.
I've been asking myself the following question for a while now: can clj-kondo make more sense of custom macros with a little help from the user? Clj-kondo could invent some DSL to express a transformation, but DSLs often cover just 80% of what you want to achieve. To get 20% more power, you'd have to turn the DSL into something like Clojure itself. So why not just use Clojure directly?
Clj-kondo is distributed in a couple of different ways. A widely used distribution is the binary compiled with GraalVM. One limitation of a GraalVM-compiled binary is that one cannot introduce new classes at runtime. And this is what clojure.core/eval does, so that's off the table. Since August 2019 I've been working on the Small Clojure
Interpreter. It's not a compiler, like Clojure, but it allows you to interpret Clojure expressions within a GraalVM binary. The interpreter is used in babashka but it has other uses as well and also works in JavaScript.
This interpreter can be used in clj-kondo to execute hooks that users can provide to transform custom macro calls into constructs that clj-kondo can understand. And this is what I've worked on.
Clj-kondo uses a vendored version of rewrite-clj to analyze source code. My first attempt at the hooks API was to transform the rewrite-clj nodes into Clojure s-expressions. Then the user's hook function would transform these s-expressions in a similar fashion as the macro would, returning new s-expressions. Lastly clj-kondo would then translate these s-expressions back into rewrite-clj nodes and continue analysis. Ostensibly this worked great for several test cases, but ultimately it wasn't good enough. The main problem is that numbers, strings and keywords cannot carry metadata. Metadata on sexprs was used to keep track of the original locations. When (some of) these locations are lost, clj-kondo cannot accurately position lint warnings anymore. And this is unacceptable in my opinion. You can read more about this problem on ClojureVerse here and in the issue on Github here.
After more experimentation I decided that the transformation should happen direcly on rewrite-clj nodes in order to preserve location information. This led to the current implementation of the :analyze-call hook, documented here. Additionally, some library specific example config + hook code is provided here, showing how to make clj-kondo understand Rum's defc macro and slingshot's try+ macro.
I consider this new feature a powerful feature but not an easy to use one. It does provide a higher degree of linting quality while still enjoying the benefits of static analysis. Luckily we only have to figure out the right code for each library once. I urge library authors and users to contribute their configurations to the clj-kondo repository so we can all benefit.
Clojurist Together has sponsored this work as part of their Summer of
Bugs program. Thanks to the people who have made this possible: the Clojurists Together staff and of course the people who donate.
Hope you enjoy. Happy linting!
Michiel Borkent (a.k.a. @borkdude)


Transducing a text file
2018-01-17T23:59:59+00:00
This post highlights of one of the core ideas posted in this
blogpost. If you've already read it and you're intimately familiar with transducers, this post probably won't have anything new for you. I've posted this to Stackoverflow before and saving this to my blog for archival purposes.
In the pre-transducer era, reading text files was often done like this:
(require '[clojure.java.io :as io])
(with-open [rdr (io/reader "/tmp/work.txt")]
  (->> (line-seq rdr)
       (mapcat #(str/split % #";"))
       (map count)
       (doall)))
Given input work.txt:
I;am;a;string
Next;line;please
this would return (1 2 1 6 4 4 6). One caveat with this approach is you have to realize the result inside the with-open macro, else the file would already be closed.
What if we want to use transducers instead of lazy collection transformations? The ingredient you need is something that allows you to treat the lines as a reducible collection and which closes the reader when you're done reducing:
    (defn lines-reducible
      [^java.io.BufferedReader rdr]
      (reify clojure.lang.IReduceInit
        (reduce [this f init]
          (try
            (loop [state init]
              (if (reduced? state)
                @state
                (if-let [line (.readLine rdr)]
                  (recur (f state line))
                  state)))
            (finally
              (.close rdr))))))
Count the length of each 'split'
    (require '[clojure.string :as str])
    (require '[clojure.java.io :as io])

    (into []
          (comp
           (mapcat #(str/split % #";"))
           (map count))
          (lines-reducible (io/reader "/tmp/work.txt")))
    ;;=> [1 2 1 6 4 4 6]
Sum the length of all 'splits'
    (transduce
     (comp
      (mapcat #(str/split % #";"))
      (map count))
     +
     (lines-reducible (io/reader "/tmp/work.txt")))
    ;;=> 24
Sum the length of all words until we find a word that is longer than 5
    (transduce
     (comp
      (mapcat #(str/split % #";"))
      (map count))
     (fn
       ([] 0)
       ([sum] sum)
       ([sum l]
        (if (> l 5)
          (reduced sum)
          (+ sum l))))
     (lines-reducible (io/reader "/tmp/work.txt")))
or with take-while:
    (transduce
     (comp
      (mapcat #(str/split % #";"))
      (map count)
      (take-while #(> 5 %)))
     +
     (lines-reducible (io/reader "/tmp/work.txt")))
Read https://www.grammarly.com/blog/engineering/building-etl-pipelines-with-clojure-and-transducers/ for more details.


Parsing a circuit with clojure.spec
2017-10-10T23:59:59+00:00
Advent of Code is a collection of self-contained programming problems, one for each day during Advent. My favorite problem of 2015's edition was Day 7: Some Assembly
Required.  You can read the full description on the site. I'll explain it briefly. A circuit looks like this:
123 -> x
456 -> y
x AND y -> d
x OR y -> e
x LSHIFT 2 -> f
y RSHIFT 2 -> g
NOT x -> h
NOT y -> i
On the left you have one or more inputs combined by a logical gate which is then wired to the output on the right.
If you run this circuit, it will produce the following state:
d: 72
e: 507
f: 492
g: 114
h: 65412
i: 65079
x: 123
y: 456
The problem can be subdivided into parsing and processing. When I solved this problem in 2015 I used good old string/split and regexes. But it can also be solved quite elegantly with clojure.spec as we shall see.
I'll walk you through the circuit spec in reverse.
An expression is the left hand side followed by the symbol -> followed by the right hand side.
(s/def ::expr (s/cat :lhs ::lhs :arrow #{'->} :rhs ::rhs))
The right hand side is always a variable name.
(s/def ::rhs ::varname)
The left hand side is a little bit more involved. It is either a simple value (a variable name or concrete value: x, 456, 1337, ac), a binary expression (x AND y) or something which is negated (NOT x).
(s/def ::lhs (s/alt :simple-value ::val
                    :binary-expression
                    ::binary-expression
                    :not ::not))
A negated expression is the symbol NOT followed by a value.
(s/def ::not (s/cat :not #{'NOT} :operand ::val))
A binary expression is a value followed by an operator followed by another value.
(s/def ::binary-expression (s/cat
                            :left-operand ::val
                            :operator ::binary-operator
                            :right-operand ::val))
A binary operator is one of the symbols in the set.
(s/def ::binary-operator #{'LSHIFT 'RSHIFT 'AND 'OR})
A value is either a variable name or a non-negative integer.
(s/def ::val (s/alt :name ::varname
                    :value nat-int?))
Lastly, a variable name is a symbol. I could have specified this in more detail by restricting the allowed characters and the length of the symbol, but this was not needed to succesfully parse my input.
(s/def ::varname
  (s/with-gen symbol?
    (fn [] varname-gen)))
However, to generate a variable name which looks like my input, for the sake of playing around with spec, I need to provide my own generator. Scanning through my input, I discovered that a variable name's length is either 1 or 2 and only alphabetic characters may be used.
(def varname-gen
  (gen/fmap (fn [chars]
              (symbol
               (str/lower-case
                (apply str chars))))
            (gen/vector (gen/char-alpha)
                        1
                        2)))
Running the generator yields for example:
(gen/sample varname-gen) ;;=> (g dv de pw hi a c j bz y)
We can now generate entire expressions:
(gen/sample (s/gen ::expr)) ;;=> ((NOT g -> sw) (NOT 0 -> j) (gl LSHIFT 0 -> q) (NOT 1 -> ly) (NOT 2 -> j) (ug -> o) (p RSHIFT 0 -> p) (NOT oj -> dz) (ih -> m) (NOT 5 -> fc))
Looks good.
To read the lines from the input file I cheated a little bit by using edn/read-string which parses raw strings to a vector of symbols and numbers for me:
(defn get-lines []
  (str/split-lines
   (slurp "input-day7.txt")))

(defn parsed-lines [lines]
  (mapv (fn [l]
          (let [edn (edn/read-string
                     (format "[%s]" l))]
            (s/conform ::expr edn)))
        lines))
I could have used line-seq or a text transducer to save some memory, but as Knuth says, if you optimize everything you will always be unhappy.
Let's peek at the first conformed expression which corresponds to the line bn RSHIFT 2 -> bo :
(first (parsed-lines (get-lines))) ;;=> {:lhs [:binary-expression {:left-operand [:name bn], :operator RSHIFT, :right-operand [:value 2]}], :arrow ->, :rhs bo}
Yay! Now we have to write some code that processes these lines and calculates the values for each variable. To do this, we are going to build up a map of symbols to their values:
(def context (atom {}))
The right hand side of an expression is always a variable name. So we assoc it to the context where the value is a delay of the evaluation of the left hand side.
(defn evaluate-expr! [expr]
  (let [rhs (:rhs expr)
        lhs (:lhs expr)]
    (swap! context assoc rhs
           (delay
            (evaluate* lhs)))))
The reason we are using a delay for the values of the context map, is twofold: delaying and caching.  Firstly, not all values that the variable depends on are already added to the context, so we have to delay calculation until every expression has been processed. Secondly, once a value of a variable is known, we do not want to recalculate it. My circuit file is 339 lines long and without caching this becomes terribly slow.
The API we need to get the solution for our Advent of Code puzzle is a function from symbol to integer.
(defn value-by-symbol [sym]
  @(get @context sym))
The double deref is needed because we're dealing with an atom and a delay.
The last bit we need to is evaluate the left hand side of an expression. Here we pattern match on the kind of expression and evaluate accordingly!
(defn evaluate* [[kind tree-or-val]]
  (case kind
    :value tree-or-val
    :name (value-by-symbol tree-or-val)
    :simple-value (evaluate* tree-or-val)
    :not (bit-not
          (evaluate*
           (:operand tree-or-val)))
    :binary-expression
    (let [l (evaluate* (:left-operand tree-or-val))
          r (evaluate* (:right-operand tree-or-val))
          operator (case (:operator tree-or-val)
                     AND bit-and
                     OR bit-or
                     LSHIFT bit-shift-left
                     RSHIFT bit-shift-right)]
      (operator l r))))
Finally, after evaluating all the lines we can ask for the value of a symbol in the circuit.
(value-by-symbol 'a) ;;=> 46065
which happened to be the correct value for my input!
Thanks for reading. The full code is available on Github. Constructive feedback and criticisms are welcome.


Inline def: an effective* debugging technique for Clojure
2017-05-25T23:59:59+00:00
Clojure beginners often hear that inline def is bad style. For code you commit that's mostly true. Example:
(defn foo [x]
  (def y (+ x 1))
  y)
Here def performs a side effect every time you call foo, by (re)defining a Var y which is global to the current namespace. Instead you should use let to make it a local:
(defn foo [x]
  (let [y (+ x 1)]
    y))
However, inline defs can serve a useful purpose, namely that of a simple debugger. Debuggers for Clojure exist, e.g. in CIDER, but I mostly forget to use them. After println, inline def is my debugging tool of choice.
Example:
(defn foo [& [{:keys [a b c] :as m}]]
  (+ a b c))
How should I call this function? Of course.
(foo :a 1 :b 2 :c 3)
;; => java.lang.NullPointerException
Wait, what? Inline def to the rescue.
(defn foo [& [{:keys [a b c] :as m}]]
  (def m m) ;; TODO: remove this line before commit
  (+ a b c))
  
(foo :a 1 :b 2 :c 3)
;; => java.lang.NullPointerException
m ;;=> :a
Oh, of course! What happened is that m was bound to the first argument. I get it, I should have called foo like this:
(foo {:a 1 :b 2 :c 3}) ;;=> 6
Time to remove the inline def and get on with life.
I regularly use this technique to capture input that is part of some processing chain and I'm not sure what data is flowing through, or when the input is hard to simulate from the REPL, e.g. coming form a large HTTP request body. Recently I was working on some XML parsing. For every XML file this function was called:
(defn process-xml [xml-as-str]
  (def xml-as-str xml-as-str) ;; TODO: remove this line before commit
  ;; processing
  )
That function was part of larger flow that reads from a directory of zipfiles containing XML files. After processing a few files I would get an exception. Let's inspect xml-as-str, the last input that triggered the exception.
xml-as-str ;;=> ""
So the last entry from the zipfile was empty. Turns out the entry was not an XML file, but a directory represented by an empty string. Another example involved some XML file that didn't have the format I expected. Every time I got a new exception I could quickly see what was going on and retry process-xml with xml-as-str without kicking off the flow from scratch.
(process-xml xml-as-str) ;;=> ok, now it works!
Next time you have the urge to reach for a debugger, you might want to become friends with inline def first.
Creating temporary vars with the same name as function arguments has the added benefit of being able to evaluate expressions within your function. This is discussed the blogpost REPL Debugging: no stacktrace required by Stuart Halloway.
*) And somewhat controversial


One off experiments with Clojure and ClojureScript libraries
2016-10-19T23:59:59+00:00
Did you ever need to know the date and time 30 hours from now, because that is the time you could check into your plane to EuroClojure 2016 (and you're too lazy to do this in your head)? Or maybe you just saw an interesting Clojure library on Twitter or Reddit that you wanted to try out?  How convenient would it be if you didn't have to create a project for such one off experiments.
There are several good options in Clojure for this. In this post let's assume we were going to try out clj-time, an excellent date and time library based on Joda Time. We'll show how to make a script that gives you almost instantaneous access to this library from the command line using Boot. And then we'll make it even faster using Planck.
Leiningen
For Leiningen, there is lein try. This is a plugin you can install into ~/.lein/profiles.clj. Then from the command line, just type lein try clj-time and we're good to go:
user=> (require '[clj-time.core :as t])
nil
user=> (require '[clj-time.local :as l])
nil
user=> (t/plus (l/local-now) (t/hours 30))
#object[org.joda.time.DateTime 0x3b3c5f5f "2016-10-25T16:53:58.154+02:00"]
Boot
For Boot this story seems even simpler as there is no need to install a plugin. Boot supports an option for including dependencies from the command line. Just type boot -d clj-time repl to get a REPL with the latest clj-time as a dependency:
$ boot -d clj-time repl
;;; output omitted
boot.user=> (require '[clj-time.core :as t])
;;; etc.
Note that Boot's repl task also supports the --eval option (-e for short), so we can already put the require on the command line:
$ boot -d clj-time repl -e "(require '[clj-time.core :as t]))"
Clojure 1.8.0
;;; output omitted
boot.user=> (t/plus (l/local-now) (t/hours 30))
#object[org.joda.time.DateTime 0x3489e3ab "2016-10-25T17:11:18.560+02:00"
```

How convenient this is. This allows us to write it as a script:

``` bash
#!/usr/bin/env bash

echo "Example: (t/plus (l/local-now) (t/hours 30))"
boot -d clj-time repl -e "(do (require '[clj-time.core :as t]) (require '[clj-time.local :as l]))"
Great to have handy for EuroClojure 2017!
Note that Boot allows us to load dependencies dynamically. Suppose you're experimenting but need another library. No need to restart the REPL. You can just type:
boot.user=> (set-env! :dependencies '[[org.clojure/core.async "RELEASE"]])
;;; output omitted
boot.user=> (require '[clojure.core.async :refer [go-loop]])
;;; continue experimenting
Plank
Wouldn't it be great if we could also experiment with ClojureScript libraries from a REPL? For example cljs-time? The easiest way to get here is Planck, which as of now runs only on OS X.
Planck can use jar files from ~/.m2, but you have to specify the full classpath. This is easily done with the help of Boot:
$ boot --dependencies org.clojars.micha/boot-cp            # load with-cp task that helps exporting minimal classpath to file
       --dependencies com.andrewmcveigh/cljs-time:"0.4.0"  # load dependency you actually want to try
       with-cp -w --file .classpath                        # write classpath to a file `.classpath`
The list of dependencies is now written to .classpath. You can re-use this file if your dependency hasn't changed.
Now we're ready to start the Planck REPL. It's fast! Even faster when you use the K option which caches compiled ClojureScript.
$ planck -Kc `cat .classpath` -e "(require '[cljs-time.core :as t])" -r
cljs.user=> (require '[cljs-time.local :as l])
cljs.user=> (str (-> (t/plus (t/now) (t/hours 30)) (t/to-default-time-zone)))
"20161025T220847"
Final thoughts
Typing directly in a REPL only goes so far. For larger expressions it is more convenient to write in a text editor and then send the code to the REPL. For experiments started with Leiningen or Boot you can use an nREPL client. I use CIDER. For Planck you can use inf-clojure.
That's it. I hope this also helpful to beginners. Performing little Clojure experiments can grow into an addiction. Before you know it, you're soaked into your first Clojure project.


Using the Clojure REPL with Java or Scala
2016-07-26T23:59:59+00:00
Clojure is a tool that enables interactive development and runtime inspection. Even when we work in other programming languages, Clojure can still be useful. Especially when that other language lives on the JVM.
Let's take Scala for example. Scala has a REPL. The REPL can be used to test-drive software in development. But it doesn't really let you inspect a running program when you didn't start it with sbt console. So let's use Clojure for that. We will walk through a simple Scala program that allows runtime inspection of an otherwise unknown state.
We'll need an sbt project for this example. Make a directory and put a build.sbt in it. The only dependency in this example is Clojure.
scalaVersion := "2.11.8"

libraryDependencies ++= Seq(
  "org.clojure" % "clojure" % "1.8.0"
)
In src/main/scala/example.scala we add the following imports:
import clojure.java.api.Clojure
import clojure.java.api.Clojure.{`var` => cvar}
We'll be using Clojure's Java API.  In Scala var is a reserved keyword, so I'm renaming it to cvar, since I don't like the backticks in my code.
Next, let's create an object that will contain some random value:
object BusinessLogic {
  val x = Math.random() // I wonder what this value is at runtime... 
}
Also, let's create an App so we can run our program with sbt run:
object Main extends App {
}
If we would execute sbt run, we would never know the value of x in BusinessLogic. We could add a println, but what if x was a var and it's value would change over time? Clojure lets us inspect this value at any given point in time. We'll start a socket server that is available since Clojure 1.8.0.
object Main extends App {
  val require = cvar("clojure.core","require")
  require.invoke(Clojure.read("clojure.core.server"))
  val startServer = cvar("clojure.core.server","start-server")
  val options = Clojure.read("""{:port 4555 :accept clojure.core.server/repl 
    :name repl :server-daemon false}""")
  startServer.invoke(options)
}
This may seem a little intimidating, so I'll explain it line by line. On line 2 we get a reference to Clojure's require so we can... yes, require namespaces.  On line 3 we read a string so we get the symbol that require needs to load the clojure.core.server namespace.  On line 4 we get a reference to the start-server var. On line 5 we define a bunch of settings. Their meaning can be found here.
In Clojure this would read as:
(require 'clojure.core.server)
(clojure.core.server/start-server 
  {:port 4555
   :accept clojure.core.server/repl
   :name 'repl
   :server-daemon false})
but since we're coming from Scala and have to use Clojure's Java API, it looks a bit more involved.
On the last line we invoke start-server with said options. When we execute sbt run again, the process will block, because :server-daemon was set to false:
~/dev/scala/cljrepl $ sbt run
[info] Loading global plugins from /Users/Borkdude/.sbt/0.13/plugins
[info] Set current project to cljrepl (in build file:/Users/Borkdude/Dropbox/dev/scala/cljrepl/)
[info] Compiling 1 Scala source to /Users/Borkdude/Dropbox/dev/scala/cljrepl/target/scala-2.11/classes...
[info] Running Main
This gives us the chance to connect to the socket repl with good ol' telnet:
~ $ rlwrap telnet localhost 4555
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
user=> (import 'BusinessLogic)
BusinessLogic
user=> (BusinessLogic/x)
0.722431948099764 ;; <-- aah! 
user=> :repl/quit
Connection closed by foreign host.
See what we did there?
Clojure's socket REPL also supports initialization via a JVM property. To try this, add these lines to build.sbt:
fork := true
javaOptions := Seq("-Dclojure.server.repl={:port 4555 :accept clojure.core.server/repl :server-daemon false}")
The App can now be reduced to something like:
object Main extends App {
  val require = cvar("clojure.core","require")
}
This doesn't do much except taking care that Clojure is initialized (for more info, read the last paragraph in this Stackoverflow answer).
This Scala example translates fairly straightforward to Java. Now don't tell your boss you're using a different programming language. After all, Clojure is just a Java library that gives you superpowers :-).
PS: it may be wise to turn this off in production because of the security risk; on the other hand, a Clojure REPL has saved my day more than once in the past!


Migrating a Leiningen project to boot
2015-06-06T23:59:59+00:00
Edit: this post made it to the front page of Hacker News. Thanks!
Boot is a new build tool for Clojure. To get acquainted with it, I decided to migrate a fairly non-trivial Leiningen project to Boot.
You can find the entire project including the Leiningen project.clj file and Boot's build.boot file here.
Disclaimer: this is not a comprehensive Boot tutorial. For a detailed introduction to the concepts of Boot I refer to the Boot website.
Requirements
I wanted my Boot project to have the same features as my Leiningen project:
Managing dependencies
Setting source and resource paths
Building ClojureScript
Automatic reloading of Clojure and ClojureScript source code during development
A Clojure and ClojureScript REPL
Setting the initial namespace for a REPL
Setting a global var like *print-length*
Packaging the project as a standalone jar that runs in an embedded server
Walkthrough
First let's walk through the Leiningen project.clj step by step and see how it translated into a build.boot file.
Paths
Here we tell Leiningen where our source files and resources are. Also we declare what directories must be emptied if we want to clean up generated files:
:source-paths ["src"]
:resource-paths ["assets" "out"]
:clean-targets ^{:protect false} [:target-path :compile-path "out/public/out"]
In the build.boot file this is done by a call to set-env!:
(set-env!
  :source-paths #{"src" "src-cljs"}
  :resource-paths #{"assets"}
  ,,,)
Boot has the concept of immutable filesets. Each task receives a fileset and produces one.  The last task outputs its fileset to a target directory, which is target by default. Boot will clean stale files from target automatically before it emits a new fileset there. There is never a need to clean something in Boot.
Dependencies
Next we describe which dependencies the project has. In Leiningen this is done as follows:
:dependencies [[org.clojure/clojure "1.6.0"]
               [org.clojure/clojurescript "0.0-3211"]
               [org.clojure/core.async "0.1.346.0-17112a-alpha"]
               [ring-server "0.4.0"]
               [org.webjars/bootstrap "3.2.0"]
               [cljs-http "0.1.30"]
               [compojure "1.3.4"]
               [liberator "0.13"]
               [fogus/ring-edn "0.2.0"]
               [clj-json "0.5.3"]
               [reagent "0.5.0"]
               [prismatic/schema "0.4.3"]]
In Boot this is done similarly, still inside the call to set-env!:
(set-env!
    ,,,
    :dependencies '[[org.clojure/clojure "1.6.0"]
                    [org.clojure/clojurescript "0.0-3211"]
                    [org.clojure/core.async "0.1.346.0-17112a-alpha"]
                    [ring-server "0.4.0"]
                    [org.webjars/bootstrap "3.2.0"]
                    [cljs-http "0.1.30"]
                    [compojure "1.3.4"]
                    [liberator "0.13"]
                    [fogus/ring-edn "0.2.0"]
                    [clj-json "0.5.3"]
                    [reagent "0.5.0"]
                    [prismatic/schema "0.4.3"]
                    ,,,
                    ])
Initial REPL namespace
The next line we encounter in project.clj is:
:repl-options {:init-ns animals.server}
This makes the animals.server namespace the starting point for every REPL session. In build.boot it is accomplished like this:
(task-options! repl {:init-ns 'animals.server})
Boot has several tasks built in and repl is one of them. It supports the option init-ns. With task-options! you can set some default options per task that are global to the project. To see all the options that repl provides, you can issue -h from the command line:
$ boot repl -h
or call (doc repl) from a Boot REPL session.
Global var setting
Next is this line from project.clj:
:global-vars {*print-length* 20}
This sets the var clojure.core/*print-length* to 20. If we print collections we'll never see more than 20 items:
user=> (println (range))
(0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 ,,,)
nil
In Boot I attempted to do it like this:
(alter-var-root (var *print-length*) (fn [v] 20))
Unfortunately this caused a bug in Boot's jar task. Later I learned that it's not a good idea at all to do this in Boot, because there can be multiple Clojure runtimes (pods) in one JVM. Since I was going to use this setting only in the REPL, this is a better solution:
(task-options!
 repl {:init-ns 'animals.server
       :eval '(set! *print-length* 20)})
Task dependencies
Leiningen has the concept of plugins. Plugins typically perform a task as part of a Leiningen build. Two popular plugins are lein cljsbuild and lein figwheel. lein cljsbuild is an interface to the ClojureScript compiler. lein Figwheel lets you push resources to a browser, typically freshly compiled ClojureScript or CSS. It also gives you a ClojureScript REPL and a web server which allows you to serve some static files or even a Ring handler. In this example I don't use Figwheel's web server for running my Ring handler, because I use Ring's standalone Jetty server that comes with automatic code reloading middleware and allows for an initial function to be executed before the handler is started: features that are lacking from Figwheel as far as I know.
In Leiningen plugins are included like this:
:plugins [[lein-cljsbuild "1.0.5"]
          [lein-figwheel "0.3.1"]]
In Boot tasks are included as normal dependencies and scoped with :test:
(set-env!
  ,,,
  :dependencies '[[adzerk/boot-cljs "0.0-3269-2" :scope "test"]
                  [adzerk/boot-cljs-repl "0.1.9" :scope "test"]
                  [adzerk/boot-reload "0.2.6" :scope "test"]
                  [pandeiro/boot-http "0.6.3-SNAPSHOT" :scope "test"]])
The first dependency is Boot's interface to the ClojureScript compiler. The latter three dependencies together offer more or less the same as Figwheel: a ClojureScript, live reloading of resources in the browser and a web server to serve static files or a Ring handler.
Building ClojureScript
In Leiningen ClojureScript is built using the lein cljsbuild plugin. My configuration for this plugin looks as follows:
:cljsbuild {:builds {:dev {:source-paths ["src-cljs" "src-cljs-dev"]
                           :figwheel {:on-jsload "animals.main/fig-reload"}
                           :compiler {:output-to "out/public/main.js"
                                       :output-dir "out/public/out"
                                       :optimizations :none
                                       :asset-path "out"
                                       :main "animals.main"
                                       :source-map true}}
                     :prod {:source-paths ["src-cljs" "src-cljs-prod"]
                              :compiler {:output-to "out/public/main.js"
                                         :optimizations :advanced}}}}
In Boot configuring the location of where generated JavaScript will end up is done by placing an .edn file at the corresponding location in the resources tree. In this project I placed it in resources/public and named it main.cljs.edn with the following content:
{:require [animals.main]
 :compiler-options {:asset-path "out"}}
This gives you the same config as in the Leiningen example with respect to the name of the main JavaScript file, :asset-path and the :main namespace.
I use different source folders for development and production, so I can have some environment specific configuration. For example, in development I enable console print and define a function for Figwheel that will be executed when new ClojureScript is pushed to the browser:
(enable-console-print!)

(defonce init
  (do (println "starting application") 
      (reagent/render [crud/animals]
                      (js/document.getElementById "app"))))

(defn fig-reload []
  (println "reloading reagent")
  (reagent/render [crud/animals]
                  (js/document.getElementById "app")))
In my production ClojureScript I set *print-fn* to identity, because else I would get errors when there was still a println around in my code:
;; no println output in production code
(set! cljs.core/*print-fn* identity)

(reagent/render [crud/animals]
                (js/document.getElementById "app"))
Developing
In Leiningen I would start my development like this.
In one terminal, I would start the web server:
lein repl
(start-server)
In another terminal, I would start Figwheel:
lein clean && lein figwheel dev
Figwheel invokes the ClojureScript compiler and the ClojureScript compiler outputs JavaScript to the out directory.
Note that using this setup, I need to run two JVMs.
In Boot the development flow is one task composed of multiple tasks:
(deftask dev []
  (set-env!
   :source-paths #(conj % "src-cljs-dev"))
  (comp
   (serve :handler 'animals.api/handler
          :reload true
          :init 'animals.api/init)
   (watch)
   (reload :on-jsload 'animals.main/fig-reload)
   (cljs-repl)
   (cljs)))
Only one JVM needed!
There is no need to worry about cleaning directies, since each task outputs an immutable fileset that the next task can use. Generated files end up in target by default, which gets cleaned before a new fileset is committed there.
The serve task will be the first one to be invoked. By default serve runs a Jetty server, but it is possible to select http-kit. It will reload Clojure files automatically, is able to run a Ring handler and also executes an initial function before the handler is started.
The next task in our Boot pipeline is watch. This task waits for file changes in any of the source or resource paths and then invokes the rest of the pipeline. The rest of the pipeline is also invoked one time for the initial fileset. An example:
(deftask watch-example []
  (comp
    (watch)
    (show :fileset true)))
In this example show prints out the fileset that it received as a tree. When we invoke it we see the initial fileset tree. When we add a file, the watch task will invoke show again and we would see the new fileset tree with the added file.
Back to our development pipeline:
(deftask dev []
  (set-env!
   :source-paths #(conj % "src-cljs-dev"))
  (comp
   (serve :handler 'animals.api/handler
          :reload true
          :init 'animals.api/init)
   (watch)
   (reload :on-jsload 'animals.main/fig-reload)
   (cljs-repl)
   (cljs)))
Whenever a file changes, the reload task is invoked. This will send changed assets to the browser via a websocket connection. The task after that, cljs-repl starts an nrepl server in which it is possible to start a ClojureScript REPL. This task also covers our requirement to have a normal Clojure REPL session with our program. Finally, the cljs task compile ClojureScript to JavaScript. I am not sure if it matters if cljs-repl comes before or after watch, but cljs surely has to come after it, since it has to see new filesets for incremental compilation.
Standalone jar
The final requirement is producing a standalone jar. In Leiningen this is done with the uberjar task. We need to tell Leiningen where it can find the main namespace that will have the -main function that will be invoked when the jar is run. Also we need to aot that namespace:
:aot [animals.uberjar]
:main animals.uberjar
Before producing a standalone jar, we must invoke the ClojureScript compiler to produce production worthy JavaScript. For convenience we can make an alias that combines all these steps:
:aliases {"build" ["do" "clean" ["cljsbuild" "once" "prod"] "uberjar"]}
Note that uberjar will invoke clean also. One problem that arose while writing this blog was that I had the entire out directory in :clean-targets, so when cljsbuild was done, uberjar would remove its output again. You will never have this kind of problem with Boot.
In Boot our build task looks like this:
(deftask build-cljs []
  (set-env!
   :source-paths #(conj % "src-cljs-prod"))
  (cljs :optimizations :advanced))

(deftask build []
  (comp
   (build-cljs)
   (aot :namespace '#{animals.uberjar})
   (pom :project 'animals
        :version "1.0.0")
   (uber)
   (jar :main 'animals.uberjar)))
First we invoke the sub-task build-cljs which includes sources from src-cljs-prod and produces optimized JavaScript. The next task performs aot on the main namespace. Then a pom file is produced. The uber task adds jar entries from dependencies to the fileset. Finally, the jar task produces a jar file from the fileset with the main namespace set to animals.uberjar. I love how Boot decomposes these tasks, so you can actually see what is going on when you produce a standalone artifact.
Issues
During this blog post I ran into a couple of issues with Boot.
The first issue had to do with dependency resolution and Clojure versions. This issue has been solved. Thanks Alan Dipert!
Another issue was that the reload task didn't have the concept of an asset-path. I needed to work around this by creating an extra route in my handler:
(defroutes routes
  ,,,
  (resources "/")
  (resources "/public") ;; extra route
  ,,,)
This problem will be solved in a future version of reload. See this issue.
Conclusion
Leiningen is a battle tested tool and probably the safest bet if you're just starting with Clojure. However, Boot has certainly sparked my interest. It has an elegant design and a more functional feel to it. I'll certainly use it on a future project.
Here are my recommendations based on my brief experience with Boot.
Use Leiningen if you:
want to get started fast and like to get help from the majority of the Clojure community
don't want to take risks in terms of stability
like configuration and convenience over programmability and composition
Use Boot if you:
like programs more than configuration files
don't like to think about cleaning directories
need to run one JVM for the entire development process (in Leiningen I needed two: one for Clojure and one for ClojureScript)
need to perform builds tasks with mutually exclusive dependencies
Thanks for reading my blogpost. Feedback is appreciated. Did I misunderstand something about Boot? Please let me know!
Credits
Thanks to Alan Dipert, Martin Klepsch, Earl S. Sauver and some other fine folks in the #boot channel on Slack.


My ClojureScript adventure at Øredev
2014-11-16T23:59:59+00:00
tl;dr
November 6th 2014 I was given the chance to speak about ClojureScript and React at the Swedish developer conference Øredev. You will find the videos and slides of my talks below. The talk about ClojureScript and React seems to be more popular and it has better sound quality, so you may want to skip straight to that one.
How I got there
On October 7th I received an e-mail from the organization of Øredev. One of their speakers, Anna Pawlicka, who was going to speak about ClojureScript had cancelled (for urgent private reasons). She had passed them some names of people they could ask to replace her. Apparently I was on this list and received an e-mail. After some consideration I accepted this invitation. It would be my first appearance on a bigger (> 1000 participants) developer conference. So in the month leading up to this conference I was pretty nervous and excited. Luckily I could practice my preliminary talks at two local meetups and had lots of people providing me with useful feedback.
The talks
The conference expected two talks of both 40 minutes. 40 minutes is a short time, so I had to select my slides and the level of detail very carefully.
ClojureScript for the web
My first talk was about ClojureScript for web applications in general. I explained the most important features of Clojure(Script). Unfortunately the sound volume of the video is a bit low.
The description of the talk for the conference was:
Over the last few years we have seen the rise of browser applications. Instead of rendering all UI server side, JavaScript driven client applications are now being widely adopted. While JavaScript is a flexible and powerful language, it has its shortcomings. This is where languages that compile to JavaScript step in. ClojureScript is one of them and offers its own powerful features to the front end developer. In this talk you will get an overview of what ClojureScript development looks like and how it may simplify your application.
Video:
 CLOJURESCRIPT FOR THE WEB from Øredev Conference on Vimeo.
The slides can be downloaded here. Related code is here.
ClojureScript interfaces to React
The second talk was about using ClojureScript in combination with the React library. I showed two approaches: Om and Reagent. I have spent more time and detail on Reagent, because this library is easier to explain in a 40 minute talk.
The description of the talk for the conference:
React is a JavaScript library for creating declarative UIs. It was created by Facebook to simplify writing applications consisting of many components. React allows you to describe how the UI should look and renders it automatically via one way data binding. It achieves good performance by using a virtual DOM that prevents unnecessary and expensive DOM manipulations. Even better performance can be achieved by leveraging the immutable data structures of ClojureScript. This is an approach taken by Om and Reagent. In this talk you will get an impression of using ClojureScript together with React in practice.
Video:
 CLOJURESCRIPT INTERFACES TO REACT from Øredev Conference on Vimeo.
The slides can be downloaded here. Related code is here.
The conference
Øredev is very well organized. I didn't have to worry about a thing: plane tickets, hotel, vegan food, quality coffee, ice breaking social events: all arranged by them. If you ever have the chance to speak at Øredev: I can highly recommend it!
I wasn't the only person doing Clojure-related talks. Ryan Neufield, the main author of the Clojure Cookbook and Pedestal contributor was there talking about Datomic and Pedestal. Rob Ashton shared his lessons learned while creating a database with Clojure. Neal Ford talked on functional thinking in Java, Scala and Clojure. Here's a picture of Ryan presenting about Pedestal:
Thanks
During these 40 minute talks I didn't have the time to thank people who helped me during my month of preparation in one way or another. Here is a list of people and companies I would like to thank for their help or support:
Anders Janmyr
Anna Pawlicka
Barbara Borkent
David Nolen
Denis Fuenzalida
Emily Holweck
Finalist (company)
Jayway (company)
Martin van Amersfoorth
Matthijs Steen
Ustun Ozgur
Vijay Kiran
Resources
Lastly, for what it's worth, here is a raw list of resources that I found interesting to study while I was preparing my talks. Have fun with those!
Clojurescript Up and Running
http://www.infoq.com/news/2014/01/om-react
http://www.lexicallyscoped.com/2013/12/25/slice-of-reactjs-and-cljs.html
http://adamsolove.com/js/clojure/2014/01/06/om-experience-report.html
http://www.joshlehman.me/rewriting-the-react-tutorial-in-om/
https://t.co/bzQcj0OsPW - PureScript
http://2013.jsconf.eu/speakers/pete-hunt-react-rethinking-best-practices.html
https://www.youtube.com/watch?v=SiFwRtCnxv4 - Nolen on immutability
https://www.youtube.com/watch?v=-DX3vJiqxm4 - Secrets of the Virtual DOM
http://www.funnyant.com/reactjs-what-is-it/
https://twitter.com/swannodette/status/407750614727524352 - historic tweet of David Nolen porting React code to Cljs
http://spootnik.org/entries/2014/10/26_from-angularjs-to-om-a-walk-through.html - from Angular to Om
http://www.infoq.com/presentations/ClojureScript-Javelin
https://github.com/enaqx/awesome-react
http://stackoverflow.com/questions/21109361/why-is-reacts-concept-of-virtual-dom-said-to-be-more-performant-than-dirty-mode
https://github.com/swannodette/om/blob/master/src/om/core.cljs#L250
https://www.youtube.com/watch?v=noiGVQoyYHw#t=72 - Clojure: 10 big ideas
https://keminglabs.com/blog/cljs-app-designs/ - A sampler of ClojureScript application designs
http://teropa.info/blog/2013/10/18/single-page-webapps-in-clojurescript-with-pedestal.html - SPA in Pedestal
https://groups.google.com/d/topic/pedestal-users/jODwmJUIUcg/discussion - Why Pedestal App is (probably) discontinued
http://blog.cognitect.com/blog/2014/10/24/analysis-of-the-state-of-clojure-and-clojurescript-survey-2014 - Clojure 2014 survey


Figwheel keep Om turning!
2014-09-25T23:59:59+00:00
How to combine figwheel, Om and Ring in one application
tl;dr
In this article you will find a configuration of figwheel with Om and a Ring server in one application.
The following issues will be addressed:
Om root component will be remounted upon code reload
App-state is lost when code is reloaded
Code changes in other cljs files do not cause a re-render
Let's get Om with it
For a few weeks I have been using Clojurescript and Om for front end development. Om is a Clojurescript library based on the famous React. Figwheel is a tool that can speed up Clojurescript and Om development by reloading code in the browser without refreshing an entire page.
Figwheel comes in the form of a leiningen plugin that uses lein-cljsbuild to compile Clojurescript and pushes the resulting Javascript to the browser, which is then reloaded. Together with React this is a powerful combination. As you change code in your editor and press save, the changes can be instantly reflected in the page you were viewing... if you configure things properly.
The project I'm currently working on consists of several Clojurescript files. Often an Om component resides in a file of its own. For my workflow it would make sense to be able to edit a component in one file, save the code and see the change in the browser immediately.  So here is what I've done.
Let's make a project based on the wrom template.
$ lein new wrom example
$ find .
.
./.gitignore
./project.clj
./resources
./resources/public
./resources/public/index.html
./resources/public/style.css
./src
./src/example
./src/example/client.cljs
./src/example/server.clj
The application comprises a server and client part. All sources files reside in one directory src. Let's add figwheel to our project. Add [figwheel "0.1.4-SNAPSHOT"] to :dependencies and [lein-figwheel "0.1.4-SNAPSHOT"] to plugins. Your project.clj should now look like this:
(defproject example "0.1.0-SNAPSHOT"
  :description "FIXME: write this!"
  :url "http://example.com/FIXME"

  :dependencies [[org.clojure/clojure "1.6.0"]
                 [org.clojure/clojurescript "0.0-2322"]
                 [org.clojure/core.async "0.1.267.0-0d7780-alpha"]
                 [org.webjars/react "0.11.1"]
                 [om "0.7.1"]
                 [cljs-http "0.1.14"]
                 [ring/ring-core "1.3.1"]
                 [ring/ring-jetty-adapter "1.3.1"]
                 [figwheel "0.1.4-SNAPSHOT"]]

  :plugins [[lein-cljsbuild "1.0.4-SNAPSHOT"]
            [lein-figwheel "0.1.4-SNAPSHOT"]
            [lein-ring "0.8.10"]]

  :source-paths ["src"]

  :cljsbuild {:builds [{:id "example"
                        :source-paths ["src"]
                        :compiler
                        {:output-to "resources/public/example.js"
                         :output-dir "resources/public/out"
                         :optimizations :none
                         :source-map true}}]}

  :ring {:handler example.server/app
         :nrepl {:start? true :port 4500}
         :port 8090}

  :global-vars {*print-length* 20})
Let's edit client.cljs. In the namespace declaration under :require add [figwheel.client :as fw]. Now we'll hook up figwheel so it can send changes in our project to a browser. Because we use Ring with the Jetty adapter as an external server, we have to tell figwheel explicitly where it's websocket is, since it can't just connect to the same origin.
(fw/watch-and-reload
 :websocket-url   "ws://localhost:3449/figwheel-ws"
 :jsload-callback
 (fn []
   (println "reloaded")))
Start Ring and Figwheel independently, both from inside the example directory. In one terminal type lein figwheel (or optionally supply the name of the build: lein figwheel example). It's best to wait for the clojurescript compilation to complete before starting Ring.
$ lein figwheel
Compiling ClojureScript.
Figwheel: Starting server at http://localhost:3449
Figwheel: Serving files from '(dev-resources|resources)/public'
Compiling "resources/public/example.js" from ["src"]...
Successfully compiled "resources/public/example.js" in 20.297 seconds.
notifying browser that file changed:  /example.js
notifying browser that file changed:  /out/goog/deps.js
notifying browser that file changed:  /out/example/client.js
In another terminal type lein ring server. If you're lucky a browser will open automatically to localhost:8090/index.html and you will see the text Hello world from server!. This text really came from the Ring handler in server.clj. If you open a developer console, you will see that figwheel has connected to the browser:
{% img center /images/2014-09/figwheel/figwheel-connecting.png %}
Now let's see if figwheel will pick up a code change in client.cljs. Let's change the render function to:
(render [_]
       (dom/div
        nil
        (dom/h1 nil (:text app))
        (dom/p nil "Hello from Michiel!")))
If everything worked, in the browser you will almost immediately see that your change is reloaded and re-rendered by Om.
Om root component will be remounted upon code reload
One problem of making changes in the file where the call to om/root resides is that the entire component tree will be unmounted and replaced by a new instance. To verify my claim, let's add line 6 and 19-21 from the snippet below:
(om/root
 (fn [app owner]
   (reify
     om/IWillMount
     (will-mount [_]
       (println "I will mount")
       (go (let [response (
Now make a change anywhere in the source code and save the file. In the browser's console you will see that Om mounted the component. Now change the source again and press save. You'll see that Om unmounted the component and mounted a new instance of the component. You really have to pay attention to this, because if you created resources or go loops in will-mount and you didn't clean them up in will-unmount, things can get really messy when you have lots of code reloads. The go loops from unmounted instances will just keep running and your program can get unpredictable. So, the solution to this problem is to keep track of your resources and take the appropriate actions in the will-unmount.
App-state is lost when code is reloaded
Let's change our app state to
(def app-state (atom {:text "" :button "unclicked"}))
and the render function to
(render [_]
       (dom/div
        nil
        (dom/p nil (pr-str app))
        (dom/button #js {:onClick #(om/update! app
                                              :button "clicked")}
                    "Click to change state")))
In the render function we show a printed version of the cursor. Now let's click the button. The app-state updated and the component is reflecting this. Now let's change the code of client.cljs and save. What do we see? Our app-state is back to the initial state. This is because app-state is being redefined by the code reload. To avoid this, change def to defonce:
(defonce app-state (atom {:text "" :button "unclicked"}))
Now the app-state will survive a code reload. Sometimes it's that easy to write re-loadable code.
Code changes in other cljs files do not cause a re-render
Let's make a second file called child.cljs like this:
(ns example.child
  (:require-macros [cljs.core.async.macros :refer (go)])
  (:require [om.core :as om :include-macros true]
            [om.dom :as dom :include-macros true]))

(defn child [cursor owner]
  (om/component
   (dom/div nil
            (dom/p nil "I'm a child.")
            (dom/p nil (str "I have local state: "
                            (pr-str (om/get-state owner))))
            (dom/button #js {:onClick
                             #(om/update-state! owner
                                                :clicks inc)}
                        "Click me to update my local state"))))
Let's require and om/build this child component in our root component, so it will appear on the page. I omitted irrelevant parts.
(ns example.client
  ,,,
  (:require [om.core :as om :include-macros true]
            ,,,
            [example.child :refer (child)]))

,,,

(om/root
 (fn [app owner]
   (reify
     ,,,
     om/IRender
     (render [_]
       (om/build child app))
     ,,,  ))
 app-state
 {:target (. js/document (getElementById "app"))})
,,,
I'm not entirely sure if figwheel handles changes in namespace declarations well, so just refresh the page. You will see the button from the child component on the screen. Click a few times:
{% img center /images/2014-09/figwheel/child-component1.png %}
Now let's change some code of the child component. For example, change the text in the button to "Click me to update me!". When saved, you won't see the change reflected in your browser. figwheel has reloaded child.cljs but the problem is that Om doesn't 'know' about this. Let's tell Om. Let's summon the power of core.async.
Change the :require entry for core.async to [cljs.core.async :refer [ so we can create channels and put something in them.
In client.cljs add a channel. Place it below the definition of app-state:
(defonce re-render-ch (chan))
In will-mount we'll now spawn a go loop that keeps reading from re-render-ch:
(will-mount [_]
  (println "I will mount")
  (go (loop []
    (when (
All we have to do now is put a (truthy) message into the channel and the root component will re-render itself. This can be done in the callback provided to fw/watch-and-reload:
(fw/watch-and-reload
 :websocket-url "ws://localhost:3449/figwheel-ws"
 :jsload-callback
 (fn []
   (println "reloaded")
   (put! re-render-ch true)))
Refresh the page so everything is in place. Now change the text of the button again in child.cljs and you'll see the component being instantly re-rendered in the browser. Observe however that all local state in the child component is lost. Because the code of the child component changed, Om has to remount the component. Again, be conscious of resources and go loops hat are creating during the mount phase and clean them up if necessary.
Let's change to child to show and update the cursor instead of local state.
(defn child [cursor owner]
  (om/component
   (dom/div nil
            (dom/p nil "I'm a child.")
            (dom/p nil (str "My cursor:"
                            (pr-str cursor)))
            (dom/button #js {:onClick
                             #(om/transact!
                               cursor
                               :clicks inc)}
                        "Click me!"))))
Click a few times and you'll see something like this:
{% img center /images/2014-09/figwheel/child-component2.png %}
Now change the text of the button in child.cljs again and save. You'll see that the state of the cursor is preserved, as expected.
Update October 11th 2014
The use of a channel to refresh a component was a little invasive and to be honest, I didn't like it much. Arne Brasseur pointed out in the comments that refreshing of Om components can be implemented simpler, because om/root is idempotent. This means it may be called multiple times and all will be well.
I changed the code in main.cljs according to the suggestion of Arne:
(ns example.client
  (:require-macros [cljs.core.async.macros :refer (go)])
  (:require [om.core :as om :include-macros true]
            [om.dom :as dom :include-macros true]
            [cljs.core.async :refer [
The differences:
no invasive channel and call to om/refresh!
the call to om/root is now wrapped inside a function main
main is called on initial page load and will be called by figwheel upon code reload (no matter which ClojureScript file, which the point of putting the call to main here)
Arne Brasseur is the author of the excellent Chestnut template, that embeds Figwheel as one of its dev tools. I suggest you try it out if you haven't. David Nolen, the author of Om, just published a demo video of Chestnut.
The completed (and updated) code of this blog post can be viewed here.
If you liked my post or want to suggest an improvement, please leave a comment. Thanks for reading!