(+ 1 2 3)6Hello, Jank
This is the first Jank-authored post on Clojure Civitas — and at the same time, a small walkthrough of how to author your own. The page is rendered with Janqua, a Quarto extension that evaluates {.clojure .jank} code blocks against a running Jank nREPL during the render and replaces each block with its evaluated output. Kindly metadata controls how each value renders, the same convention Clay uses for Clojure documents.
A huge thanks to Jeaye Wilkerson and the rest of the Jank team for building Jank in the open and being generous with their time as we wired this up.
Why Jank, on Civitas?
Jank is a dialect of Clojure hosted on C++ and an LLVM-based JIT. One feature that makes it interesting for a notebook-style post is its C++ interop: cpp/ forms call into C++ types and functions directly, without a separate FFI layer. Below we use that to draw random samples from the C++ standard library and chart them.
A first taste
Code blocks without Kindly metadata render as code output. The simplest possible block:
Annotate a value with ^:kind/... to tell Janqua how to render it:
^:kind/hiccup
[:div {:style "color: coral; font-size: 24px;"}
"Hello from Jank!"]Hello from Jank!
Random samples from <random>
The blocks below use Jank’s C++ interop to draw samples from the standard library. We construct a std::mt19937 (the Mersenne Twister PRNG) and a std::normal_distribution<double> from the C++ standard library, generate ten thousand samples, and collect them into a Jank vector. The cpp/ forms sit inline with the ordinary Jank code.
First, the include:
(cpp/raw "#include <random>")nilThen the sampling:
(def samples
(let [gen (cpp/std.mt19937. 42)
dist (#cpp (std.normal_distribution double) 0.0 1.0)]
(loop [i 10000 acc []]
(if (zero? i)
acc
(recur (dec i) (conj acc (dist gen)))))))
(count samples)10000A few notes on the syntax:
(cpp/raw "...")injects raw C++ into the compiled module — typically#includes. It needs to live in its own.jankblock when later code depends on the included symbols: Jank’s analyzer runs over a whole block at once, so an include and its first use can’t share a block.(cpp/std.mt19937. 42)is the familiar Clojure interop shape: trailing.calls the constructor.- For templated types, the
#cpp (Type arg ...)reader macro builds the instantiated type form.(#cpp (std.normal_distribution double) 0.0 1.0)reads as “constructstd::normal_distribution<double>(0.0, 1.0)”. loop/recurrather thanrepeatedlybecause C++ values aren’t (yet) automatically captured into Jank closures — explicit recursion sidesteps the issue.
Passing the same vector to Plotly via ^:kind/plotly renders it as a histogram — with the bell curve shape we’d expect for samples from a normal distribution:
^:kind/plotly
{:data [{:x samples
:type :histogram
:nbinsx 40
:marker {:color "coral"}}]
:layout {:title (str (count samples)
" samples ~ N(0, 1)")
:xaxis {:title "value"}
:yaxis {:title "count"}
:width 600}}Janqua serializes the Jank value to JSON and Plotly.js renders it client-side; the data itself doesn’t go through any conversion step beyond that.
Where next?
This post was the first Jank-authored page on Civitas. We’d love to see more. The Jank ecosystem is young — small, focused posts that exercise a corner of the language or a piece of C++ interop are exactly the kind of thing that helps everyone learn alongside the project.
If you hit something that doesn’t work, please open an issue on Janqua or on Civitas. Feedback shapes both.