Add global cherry evaluator setting + viewer opt (#486)

Add support for cherry as an alternative to sci to evaluate `:render-fn`s. You can change it per form (using form metadata or viewer opts) or doc-wide (using ns metadata) with `{:nextjournal.clerk/render-evaluator :cherry}`.

Co-authored-by: Martin Kavalar <martin@nextjournal.com>
Co-authored-by: Andrea Amantini <lo.zampino@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -22,16 +22,19 @@ Changes can be:
 
 * 🚨 Change `nextjournal.clerk.render/clerk-eval` to not recompute the currently shown document when using the 1-arity version. Added a second arity that takes an opts map with a `:recompute?` key.
 
-* ⭐️ Adds support for customization of viewer options 
+* 🍒 Add support for cherry as an alternative to sci to evaluate `:render-fn`s. You can change it per form (using form metadata or viewer opts) or doc-wide (using ns metadata) with `{:nextjournal.clerk/render-evaluator :cherry}`.
+
+* ⭐️ Adds support for customization of viewer options
 
   Support both globally (via ns metadata or a settings marker) or locally (via form metadata or the viewer options map).
-  
+
   Supported options are:
    * `:nextjournal.clerk/auto-expand-results?`
    * `:nextjournal.clerk/budget`
    * `:nextjournal.clerk/css-class`
    * `:nextjournal.clerk/visibility`
    * `:nextjournal.clerk/width`
+   * `:nextjournal.clerk/render-evaluator`
 
 * 🔌 Make websocket reconnect automatically on close to avoid having to reload the page
 

notebooks/cherry.clj

@@ -1,57 +1,53 @@
 ;; # Compile viewer functions using cherry
-(ns notebooks.cherry
-  #_{:nextjournal.clerk/visibility {:code :hide}
-     :nextjournal.clerk/auto-expand-results? true}
+(ns cherry
+  {:nextjournal.clerk/render-evaluator :cherry}
   (:require [nextjournal.clerk :as clerk]
             [nextjournal.clerk.viewer :as viewer]))
 
-(comment
-  (clerk/clear-cache!))
+#_(clerk/clear-cache!)
+#_(clerk/halt!)
+#_(clerk/serve! {:port 7777})
+
+;; Since we set `:nextjournal.clerk/render-evaluator :cherry` on the ns meta, evaluation happens through cherry by default
+;; in all codeblocks below. As a test for checking that Cherry is actually being picked up, we drop some `this-as` expressions
+;; in the code, since that will throw an exceptions when evaluated by SCI.
 
 (clerk/with-viewer
-  {:render-fn
-   '(fn [value]
-      [:pre (time (do (dotimes [_ 100000]
-                        (js/Math.sin 100))
-                      (pr-str (interleave (cycle [1]) (frequencies [1 2 3 1 2 3])))))])}
-  (+ 1 2 3 5))
+  '(fn [value]
+     [:pre (time (do (dotimes [_ 100000]
+                       (js/Math.sin 100))
+                     (pr-str (interleave (cycle [1]) (frequencies [1 2 3 1 2 3])))))])
+  {:nextjournal.clerk/render-evaluator :sci} nil)
 
 ;; Better performance:
 
+(clerk/with-viewer
+  '(fn [value]
+     [:pre
+      (time (do (dotimes [_ 100000]
+                  (js/Math.sin 100))
+                (pr-str (interleave (cycle [1]) (frequencies [1 2 3 1 2 3])))))]) nil)
+
 (clerk/with-viewer
   {:render-fn
    '(fn [value]
-      [:pre
-       (time (do (dotimes [_ 100000]
-                   (js/Math.sin 100))
-                 (pr-str (interleave (cycle [1]) (frequencies [1 2 3 1 2 3])))))])
-   :evaluator :cherry}
+      [:pre (this-as this value)])}
   (+ 1 2 3 5))
 
 ;; Let's use a render function in the :render-fn next
 
-(clerk/with-viewer
-  {:render-fn
-   '(fn [value]
-      [nextjournal.clerk.render/render-code "(+ 1 2 3)"])
-   :evaluator :cherry}
-  (+ 1 2 3 5))
+(clerk/with-viewer '(fn [value]
+                      [nextjournal.clerk.render/render-code "(+ 1 2 3)"]) nil)
 
 ;; Recursive ...
 
-(clerk/with-viewer
-  {:render-fn
-   '(fn [value]
-      [nextjournal.clerk.render/inspect {:a (range 30)}])
-   :evaluator :cherry}
-  nil)
-
-;; cherry vega viewer!
+(clerk/with-viewer '(fn [value]
+                      (this-as this
+                        [nextjournal.clerk.render/inspect {:a (range 30)}])) nil)
 
-(def cherry-vega-viewer (assoc viewer/vega-lite-viewer :evaluator :cherry))
+;; vega viewer still works
 
-(clerk/with-viewer
-  cherry-vega-viewer
+(clerk/vl
   {:width 700 :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"}
@@ -61,7 +57,7 @@
 ;; ## Input text and compile on the fly with cherry
 
 (clerk/with-viewer
-  {:evaluator :cherry
+  {;; :evaluator :cherry
    :render-fn
    '(fn [value]
       (let [default-value "(defn foo [x] (+ x 10))
@@ -82,17 +78,16 @@
            [nextjournal.clerk.render/inspect
             (try (js/eval @!compiled)
                  (catch :default e e))]])))}
+  {:nextjournal.clerk/render-evaluator :cherry}
   nil)
 
 ;; ## Functions defined with `defn` are part of the global context
 
 ;; (for now) and can be called in successive expressions
 
-(clerk/eval-cljs-str {:evaluator :cherry}
-                     "(defn foo [x] x)")
+(clerk/eval-cljs-str "(defn foo [x] (this-as this (inc x)))")
 
-(clerk/eval-cljs-str {:evaluator :cherry}
-                     "(foo 1)")
+(clerk/eval-cljs-str "(foo 1)")
 
 ;; ## Async/await works cherry
 
@@ -102,9 +97,7 @@
 ;; async functions need `^:async`, we use a plain string.
 
 
-^::clerk/no-cache
 (clerk/eval-cljs
- {:evaluator :cherry}
  '(defn emoji-picker
     {:async true}
     []
@@ -115,30 +108,26 @@
 
 ;; In the next block we call it:
 
-^::clerk/no-cache
 (clerk/with-viewer
-  {:evaluator :cherry
-   :render-fn '(fn [_]
-                 [nextjournal.clerk.render/render-promise
-                  (emoji-picker)])}
-  nil)
+  '(fn [_]
+     [nextjournal.clerk.render/render-promise
+      (emoji-picker)]) nil)
 
 ;; ## Macros
 
-^::clerk/no-cache
 (clerk/eval-cljs
- {:evaluator :cherry}
  '(defn clicks []
     (reagent.core/with-let [!s (reagent.core/atom 0)]
-      [:button {:on-click (fn []
-                            (swap! !s inc))}
+      [:button.bg-teal-500.hover:bg-teal-700.text-white.font-bold.py-2.px-4.rounded.rounded-full.font-sans
+       {:on-click (fn [] (swap! !s inc))}
        "Clicks: " @!s])))
 
-^::clerk/no-cache
-(clerk/with-viewer
-  {:evaluator :cherry
-   :render-fn '(fn [_]
-                 [clicks])
-   }
-  nil)
+(clerk/with-viewer '(fn [_] (this-as this [clicks])) nil)
+
+;; ## Evaluator option as form metadata
+^{::clerk/visibility {:code :hide :result :hide} ::clerk/no-cache true}
+(clerk/add-viewers! [(assoc viewer/code-block-viewer :transform-fn (viewer/update-val :text))])
 
+;; Test reverting the default option via metadata:
+^{::clerk/render-evaluator :sci}
+(clerk/with-viewer '(fn [_] (load-string "[:h1 \"Ahoi\"]")) nil)

src/nextjournal/clerk/builder.clj

@@ -22,6 +22,7 @@
          "notebooks/onwards.md"]
         (map #(str "notebooks/" % ".clj"))
         ["cards"
+         "cherry"
          "controlling_width"
          "docs"
          "document_linking"
@@ -63,8 +64,7 @@
          "viewers/plotly"
          "viewers/table"
          "viewers/tex"
-         "viewers/vega"
-         "cherry"]))
+         "viewers/vega"]))
 
 
 (defn strip-index [path]

src/nextjournal/clerk/cherry_env.cljs

@@ -21,6 +21,7 @@
             [sci.configs.reagent.reagent :as sci.configs.reagent]))
 
 (cherry/preserve-ns 'cljs.core)
+(cherry/preserve-ns 'nextjournal.clerk.viewer)
 (cherry/preserve-ns 'nextjournal.clerk.render)
 (cherry/preserve-ns 'nextjournal.clerk.render.code)
 (cherry/preserve-ns 'nextjournal.clerk.render.hooks)

src/nextjournal/clerk/parser.cljc

@@ -54,7 +54,8 @@
     :nextjournal.clerk/css-class
     :nextjournal.clerk/visibility
     :nextjournal.clerk/opts
-    :nextjournal.clerk/width})
+    :nextjournal.clerk/width
+    :nextjournal.clerk/render-evaluator})
 
 (defn settings-marker? [form]
   (boolean (and (map? form)

src/nextjournal/clerk/viewer.cljc

@@ -76,13 +76,13 @@
 
 #?(:clj
    (defmethod print-method ViewerFn [v ^java.io.Writer w]
-     (.write w (str "#viewer-fn" (when (= :cherry (:evaluator v))
+     (.write w (str "#viewer-fn" (when (= :cherry (:render-evaluator v))
                                    "/cherry")
                     " " (pr-str (:form v))))))
 
 #?(:clj
    (defmethod print-method ViewerEval [v ^java.io.Writer w]
-     (.write w (str "#viewer-eval" (when (= :cherry (:evaluator v))
+     (.write w (str "#viewer-eval" (when (= :cherry (:render-evaluator v))
                                      "/cherry")
                     " " (pr-str (:form v)))))
    :cljs
@@ -869,6 +869,7 @@
 
 (defn ->opts [wrapped-value]
   (select-keys wrapped-value [:nextjournal/budget :nextjournal/css-class :nextjournal/width :nextjournal/opts
+                              :nextjournal/render-evaluator
                               :!budget :store!-wrapped-value :present-elision-fn :path :offset]))
 
 (defn inherit-opts [{:as wrapped-value :nextjournal/keys [viewers]} value path-segment]
@@ -1349,23 +1350,28 @@
 
 (declare assign-closing-parens)
 
-(defn process-render-fn [{:as viewer :keys [render-fn evaluator]}]
+(defn process-render-fn [{:as viewer :keys [render-fn render-evaluator]}]
   (cond-> viewer
     (and render-fn (not (viewer-fn? render-fn)))
     (update :render-fn (fn [rf]
                          (assoc (->viewer-fn rf)
-                                :evaluator (or evaluator :sci))))))
+                                :render-evaluator (or render-evaluator :sci))))))
 
 (defn hash-sha1 [x]
   #?(:clj (analyzer/valuehash :sha1 x)
      :cljs (let [hasher (goog.crypt.Sha1.)]
              (.update hasher (goog.crypt/stringToUtf8ByteArray (pr-str x)))
              (.digest hasher))))
 
-(defn process-viewer [viewer]
+(defn process-viewer [viewer {:nextjournal/keys [render-evaluator]}]
+  ;; TODO: drop wrapped-value arg here and handle this elsewhere by
+  ;; passing modified viewer stack
+  ;; `(clerk/update-viewers viewers {:render-fn #(assoc % :render-evaluator :cherry)})`
   (if-not (map? viewer)
     viewer
     (-> viewer
+        (cond-> (and (not (:render-evaluator viewer)) render-evaluator)
+          (assoc :render-evaluator render-evaluator))
         (dissoc :pred :transform-fn :update-viewers-fn)
         (as-> viewer (assoc viewer :hash (hash-sha1 viewer)))
         (process-render-fn))))
@@ -1380,7 +1386,7 @@
   (cond-> (-> wrapped-value
               (select-keys processed-keys)
               (dissoc :nextjournal/budget)
-              (update :nextjournal/viewer process-viewer))
+              (update :nextjournal/viewer process-viewer wrapped-value))
     present-elision-fn (vary-meta assoc :present-elision-fn present-elision-fn)))
 
 #_(process-wrapped-value (apply-viewers 42))
@@ -1699,37 +1705,49 @@
   ([x] (print-hide-result-deprecation-warning) (with-viewer hide-result-viewer {} x))
   ([viewer-opts x] (print-hide-result-deprecation-warning) (with-viewer hide-result-viewer viewer-opts x)))
 
-
-(defn eval-cljs [opts & forms]
-  ;; because ViewerEval's are evaluated at read time we can no longer
-  ;; check after read if there was any in the doc. Thus we set the
-  ;; `:nextjournal.clerk/remount` attribute to a hash of the code (so
-  ;; it changes when the code changes and shows up in the doc patch.
-  ;; TODO: simplify, maybe by applying Clerk's analysis to the cljs
-  ;; part as well
-  (let [[opts forms] (if (map? opts)
-                       [opts forms]
-                       [nil (cons opts forms)])]
-    (with-viewer (assoc viewer-eval-viewer :nextjournal.clerk/remount (hash-sha1 forms))
-      (if (= :cherry (:evaluator opts))
-        (assoc (->viewer-eval
-                `(do ~@forms))
-               :evaluator (:evaluator opts))
-        (->viewer-eval
-         `(binding [*ns* *ns*]
-            ~@forms))))))
+(defn ^:private rewrite-for-cherry
+  "Takes a form as generated by `eval-cljs` or `eval-cljs-str` and rewrites it for cherry compatibility meaning:
+  * dropping the `(binding [*ns* *ns*] ,,,)`
+  * rewriting `load-string`"
+  [form]
+  (let [form-without-binding (last form)]
+    (if (and (list? form-without-binding) (= 'load-string (first form-without-binding)))
+      (list 'js/global_eval (list 'nextjournal.clerk.cherry-env/cherry-compile-string (second form-without-binding)))
+      form-without-binding)))
+
+#_(rewrite-for-cherry '(binding [*ns* *ns*] (prn :foo)))
+#_(rewrite-for-cherry '(binding [*ns* *ns*] (load-string "(prn :foo)")))
+
+(defn ^:private maybe-rewrite-cljs-form-for-cherry [{:as wrapped-value :nextjournal/keys [render-evaluator]}]
+  (cond-> wrapped-value
+    (= :cherry render-evaluator)
+    (update :nextjournal/value
+            (fn [{:as viewer-eval :keys [form]}]
+              (-> viewer-eval
+                  (assoc :render-evaluator render-evaluator)
+                  (update :form rewrite-for-cherry))))))
+
+(defn eval-cljs
+  ([form] (eval-cljs {} form))
+  ([viewer-opts form]
+   ;; because ViewerEval's are evaluated at read time we can no longer
+   ;; check after read if there was any in the doc. Thus we set the
+   ;; `:nextjournal.clerk/remount` attribute to a hash of the code (so
+   ;; it changes when the code changes and shows up in the doc patch.
+   ;; TODO: simplify, maybe by applying Clerk's analysis to the cljs
+   ;; part as well
+   (with-viewer (-> viewer-eval-viewer
+                    (update :transform-fn comp maybe-rewrite-cljs-form-for-cherry)
+                    (assoc :nextjournal.clerk/remount (hash-sha1 form)))
+     viewer-opts
+     (->viewer-eval (list 'binding '[*ns* *ns*] form)))))
 
 (defn eval-cljs-str
-  ([code-string] (eval-cljs-str nil code-string))
+  ([code-string] (eval-cljs-str {} code-string))
   ([opts code-string]
    ;; NOTE: this relies on implementation details on how SCI code is evaluated
    ;; and will change in a future version of Clerk
-   (if (= :cherry (:evaluator opts))
-     (assoc (->viewer-eval
-             `(let [prog#  (nextjournal.clerk.cherry-env/cherry-compile-string ~code-string)]
-                (js/global_eval prog#)))
-            :evaluator :cherry)
-     (eval-cljs (list 'load-string code-string)))))
+   (eval-cljs opts (list 'load-string code-string))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; examples

ui_tests/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
     "nbb": "^1.1.147",
-    "playwright": "^1.19.1"
+    "playwright": "^1.33.0"
   }
 }