-
Notifications
You must be signed in to change notification settings - Fork 80
/
book.clj
1116 lines (836 loc) · 43.8 KB
/
book.clj
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;; # 📖 Book of Clerk
^{:nextjournal.clerk/visibility {:code :hide}}
(ns nextjournal.clerk.book
{:nextjournal.clerk/toc true
:nextjournal.clerk/open-graph
{:url "https://book.clerk.vision"
:title "The Book of Clerk"
:description "Clerk’s official documentation."
:image "https://cdn.nextjournal.com/data/QmbHy6nYRgveyxTvKDJvyy2VF9teeXYkAXXDbgbKZK6YRC?filename=book-of-clerk-og-image.png&content-type=image/png"}}
(:require [clojure.string :as str]
[next.jdbc :as jdbc]
[nextjournal.clerk :as clerk]
[nextjournal.clerk.parser :as parser]
[nextjournal.clerk.eval :as eval]
[nextjournal.clerk.analyzer :as ana]
[nextjournal.clerk.viewer :as v]
[emmy.env :as emmy]
[emmy.expression]
[weavejester.dependency :as dep])
(:import (javax.imageio ImageIO)
(java.net URL)))
;; ## ⚖️ Rationale
;; Computational notebooks allow arguing from evidence by mixing prose with executable code. For a good overview of problems users encounter in traditional notebooks like Jupyter, see [I don't like notebooks](https://www.youtube.com/watch?v=7jiPeIFXb6U) and [What’s Wrong with Computational Notebooks? Pain Points, Needs, and Design Opportunities](https://www.microsoft.com/en-us/research/uploads/prod/2020/03/chi20c-sub8173-cam-i16.pdf).
;; Specifically Clerk wants to address the following problems:
;; * Less helpful than my editor
;; * Notebook code being hard to reuse
;; * Reproduction problems coming from out-of-order execution
;; * Problems with archival and putting notebooks in source control
;; Clerk is a notebook library for Clojure that aims to address these problems by doing less, namely:
;; * no editing environment, folks can keep using the editors they know and love
;; * no new format: Clerk notebooks are either regular Clojure namespaces (interspersed with markdown comments) or regular markdown files (interspersed with Clojure code fences). This also means Clerk notebooks are meant to be stored in source control.
;; * no out-of-order execution: Clerk notebooks always evaluate from top to bottom. Clerk builds a dependency graph of Clojure vars and only recomputes the needed changes to keep the feedback loop fast.
;; * no external process: Clerk runs inside your Clojure process, giving Clerk access to all code on the classpath.
;; ## 🚀 Getting Started
;; Clerk requires Java 11 or newer and [`clojure`](https://clojure.org/guides/install_clojure) installed.
;; ### 🤹 Clerk Demo
;; When you're not yet familiar with Clerk, we recommend cloning and playing with the [nextjournal/clerk-demo](https://github.com/nextjournal/clerk-demo) repo.
;; ```sh
;; git clone [email protected]:nextjournal/clerk-demo.git
;; cd clerk-demo
;; ```
;; Then open `dev/user.clj` from the project in your favorite editor and start a REPL into the project. For editor-specific instructions see:
;; * [Emacs & Cider](https://docs.cider.mx/cider/basics/up_and_running.html#launch-an-nrepl-server-from-emacs)
;; * [Calva](https://calva.io/jack-in-guide/)
;; * [Cursive](https://cursive-ide.com/userguide/repl.html)
;; * [Vim & Neovim](https://github.com/clojure-vim/vim-jack-in)
;; ### 🔌 In an Existing Project
;; To use Clerk in your project, add the following dependency to your `deps.edn`:
;; ```edn
;; {:deps {io.github.nextjournal/clerk {:mvn/version "0.17.1102"}}}
;; ```
;; Require and start Clerk as part of your system start, e.g. in `user.clj`:
;; ```clojure
;; (require '[nextjournal.clerk :as clerk])
;; ;; start Clerk's built-in webserver on the default port 7777, opening the browser when done
;; (clerk/serve! {:browse? true})
;; ;; either call `clerk/show!` explicitly to show a given notebook, or use the File Watcher described below.
;; (clerk/show! "notebooks/rule_30.clj")
;; ```
;; You can then access Clerk at <http://localhost:7777>.
;; ### ⏱ File Watcher
;; You can load, evaluate, and present a file with the `clerk/show!` function, but in most cases it's easier to start a file watcher with something like:
;; ```clojure
;; (clerk/serve! {:watch-paths ["notebooks" "src"]})
;; ```
;; ... which will automatically reload and re-eval any clojure (clj) or markdown (md) files that change, displaying the most recently changed one in your browser.
;; To make this performant enough to feel good, Clerk caches the computations it performs while evaluating each file. Likewise, to make sure it doesn't send too much data to the browser at once, Clerk paginates data structures within an interactive viewer.
;; ### 🔪 Editor Integration
;; A recommended alternative to the file watcher is setting up a hotkey in your editor to save & `clerk/show!` the active file.
;; **Emacs**
;; In Emacs, add the following to your config:
;; ```el
;; (defun clerk-show ()
;; (interactive)
;; (when-let
;; ((filename
;; (buffer-file-name)))
;; (save-buffer)
;; (cider-interactive-eval
;; (concat "(nextjournal.clerk/show! \"" filename "\")"))))
;;
;; (define-key clojure-mode-map (kbd "<M-return>") 'clerk-show)
;; ```
;; **IntelliJ/Cursive**
;; In IntelliJ/Cursive, you can [set up REPL commands](https://cursive-ide.com/userguide/repl.html#repl-commands) via:
;; * going to `Tools→REPL→Add New REPL Command`, then
;; * add the following command: `(show! "~file-path")`;
;; * make sure the command is executed in the `nextjournal.clerk` namespace;
;; * lastly assign a shortcut of your choice via `Settings→Keymap`
;; **Neovim + Conjure**
;; With [neovim](https://neovim.io/) + [conjure](https://github.com/Olical/conjure/) one can use the following vimscript function to save the file and show it with Clerk:
;; ```vimscript
;; function! ClerkShow()
;; exe "w"
;; exe "ConjureEval (nextjournal.clerk/show! \"" . expand("%:p") . "\")"
;; endfunction
;; nmap <silent> <localleader>cs :execute ClerkShow()<CR>
;; ```
;; ## 🔍 Viewers
;; Clerk comes with a number of useful built-in viewers e.g. for
;; Clojure data, html & hiccup, tables, plots &c.
;; When showing large data structures, Clerk's default viewers will
;; paginate the results.
;; ### 🧩 Clojure Data
;; The default set of viewers are able to render Clojure data.
(def clojure-data
{:hello "world 👋"
:tacos (map #(repeat % '🌮) (range 1 30))
:zeta "The\npurpose\nof\nvisualization\nis\ninsight,\nnot\npictures."})
;; Viewers can handle lazy infinite sequences, partially loading data
;; by default with the ability to load more data on request.
(range)
(def fib (lazy-cat [0 1] (map + fib (rest fib))))
;; In addition, there's a number of built-in viewers that can be
;; called explicity using functions.
;; ### 🌐 Hiccup, HTML & SVG
;; The `html` viewer interprets `hiccup` when passed a vector.
(clerk/html [:div "As Clojurians we " [:em "really"] " enjoy hiccup"])
;; Alternatively you can pass it an HTML string.
(clerk/html "Never <strong>forget</strong>.")
;; You can style elements, using [Tailwind CSS](https://tailwindcss.com/docs/utility-first).
(clerk/html [:button.bg-sky-500.hover:bg-sky-700.text-white.rounded-xl.px-2.py-1 "✨ Tailwind CSS"])
;; The `html` viewer is able to display SVG, taking either a hiccup vector or a SVG string.
(clerk/html [:svg {:width 500 :height 100}
[:circle {:cx 25 :cy 50 :r 25 :fill "blue"}]
[:circle {:cx 100 :cy 75 :r 25 :fill "red"}]])
;; You can also embed other viewers inside of hiccup.
(clerk/html [:div.flex.justify-center.space-x-6
[:p "a table is next to me"]
(clerk/table [[1 2] [3 4]])])
;; ### 🔢 Tables
;; Clerk provides a built-in data table viewer that supports the three
;; most common tabular data shapes out of the box: a sequence of maps,
;; where each map's keys are column names; a seq of seqs, which is just
;; a grid of values with an optional header; a map of seqs, in which
;; keys are column names and rows are the values for that column.
(clerk/table [[1 2]
[3 4]]) ;; seq of seqs
(clerk/table (clerk/use-headers [["odd numbers" "even numbers"]
[1 2]
[3 4]])) ;; seq of seqs with header
(clerk/table [{"odd numbers" 1 "even numbers" 2}
{"odd numbers" 3 "even numbers" 4}]) ;; seq of maps
(clerk/table {"odd numbers" [1 3]
"even numbers" [2 4]}) ;; map of seqs
;; Internally the table viewer will normalize all of the above to a
;; map with `:rows` and an optional `:head` key, also giving you
;; control over the column order.
(clerk/table {:head ["odd numbers" "even numbers"]
:rows [[1 2] [3 4]]}) ;; map with `:rows` and optional `:head` keys
;; To customize the number of rows in the table viewer, set
;; `::clerk/page-size`. Use a value of `nil` to show all rows.
(clerk/table {::clerk/page-size 7} (map (comp vector (partial str "Row #")) (range 1 31)))
;; The built-in table viewer adds a number of child-viewers on its
;; `:add-viewers` key. Those sub-viewers control the markup for the
;; table and the display of strings (to turn off quoting inside table
;; cells).
(:add-viewers v/table-viewer)
;; Modifying the `:add-viewers` key allows us to create a custom table
;; viewer that shows missing values differently.
(def table-viewer-custom-missing-values
(update v/table-viewer :add-viewers v/add-viewers [(assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
^{::clerk/viewer table-viewer-custom-missing-values}
{:A [1 2 3] :B [1 3] :C [1 2]}
;; ### 🧮 TeX
;; As we've already seen, all comment blocks can contain TeX (we use
;; [KaTeX](https://katex.org/) under the covers). In addition, you can
;; call the TeX viewer programmatically. Here, for example, are
;; Maxwell's equations in differential form:
(clerk/tex "
\\begin{alignedat}{2}
\\nabla\\cdot\\vec{E} = \\frac{\\rho}{\\varepsilon_0} & \\qquad \\text{Gauss' Law} \\\\
\\nabla\\cdot\\vec{B} = 0 & \\qquad \\text{Gauss' Law ($\\vec{B}$ Fields)} \\\\
\\nabla\\times\\vec{E} = -\\frac{\\partial \\vec{B}}{\\partial t} & \\qquad \\text{Faraday's Law} \\\\
\\nabla\\times\\vec{B} = \\mu_0\\vec{J}+\\mu_0\\varepsilon_0\\frac{\\partial\\vec{E}}{\\partial t} & \\qquad \\text{Ampere's Law}
\\end{alignedat}
")
;; ### 📊 Plotly
;; Clerk also has built-in support for Plotly's low-ceremony plotting.
;; See [Plotly's JavaScript docs](https://plotly.com/javascript/) for more examples and [options](https://plotly.com/javascript/configuration-options/).
(clerk/plotly {:data [{:z [[1 2 3] [3 2 1]] :type "surface"}]
:layout {:margin {:l 20 :r 0 :b 20 :t 20}
:paper_bgcolor "transparent"
:plot_bgcolor "transparent"}
:config {:displayModeBar false
:displayLogo false}})
;; ### 🗺 Vega Lite
;; But Clerk also has Vega Lite for those who prefer that grammar.
(clerk/vl {:width 650 :height 400 :data {:url "https://vega.github.io/vega-datasets/data/us-10m.json"
:format {:type "topojson" :feature "counties"}}
:transform [{:lookup "id" :from {:data {:url "https://vega.github.io/vega-datasets/data/unemployment.tsv"}
:key "id" :fields ["rate"]}}]
:projection {:type "albersUsa"} :mark "geoshape" :encoding {:color {:field "rate" :type "quantitative"}}
:background "transparent"
:embed/opts {:actions false}})
;; You can provide a map of [embed options](https://github.com/vega/vega-embed#embed) to the vega viewer via the `:embed/opts` key.
;;
;; Clerk handles conversion from EDN to JSON for you.
;; The official Vega-Lite examples are in JSON, but a Clojure/EDN version is available:
;; [Carsten Behring's Vega gallery in EDN](https://vlgalleryedn.happytree-bf95e0f8.westeurope.azurecontainerapps.io/).
;; ### 🎼 Code
;; By default the code viewer uses
;; [clojure-mode](https://nextjournal.github.io/clojure-mode/) for
;; syntax highlighting.
(clerk/code (macroexpand '(when test
expression-1
expression-2)))
(clerk/code '(ns foo "A great ns" (:require [clojure.string :as str])))
(clerk/code "(defn my-fn\n \"This is a Doc String\"\n [args]\n 42)")
;; You can specify the language for syntax highlighting via `::clerk/opts`.
(clerk/code {::clerk/opts {:language "python"}} "
class Foo(object):
def __init__(self):
pass
def do_this(self):
return 1")
;; Or use a code fence with a language in a markdown.
(clerk/md "```c++
#include <iostream>
int main() {
std::cout << \" Hello, world! \" << std::endl
return 0
}
```")
;; ### 🏞 Images
;; Clerk offers the `clerk/image` viewer to create a buffered image
;; from a string or anything `javax.imageio.ImageIO/read` can take
;; (URL, File or InputStream).
;;
;; For example, we can fetch a photo of De zaaier, Vincent van Gogh's
;; famous painting of a farmer sowing a field from Wiki Commons like
;; this:
(clerk/image "https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/The_Sower.jpg/1510px-The_Sower.jpg")
;; We've put some effort into making the default image rendering
;; pleasing. The viewer uses the dimensions and aspect ratio of each
;; image to guess the best way to display it in classic DWIM
;; fashion. For example, an image larger than 900px wide with an
;; aspect ratio larger then two will be displayed full width:
(clerk/image "https://images.unsplash.com/photo-1532879311112-62b7188d28ce?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8")
;; On the other hand, smaller images are centered and shown using their intrinsic dimensions:
(clerk/image "https://nextjournal.com/data/QmSJ6eu6kUFeWrqXyYaiWRgJxAVQt2ivaoNWc1dtTEADCf?filename=thermo.png&content-type=image/png")
;; You can use `clerk/image` together with `clerk/caption` which will render a simple caption under the image:
(clerk/caption
"Implements of the Paper Printing Industry"
(clerk/image "https://nextjournal.com/data/QmX99isUndwqBz7nj8fdG7UoDakNDSH1TZcvY2Y6NUTe6o?filename=image.gif&content-type=image/gif"))
;; Captions aren't limited to images and work together with any arbitrary content that you provide, e.g. a table:
^{::clerk/visibility {:code :fold}}
(clerk/caption
"Modern Symmetrical Unary(7) in [Solresol](https://wiki.xxiivv.com/site/solresol.html)"
(clerk/table {:head ["Solfège" "French IPA" "English IPA" "Meaning"]
:rows [["Do" "/do/" "/doʊ/" "no"]
["Re" "/ʁɛ/" "/ɹeɪ/" "and, also"]
["Mi" "/mi/" "/miː/" "or"]
["Fa" "/fa/" "/fɑː/" "at, to"]
["Sol" "/sɔl/" "/soʊl/" "but, if"]
["La" "/la/" "/lɑː/" "the, then"]
["Si" "/si/" "/siː/" "yes"]]}))
;; ### 📒 Markdown
;; The same Markdown support Clerk uses for comment blocks is also
;; available programmatically:
(clerk/md (clojure.string/join "\n" (map #(str "* Item " (inc %)) (range 3))))
;; For a more advanced example of ingesting markdown files and transforming the
;; content to HTML using Hiccup, see [notebooks/markdown.md](https://github.com/nextjournal/clerk-demo/blob/47e95fdc38dd5321632f73bb50a049da4055e041/notebooks/markdown.md)
;; in the clerk-demo repo.
;; ### 🔠 Grid Layouts
;; Layouts can be composed via `row`s and `col`s.
;;
;; Passing `:width`, `:height` or any other style attributes to
;; `::clerk/opts` will assign them on the row or col that contains
;; your items. You can use this to size your containers accordingly.
^{::clerk/visibility {:code :hide :result :hide}}
(def image-1 (ImageIO/read (URL. "https://nextjournal.com/data/QmU9dbBd89MUK631CoCtTwBi5fX4Hgx2tTPpiL4VStg8J7?filename=a.gif&content-type=image/gif")))
^{::clerk/visibility {:code :hide :result :hide}}
(def image-2 (ImageIO/read (URL. "https://nextjournal.com/data/QmfKZzHCBQKU7KKXQqcje5cgR6zLge3CcxeuZe8moUkJxf?filename=b.gif&content-type=image/gif")))
^{::clerk/visibility {:code :hide :result :hide}}
(def image-3 (ImageIO/read (URL. "https://nextjournal.com/data/QmXALbNeDD6NSudgVfHE5SvY1Xjzbj7TSWnARqcZrvXsss?filename=c.gif&content-type=image/gif")))
(clerk/row image-1 image-2 image-3)
(clerk/col {::clerk/opts {:width 150}} image-1 image-2 image-3)
;; Laying out stuff is not limited to images. You can use it to lay
;; out any Clerk viewer. E.g. combine it with HTML viewers to render
;; nice captions:
(defn caption [text]
(clerk/html [:figcaption.text-center.mt-1 text]))
(clerk/row
(clerk/col image-1 (caption "Figure 1: Decorative A"))
(clerk/col image-2 (caption "Figure 2: Decorative B"))
(clerk/col image-3 (caption "Figure 3: Decorative C")))
;; Note: the caption example is _exactly_ how `clerk/caption` is implemented in Clerk.
;; **Alternative notations**
;;
;; By default, `row` and `col` operate on `& rest` so you can pass any
;; number of items to the functions. But the viewers are smart enough
;; to accept any sequential list of items.
(v/row [image-1 image-2 image-3])
;; ### 🍱 Composing Viewers
;; Viewers compose, so, for example, you can lay out multiple independent Vega charts using Clerk’s grid viewers:
^{::clerk/visibility {:code :fold}}
(do
(def stock-colors
{"AAPL" "#4c78a8" "AMZN" "#f58518" "GOOG" "#e45756" "IBM" "#72b7b2" "MSFT" "#54a24b"})
(def combined-stocks-chart
(clerk/vl {:width 600
:height 200
:data {:url "https://vega.github.io/vega-lite/examples/data/stocks.csv"}
:mark "area"
:encoding {:x {:timeUnit "yearmonth" :field "date" :axis {:format "%Y"}}
:y {:aggregate "sum" :field "price"}
:color {:field "symbol"
:scale {:domain (keys stock-colors) :range (vals stock-colors)}}}
:embed/opts {:actions false}}))
(defn stock-chart [symbol]
(clerk/vl {:title symbol
:width 100
:height 40
:mark "area"
:data {:url "https://vega.github.io/vega-lite/examples/data/stocks.csv"}
:transform [{:filter (str "datum.symbol == '" symbol "'")}]
:encoding {:x {:field "date" :type "temporal" :title nil :axis {:grid false}}
:y {:field "price" :type "quantitative" :title nil :axis {:grid false} :scale {:domain [0 700]}}
:color {:field "symbol" :type "nominal" :legend nil :scale {:domain [symbol]
:range [(get stock-colors symbol)]}}}
:embed/opts {:actions false}})))
(clerk/col
(clerk/row (stock-chart "AAPL")
(stock-chart "AMZN")
(stock-chart "GOOG")
(stock-chart "IBM")
(stock-chart "MSFT"))
combined-stocks-chart)
;; Viewers can also be embedded in Hiccup. The following example shows
;; how this is used to provide a custom callout for a `clerk/image`.
(clerk/html
[:div.relative
(clerk/image "https://images.unsplash.com/photo-1608993659399-6508f918dfde?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2070&q=80")
[:div.absolute
{:class "left-[25%] top-[21%]"}
[:div.border-4.border-emerald-400.rounded-full.shadow
{:class "w-8 h-8"}]
[:div.border-t-4.border-emerald-400.absolute
{:class "w-[80px] rotate-[30deg] left-4 translate-x-[10px] translate-y-[10px]"}]
[:div.border-4.border-emerald-400.absolute.text-white.font-sans.p-3.rounded-md
{:class "bg-black bg-opacity-60 text-[13px] w-[280px] top-[66px]"}
"Cat's paws are adapted to climbing and jumping, walking and running, and have protractible claws for self-defense and hunting."]]])
#_(clerk/html [:div.flex.justify-around donut-chart donut-chart donut-chart])
;; ### 🤹🏻 Applying Viewers
;; **Metadata Notation**
;; In the examples above, we've used convenience helper functions like
;; `clerk/html` or `clerk/plotly` to wrap values in a viewer. If you
;; call this on the REPL, you'll notice a given value gets wrapped in
;; a map under the `:nextjournal/value` key with the viewer being in
;; the `:nextjournal/viewer` key.
;; You can also select a viewer using Clojure metadata in order to
;; avoid Clerk interfering with the value.
^{::clerk/viewer clerk/table}
(def my-dataset
[{:temperature 41.0 :date (java.time.LocalDate/parse "2022-08-01")}
{:temperature 39.0 :date (java.time.LocalDate/parse "2022-08-01")}
{:temperature 34.0 :date (java.time.LocalDate/parse "2022-08-01")}
{:temperature 29.0 :date (java.time.LocalDate/parse "2022-08-01")}])
;; As you can see above, the table viewer is being applied to the
;; value of the `my-dataset` var, not the var itself. If you want your viewer to access the raw var, you can opt out of this with a truthy `:var-from-def?` key on the viewer.
^{::clerk/viewer (assoc v/fallback-viewer :var-from-def? true)}
(def raw-var :baz)
;; ### 👁 Writing Viewers
;; Let's explore how Clerk viewers work and how you create your own to
;; gain better insight into your problem at hand.
v/default-viewers
;; These are the default viewers that come with Clerk.
(into #{} (map type) v/default-viewers)
;; Each viewer is a simple Clojure map.
(assoc (frequencies (mapcat keys v/default-viewers)) :total (count v/default-viewers))
;; We have a total of 43 viewers in the defaults. Let's start with a
;; simple example and explain the different extensions points in the
;; viewer api.
;; #### 🎪 Presentation
;; Clerk's rendering happens in the browser. On the Clojure-side, a
;; given document is _presented_. Presenting takes a value and
;; transforms it such that Clerk can send it to the browser where it
;; will be rendered.
;; Let's start with one of the simplest examples. You can see that
;; `present` takes our value `1` and transforms it into a map, with
;; `1` under a `:nextjournal/value` key and the number viewer assigned
;; under the `:nextjournal/viewer` key. We call this map a
;; `wrapped-value`.
^{::clerk/viewer v/inspect-wrapped-values ::clerk/auto-expand-results? true}
(clerk/present 1)
;; This data structure is sent over Clerk's websocket to the
;; browser, where it will be displayed using the `:render-fn` found in
;; the `:nextjournal/viewer` key.
;; Now onto something slightly more complex, `#{1 2 3}`.
^{::clerk/viewer v/inspect-wrapped-values ::clerk/auto-expand-results? true}
(clerk/present #{1 2 3})
;; Here, we're giving it a set with 1, 2, 3 in it. In its generalized
;; form, `present` is a function that does a depth-first traversal of
;; a given tree, starting at the root node. It will select a viewer
;; for this root node, and unless told otherwise, descend further down
;; the tree to present its child nodes.
;;
;; Compare this with the simple `1` example above! You should
;; recognize the leaf values. Also note that the container is no
;; longer a set, but it has been transformed into a vector. This
;; transformation exists to support pagination of long unordered
;; sequences like maps and sets and so we can efficiently access a
;; value inside this tree using `get-in`.
;; You might ask yourself why we don't just send the unmodified value
;; to the browser. For one, we could easily overload the browser with
;; too much data. Secondly we will look at examples of being able to
;; select viewers based on Clojure and Java types, which cannot be
;; serialized and sent to the browser.
;; #### ⚙️ Transform
;; When writing your own viewer, the first extension point you should reach for is `:transform-fn`.
#_ "exercise: wrap this in `clerk/present` and call it at the REPL"
(v/with-viewer {:transform-fn v/inspect-wrapped-values}
"Exploring the viewer api")
;; As you can see the argument to the `:transform-fn` isn't just the
;; string we're passing it, but a map with the original value under a
;; `:nextjournal/value` key. We call this map a `wrapped-value`. We
;; will look at what this enables in a bit. But let's look at one of
;; the simplest examples first.
;; **A first simple example**
(def greet-viewer
{:transform-fn (clerk/update-val #(clerk/html [:strong "Hello, " % " 👋"]))})
;; For this simple `greet-viewer` we're only doing a simple value transformation. For this, `clerk/update-val` is a small helper function which takes a function `f` and returns a function to update only the value inside a `wrapped-value`, a shorthand for `#(update % :nextjournal/val f)`
(v/with-viewer greet-viewer
"James Clerk Maxwell")
;; The `:transform-fn` runs on the JVM, which means you can explore what it does at your REPL by calling `clerk/present` on such a value.
^{::clerk/viewer v/inspect-wrapped-values}
(clerk/present (v/with-viewer greet-viewer
"James Clerk Maxwell"))
;; **Passing modified viewers down the tree**
v/table-viewer
(def custom-table-viewer
(update v/table-viewer :add-viewers v/add-viewers [(assoc v/table-head-viewer :transform-fn (v/update-val (partial map (comp (partial str "Column: ") str/capitalize name))))
(assoc v/table-missing-viewer :render-fn '(fn [x] [:span.red "N/A"]))]))
(clerk/with-viewer custom-table-viewer
{:col/a [1 2 3 4] :col/b [1 2 3] :col/c [1 2 3]})
(clerk/with-viewer custom-table-viewer
{:col/a [1 2 3 4] :col/b [1 2 3] :col/c [1 2 3]})
;; #### 🐢 Recursion
;; But this presentation and hence tranformation of nodes
;; further down the tree isn't always what you want. For example, the
;; `plotly` or `vl` viewers want to receive the child value unaltered
;; in order to use it as a spec.
;;
;; To stop Clerk's presentation from descending into child nodes, use
;; `clerk/mark-presented` as a `:transform-fn`. Compare the result
;; below in which `[1 2 3]` appears unaltered with what you see above.
^{::clerk/viewer v/inspect-wrapped-values}
(clerk/present (clerk/with-viewer {:transform-fn clerk/mark-presented
:render-fn '(fn [x] [:pre (pr-str x)])}
[1 2 3]))
;; Clerk's presentation will also transform maps into sequences in
;; order to paginate large maps. When you're dealing with a map that
;; you know is bounded and would like to preserve its keys, there's
;; `clerk/mark-preserve-keys`. This will still transform (and
;; paginate) the values of the map, but leave the keys unaltered.
^{::clerk/viewer v/inspect-wrapped-values ::clerk/auto-expand-results? true}
(clerk/present (clerk/with-viewer {:transform-fn clerk/mark-preserve-keys}
{:hello 42}))
;; #### 🔬 Render
;; As we've just seen, you can also do a lot with `:transform-fn` and
;; using `clerk/html` on the JVM. When you want to run code in the
;; browser where Clerk's viewers are rendered, reach for
;; `:render-fn`. As an example, we'll write a multiviewer for a
;; emmy literal expression that will compute two alternative
;; representations and let the user switch between them in the
;; browser.
;; We start with a simple function that takes such an expression and
;; turns it into a map with two representations, one TeX and the
;; original form.
(defn transform-literal [expr]
{:TeX (-> expr emmy/->TeX clerk/tex)
:original (clerk/code (with-out-str (emmy/print-expression (emmy/freeze expr))))})
;; Our `literal-viewer` calls this `transform-literal` function and
;; also calls `clerk/mark-preserve-keys`. This tells Clerk to leave
;; the keys of the map as-is.
;; In our `:render-fn`, which is called in the browser, we will receive this
;; map. Note that this is a quoted form, not a function. Clerk will send this
;; form to the browser for evaluation. There it will create a `reagent/atom`
;; that holds the selection state. Lastly,
;; `nextjournal.clerk.render/inspect-presented` is a component that takes a
;; `wrapped-value` that ran through `clerk/present` and show it.
(def literal-viewer
{:pred emmy.expression/literal?
:transform-fn (comp clerk/mark-preserve-keys
(clerk/update-val transform-literal))
:render-fn '(fn [label->val]
(reagent.core/with-let [!selected-label (reagent.core/atom (ffirst label->val))]
[:<> (into
[:div.flex.items-center.font-sans.text-xs.mb-3
[:span.text-slate-500.mr-2 "View-as:"]]
(map (fn [label]
[:button.px-3.py-1.font-medium.hover:bg-indigo-50.rounded-full.hover:text-indigo-600.transition
{:class (if (= @!selected-label label) "bg-indigo-100 text-indigo-600" "text-slate-500")
:on-click #(reset! !selected-label label)}
label]))
(keys label->val))
[nextjournal.clerk.render/inspect-presented (get label->val @!selected-label)]]))})
;; Now let's see if this works. Try switching to the original
;; representation!
^{::clerk/viewer literal-viewer}
(emmy/+ (emmy/square (emmy/sin 'x))
(emmy/square (emmy/cos 'x)))
;; #### 📚 Require CLJS
;; Writing `:render-fn`s inline as quoted forms is fine when they're
;; small and independent. For more complex needs, Clerk supports
;; loading ClojureScript files from the classpath.
;; To opt into this, use a fully qualified symbol as the `:render-fn`
;; and set `:require-cljs` set to `true`. This way you tell Clerk to
;; load this ClojureScript file (along with it's deps) into Clerk's
;; SCI environment in the browser to make it useable there.
(def literal-viewer-require-cljs
(assoc literal-viewer
:require-cljs true
:render-fn 'nextjournal.clerk.emmy/render-literal))
;; Writing a render function in regular `.cljs` file often works
;; better with IDE-tooling like linters, REPLs and makes reusing
;; existing ClojureScript code easier.
^{::clerk/viewer literal-viewer-require-cljs}
(emmy/+ (emmy/square (emmy/sin 'x))
(emmy/square (emmy/cos 'x)))
;; #### 🥇 Selection
;; Without a viewer specified, Clerk will go through the sequence of
;; viewers and apply the `:pred` function in the viewer to find a
;; matching one. Use `v/viewer-for` to select a viewer for a given
;; value.
(def char?-viewer
(v/viewer-for v/default-viewers \A))
;; If we select a specific viewer (here the `v/html-viewer` using
;; `clerk/html`) this is the viewer we will get.
(def html-viewer
(v/viewer-for v/default-viewers (clerk/html [:h1 "foo"])))
;; Instead of specifying a viewer for every value, we can also modify
;; the viewers per namespace. Here, we add the `literal-viewer` from
;; above to the whole namespace.
^{::clerk/visibility {:result :hide}}
(clerk/add-viewers! [literal-viewer])
;; As you can see we now get this viewer automatically, without
;; needing to explicitly select it.
(emmy/+ (emmy/square (emmy/sin 'x))
(emmy/square (emmy/cos 'x)))
;; #### 🔓 Elisions
(def string?-viewer
(v/viewer-for v/default-viewers "Denn wir sind wie Baumstämme im Schnee."))
;; Notice that for the `string?` viewer above, there's a `:page-size`
;; of `80`. This is the case for all collection viewers in Clerk and
;; controls how many elements are displayed. So using the default
;; `string?-viewer` above, we're showing the first 80 characters.
(def long-string
(str/join (into [] cat (repeat 10 "Denn wir sind wie Baumstämme im Schnee.\n"))))
;; If we change the viewer and set a different `:n` in `:page-size`, we only see 10 characters.
(v/with-viewer (assoc string?-viewer :page-size 10)
long-string)
;; Or, we can turn off eliding, by dissoc'ing `:page-size` alltogether.
(v/with-viewer (dissoc string?-viewer :page-size)
long-string)
;; The operations above were changes to a single viewer. But we also
;; have a function `update-viewers` to update a given viewers by
;; applying a `select-fn->update-fn` map. Here, the predicate is the
;; keyword `:page-size` and our update function is called for every
;; viewer with `:page-size` and is dissoc'ing them.
(def without-pagination
{:page-size #(dissoc % :page-size)})
;; Here's the updated-viewers:
(def viewers-without-lazy-loading
(v/update-viewers v/default-viewers without-pagination))
;; Now let's confirm these modified viewers don't have `:page-size`
;; on them anymore.
(filter :page-size viewers-without-lazy-loading)
;; And compare it with the defaults:
(filter :page-size v/default-viewers)
;; Now let's display our `clojure-data` var from above using these
;; modified viewers.
(clerk/with-viewers viewers-without-lazy-loading
clojure-data)
;; #### 👷 Loading Libraries
;; Here is a custom viewer for
;; [Mermaid](https://mermaid-js.github.io/mermaid), a markdown-like
;; syntax for creating diagrams from text. Note that this library
;; isn't bundled with Clerk but we use a component based on
;; [d3-require](https://github.com/d3/d3-require) to load it at
;; runtime.
(def mermaid-viewer
{:transform-fn clerk/mark-presented
:render-fn '(fn [value]
(when value
[nextjournal.clerk.render/with-d3-require {:package ["[email protected]/dist/mermaid.js"]}
(fn [mermaid]
[:div {:ref (fn [el] (when el
(.render mermaid (str (gensym)) value #(set! (.-innerHTML el) %))))}])]))})
;; We can then use the above viewer using `with-viewer`.
(clerk/with-viewer mermaid-viewer
"stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]")
;; #### 🧙 Evaluator
;; By default, [SCI](https://github.com/babashka/sci) is used for evaluating `:render-fn` functions in the browser.
;; What follows is an intentionally inefficient but fun way to compute
;; the nth fibonacci number and show how long it took.
(def fib-viewer
{:render-fn '(fn [n opts]
(reagent.core/with-let
[fib (fn fib [x]
(if (< x 2)
1
(+ (fib (dec x)) (fib (dec (dec x))))))
time-before (js/performance.now)
nth-fib (fib n)
time-after (js/performance.now)]
[:div
[:p
(if (= :cherry (-> opts :viewer :render-evaluator))
"Cherry"
"SCI")
" computed the " n "th fibonacci number (" nth-fib ")"
" in " (js/Math.ceil (- time-after time-before) 2) "ms."]]))})
(clerk/with-viewer fib-viewer 25)
;; You can opt into [cherry](https://github.com/squint-cljs/cherry) as an
;; alternative evaluator by setting `{::clerk/render-evaluator :cherry}` via the
;; viewers opts (see [Customizations](#customizations)). The main difference between cherry and SCI
;; for viewer functions is performance. For performance-sensitive code cherry is
;; better suited since it compiles directly to JavaScript code.
(clerk/with-viewer fib-viewer {::clerk/render-evaluator :cherry} 25)
#_(clerk/halt!)
#_(clerk/serve! {:port 7777})
;; ## ⚙️ Customizations
;; Clerk allows easy customization of visibility, result width and
;; budget. All settings can be applied document-wide using `ns`
;; metadata or a top-level settings marker and per form using
;; metadata.
;; Let's start with a concrete example to understand how this works.
;; ### 🙈 Visibility
;; By default, Clerk will show all code and
;; results for a notebook.
;; You can use a map of the following shape to set the visibility of
;; code and results individually:
;;
;; {:nextjournal.clerk/visibility {:code :hide :result :show}}
;;
;; The above example will hide the code and show only results.
;;
;; Valid values are `:show`, `:hide` and `:fold` (only available for `:code`).
;; Using `{:code :fold}` will hide the code cell initially but show an
;; indicator to toggle its visibility:
^{::clerk/visibility {:code :fold}} (shuffle (range 25))
;; The visibility map can be used in the following ways:
;; **Set document defaults via the `ns` form**
;;
;; (ns visibility
;; {:nextjournal.clerk/visibility {:code :fold}})
;;
;; The above example will hide all code cells by default but show an indicator
;; to toggle their visibility instead. In this case results will always show
;; because that’s the default.
;;
;; **As metadata to control a single top-level form**
;;
;; ^{::clerk/visibility {:code :hide}} (shuffle (range 25))
;;
;; This will hide the code but only show the result:
^{::clerk/visibility {:code :hide}} (shuffle (range 25))
;; Setting visibility as metadata will override the document-wide
;; visibility settings for this one specific form.
;; **As top-level form to change the document defaults**
;;
;; Independently of what defaults are set via your `ns` form,
;; you can use a top-level map as a marker to override the visibility
;; settings for any forms following it.
;;
;; Example: Code is hidden by default but you want to show code for all
;; top-level forms after a certain point:
;;
;; (ns visibility
;; {:nextjournal.clerk/visibility {:code :hide}})
;;
;; (+ 39 3) ;; code will be hidden
;; (range 25) ;; code will be hidden
;;
;; {:nextjournal.clerk/visibility {:code :show}}
;;
;; (range 500) ;; code will be visible
;; (rand-int 42) ;; code will be visible
;;
;; This comes in quite handy for debugging too!
;;
;; ### 👻 Clerk Metadata
;;
;; By default, Clerk will hide Clerk's metadata annotations on cells
;; to not distract from the essence. When you do want your reader
;; learn how the metadata annotations are written – as for this book –
;; you can opt out of this behaviour by modifying the
;; `code-block-viewer`:
;;
;; (clerk/add-viewers! [(assoc v/code-block-viewer :transform-fn (v/update-val :text))])
;;
^{::clerk/visibility {:code :hide :result :hide}}
(v/reset-viewers! *ns* (v/add-viewers (v/get-viewers *ns*) [(assoc v/code-block-viewer :transform-fn (v/update-val :text))]))
;; ### 🍽 Table of Contents
;; If you want a table of contents like the one in this document, set the `:nextjournal.clerk/toc` option.
;;
;; (ns doc-with-table-of-contents
;; {:nextjournal.clerk/toc true})
;;
;; If you want it to be collapsed initially, use `:collapsed` as a value.
;; ### 🔮 Result Expansion
;; If you want to better see the shape of your data without needing to
;; click and expand it first, set the
;; `:nextjournal.clerk/auto-expand-results?` option.
^{::clerk/visibility {:code :fold}}
(def rows
(take 15 (repeatedly (fn []
{:name (str
(rand-nth ["Oscar" "Karen" "Vlad" "Rebecca" "Conrad"]) " "
(rand-nth ["Miller" "Stasčnyk" "Ronin" "Meyer" "Black"]))
:role (rand-nth [:admin :operator :manager :programmer :designer])
:dice (shuffle (range 1 7))}))))
^{::clerk/auto-expand-results? true} rows
;; This option might become the default in the future.
;; ### 🙅🏼♂️ Viewer Budget
;; In order to not send too much data to the browser, Clerk uses a per-result budget to limit. You can see this budget in action above. Use the `:nextjournal.clerk/budget` key to change its default value of `200` or disable it completely using `nil`.
^{::clerk/budget nil ::clerk/auto-expand-results? true} rows
;; ## ⚛️ Clerk Sync
;; Clerk Sync is a way to support lightweight interactivity between
;; Clerk's render display running in the browser and the JVM. By
;; flagging a form defining an atom with `::clerk/sync` metadata,
;; Clerk will sync this atom to Clerk's render environment. It will
;; also watch recompute the notebook whenever the value inside the
;; atom changes.
^{::clerk/sync true}
(defonce !counter (atom 0))
(clerk/with-viewer {:render-fn '(fn [] [:button.bg-sky-500.hover:bg-sky-700.text-white.rounded-xl.px-2.py-1
{:on-click #(swap! !counter inc)}
"Increment Counter"])}
{})
;; ## 🚰 Tap Inspector
;; Clerk comes with an inspector notebook for Clojure's tap system. Use the following form from your REPL to show it.
;;```clojure
;;(nextjournal.clerk/show! 'nextjournal.clerk.tap)
;;```
;; You can then call `tap>` from anywhere in your codebase and the Tap Inspector will show your value. This supports the full viewer api described above.
;;```clojure
;;(tap> (clerk/html [:h1 "Hello 🚰 Tap Inspector 👋"]))
;;```
;; ## 👷♀️ Static Building
;; Clerk can make a static HTML build from a collection of notebooks.
;; The entry point for this is the `nextjournal.clerk/build!`
;; function. You can pass it a set of notebooks via the `:paths`
;; option (also supporting glob patterns).
;; When Clerk is building multiple notebooks, it will automatically
;; generate an index page that will be the first to show up when
;; opening the build. You can override this index page via the