From 4baba2b93d4752c4b825bb1fa23c0092a8ba3ea8 Mon Sep 17 00:00:00 2001 From: Camilo Roca Date: Mon, 27 Jun 2016 01:24:55 +0200 Subject: [PATCH 1/4] docstrings added to most eval-related behaviors --- src/lt/plugins/clojure.cljs | 97 +++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 19 deletions(-) diff --git a/src/lt/plugins/clojure.cljs b/src/lt/plugins/clojure.cljs index aaee789..ea4636b 100644 --- a/src/lt/plugins/clojure.cljs +++ b/src/lt/plugins/clojure.cljs @@ -68,6 +68,7 @@ (run-local-server (clients/client! :nrepl.client)))))) (behavior ::on-eval.clj + :desc "Clojure: Eval editor content" :triggers #{:eval} :reaction (fn [editor] (object/raise clj-lang :eval! {:origin editor @@ -75,6 +76,7 @@ :print-length (object/raise-reduce editor :clojure.print-length+ nil) :code (watches/watched-range editor nil nil nil))}))) (behavior ::on-eval.cljs + :desc "Clojurescript: Eval editor content" :triggers #{:eval} :reaction (fn [editor] (object/raise clj-lang :eval! {:origin editor @@ -87,6 +89,7 @@ "(set! js/COMPILED js/COMPILED-temp)"))}))) (behavior ::on-eval.one + :desc "Clojure(script): Eval a single form in editor" :triggers #{:eval.one} :reaction (fn [editor] (let [code (watches/watched-range editor nil nil nil) @@ -103,12 +106,17 @@ :info info})))) -(defn fill-placeholders [editor exp] +(defn fill-placeholders + "replace editor-selection-flags (placeholders) inside exp with the currently + selected code in the editor" + [editor exp] (-> exp (string/replace "__SELECTION*__" (pr-str (ed/selection editor))) (string/replace "__SELECTION__" (ed/selection editor)))) (behavior ::on-eval.custom + :desc "Clojure(script): Eval a form that has been wrapped by a custom code, + thus changing the result. Ilustrative example: (eval (time form)) instead of (eval form)" :triggers #{:eval.custom} :reaction (fn [editor exp opts] (let [code (fill-placeholders editor exp) @@ -176,6 +184,8 @@ (= 'lighttable (second (reader/read-string (:content (files/open-sync project-file)))))))) (behavior ::eval! + :desc "Clojure(script): Send event information for evaluation to the appropiate nREPL + or LightTable-UI client" :triggers #{:eval!} :reaction (fn [this event] (let [{:keys [info origin]} event @@ -263,6 +273,8 @@ (notifos/done-working))) (behavior ::cljs-result + :desc "Clojurescript: Receive a cljs result and dispatches it according + to its appropiate result type. Defaults to :inline" :triggers #{:editor.eval.cljs.result} :reaction (fn [obj res] (notifos/done-working) @@ -270,6 +282,7 @@ ev (->dottedkw :editor.eval.cljs.result type)] (object/raise obj ev res)))) +;; this is probably to handle find and replace source code in a CLJS editor (behavior ::cljs-result.replace :triggers #{:editor.eval.cljs.result.replace} :reaction (fn [obj res] @@ -277,6 +290,7 @@ (notifos/set-msg! err {:class "error"}) (ed/replace-selection obj (unescape-unicode (or (:result res) "")))))) +;; this is probably to handle result without any output. For example: 'Compilation succeded', 'nREPL connected' and so on (behavior ::cljs-result.statusbar :triggers #{:editor.eval.cljs.result.statusbar} :reaction (fn [obj res] @@ -285,6 +299,8 @@ (notifos/set-msg! (unescape-unicode (or (:result res) "")) {:class "result"})))) (behavior ::cljs-result.inline + :desc "Clojurescript: Takes a cljs-code evaluation-result and dispatches it as + an exception or as an inline-result" :triggers #{:editor.eval.cljs.result.inline} :reaction (fn [obj res] (let [meta (:meta res) @@ -294,6 +310,7 @@ (object/raise obj :editor.eval.cljs.exception res :passed) (object/raise obj :editor.result (unescape-unicode (or (:result res) "")) loc))))) +;; this is probably the same as ::cljs-result.inline but put the result widget somewhere else (behavior ::cljs-result.inline-at-cursor :triggers #{:editor.eval.cljs.result.inline-at-cursor} :reaction (fn [obj res] @@ -316,6 +333,8 @@ :meta meta}))))) (behavior ::clj-result + :desc "Clojure: Receive a clj result and dispatches it according + to its appropiate result type. Defaults to :inline" :triggers #{:editor.eval.clj.result} :reaction (fn [obj res] (notifos/done-working) @@ -323,6 +342,7 @@ ev (->dottedkw :editor.eval.clj.result type)] (object/raise obj ev res)))) +;; this is probably to handle find and replace source code in a CLJ editor (behavior ::clj-result.replace :triggers #{:editor.eval.clj.result.replace} :reaction (fn [obj res] @@ -334,6 +354,7 @@ (notifos/set-msg! (:result res) {:class "error"}) (ed/replace-selection obj (:result result)))))) +;; this is probably to handle result without any output. For example: 'Compilation succeded', 'nREPL connected' and so on (behavior ::clj-result.statusbar :triggers #{:editor.eval.clj.result.statusbar} :reaction (fn [obj res] @@ -346,6 +367,8 @@ (notifos/set-msg! (:result result) {:class "result"}))))) (behavior ::clj-result.inline + :desc "Clojurescript: Takes a cljs-code evaluation-result and dispatches it as + an exception or as an inline-result" :triggers #{:editor.eval.clj.result.inline} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -354,9 +377,9 @@ :start-line (dec (:line meta))}]] (if (:stack result) (object/raise obj :editor.eval.clj.exception result :passed) - (do - (object/raise obj :editor.result (:result result) loc)))))) + (object/raise obj :editor.result (:result result) loc))))) +;; this is probably the same as ::clj-result.inline but put the result widget somewhere else (behavior ::clj-result.inline-at-cursor :triggers #{:editor.eval.clj.result.inline-at-cursor} :reaction (fn [obj res] @@ -366,8 +389,7 @@ :start-line (-> res :meta :start)}]] (if (:stack result) (object/raise obj :editor.eval.clj.exception result :passed) - (do - (object/raise obj :editor.result (:result result) loc)))))) + (object/raise obj :editor.result (:result result) loc))))) (behavior ::clj-result.return :triggers #{:editor.eval.clj.result.return} @@ -382,6 +404,9 @@ :meta meta}))))) (behavior ::clj-exception + :desc "Clojure: Takes the result of evaling a clj form which resulted in an + exception. Displays a message in the status bar and an exception widget + with the stacktrace" :triggers #{:editor.eval.clj.exception} :reaction (fn [obj res passed?] (when-not passed? @@ -390,10 +415,12 @@ loc {:line (dec (:end-line meta)) :ch (:end-column meta 0) :start-line (dec (:line meta 1))}] (notifos/set-msg! (:result res) {:class "error"}) - (object/raise obj :editor.exception (:stack res) loc)) - )) + (object/raise obj :editor.exception (:stack res) loc)))) (behavior ::cljs-exception + :desc "Clojurescript: Takes the result of evaling a cljs form which resulted in an + exception. Displays a message in the status bar and an exception widget with + the stacktrace" :triggers #{:editor.eval.cljs.exception} :reaction (fn [obj res passed?] (when-not passed? @@ -413,9 +440,10 @@ msg "Unknown error")] (notifos/set-msg! msg {:class "error"}) - (object/raise obj :editor.exception stack loc)) - )) + (object/raise obj :editor.exception stack loc)))) +;; this is probably to avoid returning (print expr) as an inline result, instead sends it +;; to the console (behavior ::eval-print :triggers #{:editor.eval.clj.print} :reaction (fn [this str] @@ -424,9 +452,10 @@ :line (when (object/has-tag? this :nrepl.client) "stdout") :id (:id str) - :content (:out str)} - )))) + :content (:out str)})))) +;; this is probably to avoid returning (print expr) as an inline result, instead sends it +;; to the console but as an error element (red css color and so) (behavior ::eval-print-err :triggers #{:editor.eval.clj.print.err} :reaction (fn [this str] @@ -517,18 +546,33 @@ ;; watches ;;**************************************************** +;; For more information on watches check +;; Original anouncement: https://groups.google.com/forum/#!msg/light-table-discussion/lyFzPGI2XMs/ec8T1OUPvMsJ +;; blog posts: http://scattered-thoughts.net/blog/2014/01/27/were-not-even-trying/?utm_source=dlvr.it&utm_medium=twitter +;; https://medium.com/@zindlerb/guide-to-light-table-watches-fad560f698d3#.oqwq991sx +;; fancy Rolex watches plugin: https://groups.google.com/forum/#!topic/light-table-discussion/NQWGC0vVHMY + (behavior ::cljs-watch-src + :desc "Clojurescript: wraps the watched source code with a call to 'js/lttools.watch' to catch + its result and send it back to LightTable while continuing normal evaluation of an expression. + (Check the wrapping function for more information)" :triggers #{:watch.src+} :reaction (fn [editor cur meta src] (let [meta (assoc meta :ev :editor.eval.cljs.watch)] (str "(js/lttools.watch " src " (clj->js " (pr-str meta) "))")))) (behavior ::clj-watch-src + :desc "Clojure: wraps the watched source code with a call to 'lighttable.nrepl.eval/watch' to catch + its result and send it back to LightTable while continuing normal evaluation of an expression. + (Check the wrapping function for more information)" :triggers #{:watch.src+} :reaction (fn [editor cur meta src] (str "(lighttable.nrepl.eval/watch " src " " (pr-str meta) ")"))) -(defn fill-watch-placeholders [exp src meta watch] +(defn fill-watch-placeholders + "replace editor-selection-flags (placeholders) for custom watches inside exp + with the src-code to be watched" + [exp src meta watch] (-> exp (string/replace "\n" " ") (string/replace "__SELECTION*__" (pr-str src)) @@ -537,12 +581,18 @@ (string/replace #"__\|(.*)\|__" watch))) (behavior ::cljs-watch-custom-src + :desc "Clojurescript: prepare exp for watching by filling its placeholders and wrapping + its watcher-code with custom call to :editor.eval.cljs.watch" :triggers #{:watch.custom.src+} :reaction (fn [editor cur meta opts src] - (let [watch (str "(js/lttools.raise " (:obj meta) " :editor.eval.cljs.watch {:meta " (pr-str (merge (dissoc opts :exp) meta)) " :result $1})")] + (let [watch (str "(js/lttools.raise " (:obj meta) + " :editor.eval.cljs.watch {:meta " (pr-str (merge (dissoc opts :exp) meta)) + " :result $1})")] (fill-watch-placeholders (:exp opts) src meta watch)))) (behavior ::clj-watch-custom-src + :desc "Clojure: prepare exp for watching by filling its placeholders and wrapping + its watcher-code with custom call to :editor.eval.cljs.watch" :triggers #{:watch.custom.src+} :reaction (fn [editor cur meta opts src] (let [wrapped (if (:verbatim opts) @@ -551,6 +601,7 @@ watch (str "(lighttable.nrepl.core/safe-respond-to " (:obj meta) " :editor.eval.clj.watch {:meta " (pr-str (merge (dissoc opts :exp) meta)) " :result " wrapped "})")] (fill-watch-placeholders (:exp opts) src meta watch)))) +;; this is probably to update the value of watches during evaluation of a form (behavior ::cljs-watch-result :triggers #{:editor.eval.cljs.watch} :reaction (fn [editor res] @@ -564,6 +615,7 @@ str-result (util/escape str-result)] (object/raise (:inline-result watch) :update! str-result))))) +;; this is probably to update the value of watches during evaluation of a form (behavior ::clj-watch-result :triggers #{:editor.eval.clj.watch} :reaction (fn [editor res] @@ -578,6 +630,8 @@ ;;**************************************************** (behavior ::clj-doc + :desc "Clojure: gets the symbol at the cursor position and request its + docstring from the nREPL" :triggers #{:editor.doc} :reaction (fn [editor] (let [token (find-symbol-at-cursor editor) @@ -593,8 +647,7 @@ :info info :origin editor :create try-connect}) - command info :only editor))) - )) + command info :only editor))))) (behavior ::print-clj-doc :triggers #{:editor.clj.doc} @@ -617,6 +670,8 @@ (assoc token-left :loc loc))))) (behavior ::cljs-doc + :desc "Clojurescript: gets the symbol at the cursor position and request its + docstring from the nREPL" :triggers #{:editor.doc} :reaction (fn [editor] (let [token (find-symbol-at-cursor editor) @@ -643,16 +698,20 @@ (object/raise editor :editor.doc.show! result))))) (behavior ::clj-doc-search + :desc "Clojure: Links the 'Search language docs' input-text on the sidebar + with a trigger to :docs.clj.search to retrieve all the documentation + on a user-input" :triggers #{:types+} :reaction (fn [this cur] - (conj cur {:label "clj" :trigger :docs.clj.search :file-types #{"Clojure"}}) - )) + (conj cur {:label "clj" :trigger :docs.clj.search :file-types #{"Clojure"}}))) (behavior ::cljs-doc-search + :desc "Clojurescript: Links the 'Search language docs' input-text on the sidebar + with a trigger to :docs.clj.search to retrieve all the documentation + on a user-input" :triggers #{:types+} :reaction (fn [this cur] - (conj cur {:label "cljs" :trigger :docs.cljs.search :file-types #{"ClojureScript"}}) - )) + (conj cur {:label "cljs" :trigger :docs.cljs.search :file-types #{"ClojureScript"}}))) ;;**************************************************** ;; autocomplete From fb2c4da34a670d1b410eca3b7212c7939ce0d1e6 Mon Sep 17 00:00:00 2001 From: Camilo Roca Date: Mon, 27 Jun 2016 01:24:02 +0200 Subject: [PATCH 2/4] docstrings added to 'clean-serialize' and 'watch' --- .../src/lighttable/nrepl/eval.clj | 21 ++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/lein-light-nrepl/src/lighttable/nrepl/eval.clj b/lein-light-nrepl/src/lighttable/nrepl/eval.clj index d006f12..249f502 100644 --- a/lein-light-nrepl/src/lighttable/nrepl/eval.clj +++ b/lein-light-nrepl/src/lighttable/nrepl/eval.clj @@ -53,7 +53,17 @@ (if (instance? clojure.lang.IObj thing) (meta thing))) -(defn clean-serialize [res & [opts]] +(defn clean-serialize + "stringify the result 'res' into a form appropiate to its type. Defaults to + using 'pr-str' for most types. + + Allowed options: + :print-length, restrict length of stringified results to it. Defaults to 1000 + :allow-var?, whether to return a var itself or its stringified version. + Defaults to nil + :result, whether to return an atom itself or its content. Defaults to nil + :verbatim, whether to return an string itself or its 'pr-str' version" + [res & [opts]] (binding [*print-length* (or (:print-length opts) *print-length* 1000)] (cond (fn? res) 'fn @@ -70,7 +80,9 @@ (and (string? res) (:verbatim opts)) res :else (pr-str res)))) -(defn truncate [v] +(defn truncate + "useless function. Same as 'identity'" + [v] v) (defn ->result [opts f] @@ -118,7 +130,10 @@ (str (reduce str "" (repeat (:start meta 0) "\n")) code))) -(defn watch [v meta] +(defn watch + "stringify result-value 'v' with pretty-print, sends it back to Lighttable + and returns the value itself to continue the evaling call" + [v meta] (let [ppv (with-out-str (pprint v)) data {:meta meta :result (subs ppv 0 (dec (count ppv)))}] (core/safe-respond-to (:obj meta) :editor.eval.clj.watch data)) From 78c530b11c5ea8da7f45e518e844f032980ab84b Mon Sep 17 00:00:00 2001 From: Camilo Roca Date: Wed, 6 Jul 2016 13:27:57 +0200 Subject: [PATCH 3/4] *.result.replace and statusbar behaviors' descriptions added. some desc simplified --- src/lt/plugins/clojure.cljs | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/src/lt/plugins/clojure.cljs b/src/lt/plugins/clojure.cljs index ea4636b..e362b40 100644 --- a/src/lt/plugins/clojure.cljs +++ b/src/lt/plugins/clojure.cljs @@ -282,16 +282,16 @@ ev (->dottedkw :editor.eval.cljs.result type)] (object/raise obj ev res)))) -;; this is probably to handle find and replace source code in a CLJS editor (behavior ::cljs-result.replace + :desc "Clojurescript: replace current selection with the result of an evaluation" :triggers #{:editor.eval.cljs.result.replace} :reaction (fn [obj res] (if-let [err (or (:stack res) (:ex res))] (notifos/set-msg! err {:class "error"}) (ed/replace-selection obj (unescape-unicode (or (:result res) "")))))) -;; this is probably to handle result without any output. For example: 'Compilation succeded', 'nREPL connected' and so on (behavior ::cljs-result.statusbar + :desc "Clojurescript: show the result of an evaluation on the statusbar" :triggers #{:editor.eval.cljs.result.statusbar} :reaction (fn [obj res] (if-let [err (or (:stack res) (:ex res))] @@ -299,7 +299,7 @@ (notifos/set-msg! (unescape-unicode (or (:result res) "")) {:class "result"})))) (behavior ::cljs-result.inline - :desc "Clojurescript: Takes a cljs-code evaluation-result and dispatches it as + :desc "Clojurescript: shows the result of an evaluation as an inline-widget. Dispatches it as an exception or as an inline-result" :triggers #{:editor.eval.cljs.result.inline} :reaction (fn [obj res] @@ -333,7 +333,7 @@ :meta meta}))))) (behavior ::clj-result - :desc "Clojure: Receive a clj result and dispatches it according + :desc "Clojure: Receive an eval! result and dispatches it according to its appropiate result type. Defaults to :inline" :triggers #{:editor.eval.clj.result} :reaction (fn [obj res] @@ -342,8 +342,8 @@ ev (->dottedkw :editor.eval.clj.result type)] (object/raise obj ev res)))) -;; this is probably to handle find and replace source code in a CLJ editor (behavior ::clj-result.replace + :desc "Clojure: replace current selection with the result of an evaluation" :triggers #{:editor.eval.clj.result.replace} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -354,8 +354,8 @@ (notifos/set-msg! (:result res) {:class "error"}) (ed/replace-selection obj (:result result)))))) -;; this is probably to handle result without any output. For example: 'Compilation succeded', 'nREPL connected' and so on (behavior ::clj-result.statusbar + :desc "Clojure: show the result of an evaluation on the statusbar" :triggers #{:editor.eval.clj.result.statusbar} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -367,8 +367,8 @@ (notifos/set-msg! (:result result) {:class "result"}))))) (behavior ::clj-result.inline - :desc "Clojurescript: Takes a cljs-code evaluation-result and dispatches it as - an exception or as an inline-result" + :desc "Clojure: displays the result of an eval! as an inline-widget. + Dispatches it as an exception or as an inline-result" :triggers #{:editor.eval.clj.result.inline} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -404,9 +404,8 @@ :meta meta}))))) (behavior ::clj-exception - :desc "Clojure: Takes the result of evaling a clj form which resulted in an - exception. Displays a message in the status bar and an exception widget - with the stacktrace" + :desc "Clojure: displays an inline widget with stacktrace information and + a summary in the statusbar" :triggers #{:editor.eval.clj.exception} :reaction (fn [obj res passed?] (when-not passed? From aa877860fde4a3bd64e14eb33d6b34f9c09ab19a Mon Sep 17 00:00:00 2001 From: Scott Bauer Date: Sat, 10 Dec 2016 20:43:25 -0500 Subject: [PATCH 4/4] Update docstrings to use :doc key. Various formatting changes too. --- .../src/lighttable/nrepl/eval.clj | 20 +-- src/lt/plugins/clojure.cljs | 118 +++++++++--------- 2 files changed, 70 insertions(+), 68 deletions(-) diff --git a/lein-light-nrepl/src/lighttable/nrepl/eval.clj b/lein-light-nrepl/src/lighttable/nrepl/eval.clj index 249f502..107ded3 100644 --- a/lein-light-nrepl/src/lighttable/nrepl/eval.clj +++ b/lein-light-nrepl/src/lighttable/nrepl/eval.clj @@ -54,15 +54,16 @@ (meta thing))) (defn clean-serialize - "stringify the result 'res' into a form appropiate to its type. Defaults to - using 'pr-str' for most types. + "Stringify the result `res` into a form appropiate to its type. Defaults to + using function `pr-str` for most types. Allowed options: - :print-length, restrict length of stringified results to it. Defaults to 1000 - :allow-var?, whether to return a var itself or its stringified version. - Defaults to nil - :result, whether to return an atom itself or its content. Defaults to nil - :verbatim, whether to return an string itself or its 'pr-str' version" + + - `:print-length` - Restricts length of stringified results to it. Defaults to 1000. + - `:allow-var?` - Whether to return a var itself or its stringified version. + Defaults to nil. + - `:result` - Whether to return an atom itself or its content. Defaults to nil. + - `:verbatim` - Whether to return an string itself or its 'pr-str' version." [res & [opts]] (binding [*print-length* (or (:print-length opts) *print-length* 1000)] (cond @@ -81,7 +82,6 @@ :else (pr-str res)))) (defn truncate - "useless function. Same as 'identity'" [v] v) @@ -131,8 +131,8 @@ code))) (defn watch - "stringify result-value 'v' with pretty-print, sends it back to Lighttable - and returns the value itself to continue the evaling call" + "Stringify result-value `v` with pretty-print, send it back to Light Table, + and then return the value itself to continue the evaling call." [v meta] (let [ppv (with-out-str (pprint v)) data {:meta meta :result (subs ppv 0 (dec (count ppv)))}] diff --git a/src/lt/plugins/clojure.cljs b/src/lt/plugins/clojure.cljs index e362b40..a9d7cdd 100644 --- a/src/lt/plugins/clojure.cljs +++ b/src/lt/plugins/clojure.cljs @@ -76,7 +76,7 @@ :print-length (object/raise-reduce editor :clojure.print-length+ nil) :code (watches/watched-range editor nil nil nil))}))) (behavior ::on-eval.cljs - :desc "Clojurescript: Eval editor content" + :desc "Clojure: Eval editor content" :triggers #{:eval} :reaction (fn [editor] (object/raise clj-lang :eval! {:origin editor @@ -89,7 +89,7 @@ "(set! js/COMPILED js/COMPILED-temp)"))}))) (behavior ::on-eval.one - :desc "Clojure(script): Eval a single form in editor" + :desc "Clojure: Eval a single form in editor" :triggers #{:eval.one} :reaction (fn [editor] (let [code (watches/watched-range editor nil nil nil) @@ -107,16 +107,20 @@ (defn fill-placeholders - "replace editor-selection-flags (placeholders) inside exp with the currently - selected code in the editor" + "Replace editor-selection-flags, that is `__SELECTION*__`, inside `exp` with the currently + selected code in `editor`." [editor exp] (-> exp (string/replace "__SELECTION*__" (pr-str (ed/selection editor))) (string/replace "__SELECTION__" (ed/selection editor)))) (behavior ::on-eval.custom - :desc "Clojure(script): Eval a form that has been wrapped by a custom code, - thus changing the result. Ilustrative example: (eval (time form)) instead of (eval form)" + :desc "Clojure: Eval a form that has been wrapped by custom code" + :doc "Example: + + ``` + (eval (time form)) ;; instead of (eval form) + ```" :triggers #{:eval.custom} :reaction (fn [editor exp opts] (let [code (fill-placeholders editor exp) @@ -176,7 +180,7 @@ (defn lighttable-ui-project? "Determine if path is part of a project that evals to LightTable's process - e.g. LightTable plugin or LightTable itself" + (i.e., LightTable plugin or LightTable itself)." [path] (or (files/walk-up-find path "plugin.edn") (files/walk-up-find path "plugin.json") @@ -184,8 +188,8 @@ (= 'lighttable (second (reader/read-string (:content (files/open-sync project-file)))))))) (behavior ::eval! - :desc "Clojure(script): Send event information for evaluation to the appropiate nREPL - or LightTable-UI client" + :desc "Clojure: Send event information for evaluation." + :doc "This event information goes to the appropriate nREPL or LightTable-UI client." :triggers #{:eval!} :reaction (fn [this event] (let [{:keys [info origin]} event @@ -273,8 +277,7 @@ (notifos/done-working))) (behavior ::cljs-result - :desc "Clojurescript: Receive a cljs result and dispatches it according - to its appropiate result type. Defaults to :inline" + :desc "Clojure: Receive a cljs result and dispatch it" :triggers #{:editor.eval.cljs.result} :reaction (fn [obj res] (notifos/done-working) @@ -283,7 +286,7 @@ (object/raise obj ev res)))) (behavior ::cljs-result.replace - :desc "Clojurescript: replace current selection with the result of an evaluation" + :desc "Clojure: Replace current selection with the result of an evaluation" :triggers #{:editor.eval.cljs.result.replace} :reaction (fn [obj res] (if-let [err (or (:stack res) (:ex res))] @@ -291,7 +294,7 @@ (ed/replace-selection obj (unescape-unicode (or (:result res) "")))))) (behavior ::cljs-result.statusbar - :desc "Clojurescript: show the result of an evaluation on the statusbar" + :desc "Clojure: Show the result of an evaluation on the statusbar" :triggers #{:editor.eval.cljs.result.statusbar} :reaction (fn [obj res] (if-let [err (or (:stack res) (:ex res))] @@ -299,8 +302,8 @@ (notifos/set-msg! (unescape-unicode (or (:result res) "")) {:class "result"})))) (behavior ::cljs-result.inline - :desc "Clojurescript: shows the result of an evaluation as an inline-widget. Dispatches it as - an exception or as an inline-result" + :desc "Clojure: Show the resulting evaluation on inline widget" + :doc "The resulting evaluation is dispatched either as an exception or an inline-result." :triggers #{:editor.eval.cljs.result.inline} :reaction (fn [obj res] (let [meta (:meta res) @@ -310,8 +313,9 @@ (object/raise obj :editor.eval.cljs.exception res :passed) (object/raise obj :editor.result (unescape-unicode (or (:result res) "")) loc))))) -;; this is probably the same as ::cljs-result.inline but put the result widget somewhere else (behavior ::cljs-result.inline-at-cursor + :desc "Clojure: Show the resulting evaluation inline at cursor location" + :doc "This is similar to `::cljs-result.inline`, but puts the result as the cursor location." :triggers #{:editor.eval.cljs.result.inline-at-cursor} :reaction (fn [obj res] (let [meta (:meta res) @@ -333,8 +337,8 @@ :meta meta}))))) (behavior ::clj-result - :desc "Clojure: Receive an eval! result and dispatches it according - to its appropiate result type. Defaults to :inline" + :desc "Clojure: Receive an eval! result and dispatch it" + :doc "The dispatch is according to the appropiate result type. Defaults to `:inline`." :triggers #{:editor.eval.clj.result} :reaction (fn [obj res] (notifos/done-working) @@ -343,7 +347,7 @@ (object/raise obj ev res)))) (behavior ::clj-result.replace - :desc "Clojure: replace current selection with the result of an evaluation" + :desc "Clojure: Replace current selection with the result" :triggers #{:editor.eval.clj.result.replace} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -355,7 +359,7 @@ (ed/replace-selection obj (:result result)))))) (behavior ::clj-result.statusbar - :desc "Clojure: show the result of an evaluation on the statusbar" + :desc "Clojure: Show evaluation result on the statusbar" :triggers #{:editor.eval.clj.result.statusbar} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -367,8 +371,8 @@ (notifos/set-msg! (:result result) {:class "result"}))))) (behavior ::clj-result.inline - :desc "Clojure: displays the result of an eval! as an inline-widget. - Dispatches it as an exception or as an inline-result" + :desc "Clojure: Display eval result inline" + :doc "Dispatches as an exception or an inline-result." :triggers #{:editor.eval.clj.result.inline} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -379,8 +383,9 @@ (object/raise obj :editor.eval.clj.exception result :passed) (object/raise obj :editor.result (:result result) loc))))) -;; this is probably the same as ::clj-result.inline but put the result widget somewhere else (behavior ::clj-result.inline-at-cursor + :desc "Clojure: Display the eval result inline at cursor location" + :doc "This is similar to `::clj-result.inline`, but puts the result at the cursor location." :triggers #{:editor.eval.clj.result.inline-at-cursor} :reaction (fn [obj res] (doseq [result (-> res :results) @@ -404,8 +409,7 @@ :meta meta}))))) (behavior ::clj-exception - :desc "Clojure: displays an inline widget with stacktrace information and - a summary in the statusbar" + :desc "Clojure: Display stacktrace information and summary in statusbar" :triggers #{:editor.eval.clj.exception} :reaction (fn [obj res passed?] (when-not passed? @@ -417,9 +421,10 @@ (object/raise obj :editor.exception (:stack res) loc)))) (behavior ::cljs-exception - :desc "Clojurescript: Takes the result of evaling a cljs form which resulted in an - exception. Displays a message in the status bar and an exception widget with - the stacktrace" + :desc "Clojure: Display stacktrace information and summary in statusbar" + ;; Line below is too long to include, but will be useful after https://github.com/LightTable/LightTable/issues/2197 + :doc "Take the result of evaling a cljs form, which resulted in an exception, + and displays a message in the status bar and an exception widget with the stacktrace." :triggers #{:editor.eval.cljs.exception} :reaction (fn [obj res passed?] (when-not passed? @@ -441,8 +446,6 @@ (notifos/set-msg! msg {:class "error"}) (object/raise obj :editor.exception stack loc)))) -;; this is probably to avoid returning (print expr) as an inline result, instead sends it -;; to the console (behavior ::eval-print :triggers #{:editor.eval.clj.print} :reaction (fn [this str] @@ -453,8 +456,6 @@ :id (:id str) :content (:out str)})))) -;; this is probably to avoid returning (print expr) as an inline result, instead sends it -;; to the console but as an error element (red css color and so) (behavior ::eval-print-err :triggers #{:editor.eval.clj.print.err} :reaction (fn [this str] @@ -546,31 +547,34 @@ ;;**************************************************** ;; For more information on watches check +;; ;; Original anouncement: https://groups.google.com/forum/#!msg/light-table-discussion/lyFzPGI2XMs/ec8T1OUPvMsJ -;; blog posts: http://scattered-thoughts.net/blog/2014/01/27/were-not-even-trying/?utm_source=dlvr.it&utm_medium=twitter +;; +;; Blog posts: http://scattered-thoughts.net/blog/2014/01/27/were-not-even-trying/?utm_source=dlvr.it&utm_medium=twitter ;; https://medium.com/@zindlerb/guide-to-light-table-watches-fad560f698d3#.oqwq991sx -;; fancy Rolex watches plugin: https://groups.google.com/forum/#!topic/light-table-discussion/NQWGC0vVHMY +;; +;; Rolex watches plugin: https://groups.google.com/forum/#!topic/light-table-discussion/NQWGC0vVHMY (behavior ::cljs-watch-src - :desc "Clojurescript: wraps the watched source code with a call to 'js/lttools.watch' to catch - its result and send it back to LightTable while continuing normal evaluation of an expression. - (Check the wrapping function for more information)" + :desc "Clojure: Wraps the watched source code" + :doc "Wraps watched code to catch its result and send it back to LightTable, + while continuing normal evaluation of an expression." :triggers #{:watch.src+} :reaction (fn [editor cur meta src] (let [meta (assoc meta :ev :editor.eval.cljs.watch)] (str "(js/lttools.watch " src " (clj->js " (pr-str meta) "))")))) (behavior ::clj-watch-src - :desc "Clojure: wraps the watched source code with a call to 'lighttable.nrepl.eval/watch' to catch - its result and send it back to LightTable while continuing normal evaluation of an expression. - (Check the wrapping function for more information)" + :desc "Clojure: Wraps the watched source code" + :doc "Wraps watched code to catch its result and send it back to LightTable, + while continuing normal evaluation of an expression." :triggers #{:watch.src+} :reaction (fn [editor cur meta src] (str "(lighttable.nrepl.eval/watch " src " " (pr-str meta) ")"))) (defn fill-watch-placeholders - "replace editor-selection-flags (placeholders) for custom watches inside exp - with the src-code to be watched" + "Replace editor-selection-flags (placeholders) for custom watches inside `exp` + with the src-code to be watched." [exp src meta watch] (-> exp (string/replace "\n" " ") @@ -580,8 +584,9 @@ (string/replace #"__\|(.*)\|__" watch))) (behavior ::cljs-watch-custom-src - :desc "Clojurescript: prepare exp for watching by filling its placeholders and wrapping - its watcher-code with custom call to :editor.eval.cljs.watch" + :desc "Clojure: Prepare expression for watching" + :doc "The expression is prepared by filling its placeholders and wrapping its watcher-code + with custom call to `:editor.eval.cljs.watch`." :triggers #{:watch.custom.src+} :reaction (fn [editor cur meta opts src] (let [watch (str "(js/lttools.raise " (:obj meta) @@ -590,8 +595,9 @@ (fill-watch-placeholders (:exp opts) src meta watch)))) (behavior ::clj-watch-custom-src - :desc "Clojure: prepare exp for watching by filling its placeholders and wrapping - its watcher-code with custom call to :editor.eval.cljs.watch" + :desc "Clojure: Prepare expression for watching" + :doc "The exp is prepared by filling its placeholders and wrapping its watcher-code + with custom call to `:editor.eval.clj.watch`" :triggers #{:watch.custom.src+} :reaction (fn [editor cur meta opts src] (let [wrapped (if (:verbatim opts) @@ -600,7 +606,6 @@ watch (str "(lighttable.nrepl.core/safe-respond-to " (:obj meta) " :editor.eval.clj.watch {:meta " (pr-str (merge (dissoc opts :exp) meta)) " :result " wrapped "})")] (fill-watch-placeholders (:exp opts) src meta watch)))) -;; this is probably to update the value of watches during evaluation of a form (behavior ::cljs-watch-result :triggers #{:editor.eval.cljs.watch} :reaction (fn [editor res] @@ -614,7 +619,6 @@ str-result (util/escape str-result)] (object/raise (:inline-result watch) :update! str-result))))) -;; this is probably to update the value of watches during evaluation of a form (behavior ::clj-watch-result :triggers #{:editor.eval.clj.watch} :reaction (fn [editor res] @@ -629,8 +633,7 @@ ;;**************************************************** (behavior ::clj-doc - :desc "Clojure: gets the symbol at the cursor position and request its - docstring from the nREPL" + :desc "Clojure: Request docstring for symbol at cursor from nREPL" :triggers #{:editor.doc} :reaction (fn [editor] (let [token (find-symbol-at-cursor editor) @@ -669,8 +672,7 @@ (assoc token-left :loc loc))))) (behavior ::cljs-doc - :desc "Clojurescript: gets the symbol at the cursor position and request its - docstring from the nREPL" + :desc "Clojure: Request docstring for symbol at cursor from nREPL" :triggers #{:editor.doc} :reaction (fn [editor] (let [token (find-symbol-at-cursor editor) @@ -697,17 +699,17 @@ (object/raise editor :editor.doc.show! result))))) (behavior ::clj-doc-search - :desc "Clojure: Links the 'Search language docs' input-text on the sidebar - with a trigger to :docs.clj.search to retrieve all the documentation - on a user-input" + :desc "Clojure: Add trigger for Clojure in language documentation search" + :doc "Links the 'Search language docs' input-text on the sidebar with a trigger to + `:docs.clj.search` to retrieve all the documentation on a user-input." :triggers #{:types+} :reaction (fn [this cur] (conj cur {:label "clj" :trigger :docs.clj.search :file-types #{"Clojure"}}))) (behavior ::cljs-doc-search - :desc "Clojurescript: Links the 'Search language docs' input-text on the sidebar - with a trigger to :docs.clj.search to retrieve all the documentation - on a user-input" + :desc "Clojure: Add trigger for ClojureScript in language documentation search" + :doc "Links the 'Search language docs' input-text on the sidebar with a trigger to + `:docs.cljs.search` to retrieve all the documentation on a user-input." :triggers #{:types+} :reaction (fn [this cur] (conj cur {:label "cljs" :trigger :docs.cljs.search :file-types #{"ClojureScript"}})))