diff --git a/CHANGELOG.md b/CHANGELOG.md index f8f244c..c4f244a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Change Log All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/). +## [4-beta7] - TBD +- added `*options*` as an alternative to passing options per form + ## [4-beta6] - 2024-08-08 - fixed docstring for `:kind/image` (fixing #16) diff --git a/dev/scicloj/kindly/gen.clj b/dev/scicloj/kindly/gen.clj index 7cfdcd8..ca5bb6a 100644 --- a/dev/scicloj/kindly/gen.clj +++ b/dev/scicloj/kindly/gen.clj @@ -23,15 +23,9 @@ (str (name k) ": " (escape v)))) "\"" \newline " ([] " kind-kw ")" \newline - (if (:hide-code attrs) - (str - " ([value] (hide-code (attach-kind-to-value value " kind-kw "))) ") - (str - " ([value] (attach-kind-to-value value " kind-kw ")) ")) - (str \newline - " ([value options] (" (symbol "scicloj.kindly.v4.kind" (name kind)) " (vary-meta value assoc :kindly/options options)))") - ")" \newline))) - + " ([value] (scicloj.kindly.v4.kind/" kind " value nil))" \newline + " ([value options] (kindly/attach-meta-to-value value {:kindly/kind " kind-kw " :kindly/options options})))" + \newline))) (defn kind-fns [all-kinds] (str/join (str \newline \newline) @@ -50,7 +44,7 @@ (defn kind-ns [all-kinds] (str "(ns scicloj.kindly.v4.kind \"Kinds for visualization\" - (:require [scicloj.kindly.v4.api :refer [attach-kind-to-value hide-code]]) + (:require [scicloj.kindly.v4.api :as kindly]) (:refer-clojure :exclude " (excludes all-kinds) ")) " (kind-fns all-kinds) \newline)) @@ -73,6 +67,16 @@ (str "(ns scicloj.kindly.v4.api \"See the kind namespace\") +(def ^:dynamic *options* + \"Visualization tools take options in the following priority: + + 1. options on the metadata of a form or value + 3. kind specific options found in the `:kinds` map of this dynamic var + 2. options found in this dynamic var + + See the kindly documentation for valid options.\" + nil) + (defn attach-meta-to-value [value m] (if (instance? clojure.lang.IObj value) @@ -88,9 +92,8 @@ ([value] (hide-code value true)) ([value bool] - (if (instance? clojure.lang.IObj value) - (vary-meta value assoc :kindly/hide-code true) - (hide-code [value])))) + ;; Will change when Clay is updated + (attach-meta-to-value value {:kindly/hide-code bool}))) (defn consider \"Add metadata to a given value. diff --git a/src/scicloj/kindly/v4/api.cljc b/src/scicloj/kindly/v4/api.cljc index 90c8d29..80b37a8 100644 --- a/src/scicloj/kindly/v4/api.cljc +++ b/src/scicloj/kindly/v4/api.cljc @@ -1,6 +1,16 @@ (ns scicloj.kindly.v4.api "See the kind namespace") +(def ^:dynamic *options* + "Visualization tools take options in the following priority: + + 1. options on the metadata of a form or value + 3. kind specific options found in the `:kinds` map of this dynamic var + 2. options found in this dynamic var + + See the kindly documentation for valid options." + nil) + (defn attach-meta-to-value [value m] (if (instance? clojure.lang.IObj value) @@ -16,9 +26,8 @@ ([value] (hide-code value true)) ([value bool] - (if (instance? clojure.lang.IObj value) - (vary-meta value assoc :kindly/hide-code true) - (hide-code [value])))) + ;; Will change when Clay is updated + (attach-meta-to-value value {:kindly/hide-code bool}))) (defn consider "Add metadata to a given value. diff --git a/src/scicloj/kindly/v4/kind.cljc b/src/scicloj/kindly/v4/kind.cljc index c964f0f..9609024 100644 --- a/src/scicloj/kindly/v4/kind.cljc +++ b/src/scicloj/kindly/v4/kind.cljc @@ -1,6 +1,6 @@ (ns scicloj.kindly.v4.kind "Kinds for visualization" - (:require [scicloj.kindly.v4.api :refer [attach-kind-to-value hide-code]]) + (:require [scicloj.kindly.v4.api :as kindly]) (:refer-clojure :exclude [test seq vector set map fn])) ;; ## simple behaviours @@ -9,15 +9,15 @@ "display-as: a formatted string example: {:key1 \"value1\", :key2 \"value2\"}" ([] :kind/pprint) - ([value] (attach-kind-to-value value :kind/pprint)) - ([value options] (scicloj.kindly.v4.kind/pprint (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/pprint value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/pprint :kindly/options options}))) (defn hidden "display-as: do not display example: [\"SECRET\"]" ([] :kind/hidden) - ([value] (attach-kind-to-value value :kind/hidden)) - ([value options] (scicloj.kindly.v4.kind/hidden (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/hidden value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/hidden :kindly/options options}))) ;; ## web dev @@ -26,22 +26,22 @@ example: [\"SECRET\"]" "display-as: HTML example:

Hello >World

" ([] :kind/html) - ([value] (attach-kind-to-value value :kind/html)) - ([value options] (scicloj.kindly.v4.kind/html (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/html value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/html :kindly/options options}))) (defn hiccup "display-as: HTML example: [:div [:h3 \"Hello \" [:em \"World\"]]]" ([] :kind/hiccup) - ([value] (attach-kind-to-value value :kind/hiccup)) - ([value options] (scicloj.kindly.v4.kind/hiccup (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/hiccup value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/hiccup :kindly/options options}))) (defn reagent "display-as: A reagent component inside HTML example: [(fn [] [:button {:on-click (fn [ev] (js/alert \"You pressed it\"))} \"Press me\"])]" ([] :kind/reagent) - ([value] (attach-kind-to-value value :kind/reagent)) - ([value options] (scicloj.kindly.v4.kind/reagent (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/reagent value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/reagent :kindly/options options}))) ;; ## data visualization formats @@ -50,29 +50,29 @@ example: [(fn [] [:button {:on-click (fn [ev] (js/alert \"You pressed it\"))} \" "display-as: a Markdown string example: ## Hello *World*" ([] :kind/md) - ([value] (attach-kind-to-value value :kind/md)) - ([value options] (scicloj.kindly.v4.kind/md (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/md value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/md :kindly/options options}))) (defn tex "display-as: a TeX formula example: x^2" ([] :kind/tex) - ([value] (attach-kind-to-value value :kind/tex)) - ([value options] (scicloj.kindly.v4.kind/tex (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/tex value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/tex :kindly/options options}))) (defn code "display-as: a piece syntax highlighted Clojure code example: (+ 1 2)" ([] :kind/code) - ([value] (attach-kind-to-value value :kind/code)) - ([value options] (scicloj.kindly.v4.kind/code (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/code value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/code :kindly/options options}))) (defn edn "display-as: a piece syntax highlighted EDN structure example: {:x [1 2 3]}" ([] :kind/edn) - ([value] (attach-kind-to-value value :kind/edn)) - ([value options] (scicloj.kindly.v4.kind/edn (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/edn value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/edn :kindly/options options}))) (defn vega "display-as: a chart @@ -80,8 +80,8 @@ example: {:description \"A basic bar chart example, with value labels shown upon docs: https://vega.github.io/vega/docs/ json-schema: https://vega.github.io/schema/vega/v5.json" ([] :kind/vega) - ([value] (attach-kind-to-value value :kind/vega)) - ([value options] (scicloj.kindly.v4.kind/vega (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/vega value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/vega :kindly/options options}))) (defn vega-lite "display-as: VegaLite chart @@ -89,16 +89,16 @@ example: {:description \"A simple bar chart with embedded data.\", :data {:value docs: https://vega.github.io/vega-lite/docs/ json-schema: https://vega.github.io/schema/vega-lite/v5.json" ([] :kind/vega-lite) - ([value] (attach-kind-to-value value :kind/vega-lite)) - ([value options] (scicloj.kindly.v4.kind/vega-lite (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/vega-lite value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/vega-lite :kindly/options options}))) (defn echarts "display-as: a chart example: [[\"a\" \"b\" \"c\" \"d\"] [1 2 3 4]] docs: https://echarts.apache.org/en/option.html" ([] :kind/echarts) - ([value] (attach-kind-to-value value :kind/echarts)) - ([value options] (scicloj.kindly.v4.kind/echarts (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/echarts value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/echarts :kindly/options options}))) (defn cytoscape "display-as: a graph @@ -106,8 +106,8 @@ example: {:nodes #{1 4 3 2 5}, :edges #{[4 3] [4 2] [1 2] [3 5]}} docs: https://js.cytoscape.org/#notation/elements-json json-schema: https://raw.githubusercontent.com/AZaitzeff/cytoscape_js_schema/main/cytoscape_schema.json" ([] :kind/cytoscape) - ([value] (attach-kind-to-value value :kind/cytoscape)) - ([value options] (scicloj.kindly.v4.kind/cytoscape (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/cytoscape value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/cytoscape :kindly/options options}))) (defn plotly "display-as: a plot @@ -115,36 +115,36 @@ example: [{:x [1 2 3 4 5], :y [1 2 4 8 16]}] docs: https://plotly.com/javascript/getting-started/ json-schema: https://plotly.com/chart-studio-help/json-chart-schema/" ([] :kind/plotly) - ([value] (attach-kind-to-value value :kind/plotly)) - ([value options] (scicloj.kindly.v4.kind/plotly (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/plotly value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/plotly :kindly/options options}))) (defn htmlwidgets-plotly "display-as: a plot rendered by the JS client side of Plotly R docs: https://plotly.com/r/" ([] :kind/htmlwidgets-plotly) - ([value] (attach-kind-to-value value :kind/htmlwidgets-plotly)) - ([value options] (scicloj.kindly.v4.kind/htmlwidgets-plotly (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/htmlwidgets-plotly value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/htmlwidgets-plotly :kindly/options options}))) (defn htmlwidgets-ggplotly "display-as: a plot rendered by the JS client side of Plotly R, specifically for a ggplotly plot docs: https://plotly.com/ggplot2/" ([] :kind/htmlwidgets-ggplotly) - ([value] (attach-kind-to-value value :kind/htmlwidgets-ggplotly)) - ([value options] (scicloj.kindly.v4.kind/htmlwidgets-ggplotly (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/htmlwidgets-ggplotly value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/htmlwidgets-ggplotly :kindly/options options}))) (defn video "display-as: an embedded video example: {:youtube-id \"MXHI4mgfVk8\"}" ([] :kind/video) - ([value] (attach-kind-to-value value :kind/video)) - ([value options] (scicloj.kindly.v4.kind/video (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/video value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/video :kindly/options options}))) (defn observable "display-as: Observable visualizations docs: https://observablehq.com/" ([] :kind/observable) - ([value] (attach-kind-to-value value :kind/observable)) - ([value options] (scicloj.kindly.v4.kind/observable (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/observable value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/observable :kindly/options options}))) (defn highcharts "display-as: a chart @@ -152,8 +152,8 @@ example: {:title {:text \"Line chart\"}, :subtitle {:text \"By Job Category\"}, docs: https://www.highcharts.com/docs/index json-schema: " ([] :kind/highcharts) - ([value] (attach-kind-to-value value :kind/highcharts)) - ([value options] (scicloj.kindly.v4.kind/highcharts (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/highcharts value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/highcharts :kindly/options options}))) ;; ## specific types @@ -162,23 +162,23 @@ json-schema: " "display-as: an image example: At the moment, java BufferedImage objects are supported." ([] :kind/image) - ([value] (attach-kind-to-value value :kind/image)) - ([value options] (scicloj.kindly.v4.kind/image (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/image value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/image :kindly/options options}))) (defn dataset "display-as: a table example: (->> (System/getProperties) (map (fn [[k v]] {:k k, :v (apply str (take 40 (str v)))})) (tech.v3.dataset/->>dataset {:dataset-name \"My Truncated System Properties\"})) docs: https://github.com/techascent/tech.ml.dataset" ([] :kind/dataset) - ([value] (attach-kind-to-value value :kind/dataset)) - ([value options] (scicloj.kindly.v4.kind/dataset (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/dataset value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/dataset :kindly/options options}))) (defn smile-model "display-as: the `str` value should be displayesd as code docs: https://haifengl.github.io/" ([] :kind/smile-model) - ([value] (attach-kind-to-value value :kind/smile-model)) - ([value options] (scicloj.kindly.v4.kind/smile-model (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/smile-model value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/smile-model :kindly/options options}))) ;; ## clojure specific @@ -187,15 +187,15 @@ docs: https://haifengl.github.io/" "display-as: the name of a var example: (def testvar 100)" ([] :kind/var) - ([value] (attach-kind-to-value value :kind/var)) - ([value options] (scicloj.kindly.v4.kind/var (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/var value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/var :kindly/options options}))) (defn test "display-as: success or failure example: (deftest unity-test (is (= 1 1)))" ([] :kind/test) - ([value] (attach-kind-to-value value :kind/test)) - ([value options] (scicloj.kindly.v4.kind/test (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/test value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/test :kindly/options options}))) ;; ## plain structures @@ -204,29 +204,29 @@ example: (deftest unity-test (is (= 1 1)))" "display-as: a sequence example: (range 5)" ([] :kind/seq) - ([value] (attach-kind-to-value value :kind/seq)) - ([value options] (scicloj.kindly.v4.kind/seq (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/seq value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/seq :kindly/options options}))) (defn vector "display-as: a sequence example: (vec (range 5))" ([] :kind/vector) - ([value] (attach-kind-to-value value :kind/vector)) - ([value options] (scicloj.kindly.v4.kind/vector (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/vector value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/vector :kindly/options options}))) (defn set "display-as: a bag example: (set (range 5))" ([] :kind/set) - ([value] (attach-kind-to-value value :kind/set)) - ([value options] (scicloj.kindly.v4.kind/set (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/set value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/set :kindly/options options}))) (defn map "display-as: associated values example: {:key1 \"value1\", :key2 \"value2\"}" ([] :kind/map) - ([value] (attach-kind-to-value value :kind/map)) - ([value options] (scicloj.kindly.v4.kind/map (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/map value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/map :kindly/options options}))) ;; ## other recursive structures @@ -235,15 +235,15 @@ example: {:key1 \"value1\", :key2 \"value2\"}" "display-as: a table example: {:headers [:a], :rows [{:a 1} {:a 2}]}" ([] :kind/table) - ([value] (attach-kind-to-value value :kind/table)) - ([value options] (scicloj.kindly.v4.kind/table (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/table value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/table :kindly/options options}))) (defn portal "display-as: portal example: {:key1 \"value1\", :key2 [:div [:h3 \"Hello \" [:em \"World\"]]]}" ([] :kind/portal) - ([value] (attach-kind-to-value value :kind/portal)) - ([value options] (scicloj.kindly.v4.kind/portal (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/portal value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/portal :kindly/options options}))) ;; ## meta kinds @@ -252,20 +252,20 @@ example: {:key1 \"value1\", :key2 [:div [:h3 \"Hello \" [:em \"World\"]]]}" "display-as: one toplevel context with a sequential value considered as many toplevel contexts of various kinds example: [[\"**hello**\"] [:p [:b \"hello\"]]]" ([] :kind/fragment) - ([value] (attach-kind-to-value value :kind/fragment)) - ([value options] (scicloj.kindly.v4.kind/fragment (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/fragment value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/fragment :kindly/options options}))) (defn fn "display-as: the evaluation of the given function and arguments example: [+ 2 3]" ([] :kind/fn) - ([value] (attach-kind-to-value value :kind/fn)) - ([value options] (scicloj.kindly.v4.kind/fn (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/fn value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/fn :kindly/options options}))) (defn test-last "display-as: invisible (both code and value), but generates a test example: [> 9]" ([] :kind/test-last) - ([value] (attach-kind-to-value value :kind/test-last)) - ([value options] (scicloj.kindly.v4.kind/test-last (vary-meta value assoc :kindly/options options)))) + ([value] (scicloj.kindly.v4.kind/test-last value nil)) + ([value options] (kindly/attach-meta-to-value value {:kindly/kind :kind/test-last :kindly/options options})))