[nop] Misc housekeeping

examples.clj

@@ -1 +0,0 @@
-;; TODO

examples.cljc

@@ -0,0 +1,59 @@
+(ns examples
+  "Some basic Telemere usage examples."
+  (:require
+   [taoensso.telemere :as t]))
+
+;; TODO Still be to completed
+
+(t/with-signal (t/event! ::my-id))
+(t/with-signal (t/event! ::my-id :warn))
+(t/with-signal
+  (t/event! ::my-id
+    {:let  [x "x"] ; Available to `:data` and `:msg`
+     :data {:x x}
+     :msg  ["My msg:" x]}))
+
+(t/with-signal (t/log! "My msg"))
+(t/with-signal (t/log! :warn "My msg"))
+(t/with-signal
+  (t/log!
+    {:let  [x "x"] ; Available to `:data` and `:msg`
+     :data {:x x}}
+    ["My msg:" x]))
+
+(t/with-signal (throw (t/error!         (ex-info "MyEx" {}))))
+(t/with-signal (throw (t/error! ::my-id (ex-info "MyEx" {}))))
+(t/with-signal
+  (throw
+    (t/error!
+      {:let  [x "x"] ; Available to `:data` and `:msg`
+       :data {:x x}
+       :msg  ["My msg:" x]}
+      (ex-info "MyEx" {}))))
+
+(t/with-signal (t/trace! (+ 1 2)))
+(t/with-signal (t/trace! ::my-id (+ 1 2)))
+(t/with-signal
+  (t/trace!
+    {:let  [x "x"] ; Available to `:data` and `:msg`
+     :data {:x x}}
+    (+ 1 2)))
+
+(t/with-signal (t/spy! (+ 1 2)))
+(t/with-signal (t/spy! :debug (+ 1 2)))
+(t/with-signal
+  (t/spy!
+    {:let  [x "x"] ; Available to `:data` and `:msg`
+     :data {:x x}}
+    (+ 1 2)))
+
+(t/with-signal (t/catch->error! (/ 1 0)))
+(t/with-signal (t/catch->error! ::my-id (/ 1 0)))
+(t/with-signal
+  (t/catch->error!
+    {:let  [x "x"] ; Available to `:data` and `:msg`
+     :data {:x x}
+     :msg  ["My msg:" x my-error]
+     :catch-val "Return value when form throws"
+     :catch-sym my-error}
+    (/ 1 0)))

examples.cljs

@@ -1 +0,0 @@
-;; TODO

resources/signal-docstrings/catch-to-error!.txt

@@ -10,13 +10,17 @@ Default level: `:error`
 
 Examples:
 
-  (catch->error! (/ 1 0)) ; %> {:kind :error, :level :error, :error <caught> ...}
+  (catch->error! (/ 1 0))         ; %> {:kind :error, :level :error, :error <caught> ...}
-  (catch->error! {:id ::my-id, :catch-val "threw"} (/ 1 0)) ; %> {... :id ::my-id ...}
+  (catch->error! ::my-id (/ 1 0)) ; %> {... :id ::my-id ...}
   (catch->error!
     {:let  [x "x"] ; Available to `:data` and `:msg`
      :data {:x x}
-     :msg_ ["My msg:" x]}
+     :msg  ["My msg:" x my-error]
-     (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+     :catch-val "Return value when form throws"
+     :catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
+     }
+
+     (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
 
 Tips:
 

src/taoensso/telemere.cljc

@@ -20,33 +20,19 @@
 
 (enc/assert-min-encore-version [3 91 0])
 
-;;;; Roadmap
-;; x Fundamentals
-;; x Basic logging utils
-;; x Interop: SLF4J
-;; x Interop: `clojure.tools.logging`
-;; - Core logging handlers
-;; - First docs, intro video
-;; - First OpenTelemetry tools
-;; - Update Tufte  (signal API, config API, signal fields, etc.)
-;; - Update Timbre (signal API, config API, signal fields, backport improvements)
-
 ;;;; TODO
-;; - Via Timbre: core handlers, any last utils?
+;; - Core handlers
-;;   - Cljs (.log js/console <js/Error>) better than string stacktrace (clickable, etc.)
+;;   - (.log js/console <js/Error>) better than string stacktrace
-;;
+;; - Handler utils: complete, docstrings, tests
-;; - Tests for utils (hostname, formatters, etc.)?
-;; - Remaining docstrings and TODOs
-;; - Kinds: #{:log :spy :trace :event :error :system/out :system/err <user>}
-;; - General polish
-;;
 ;; - Reading plan
-;; - Recheck `ensso/telemere-draft.cljc`
+;; - Final polish, docstrings
-;; - Cleanup `ensso/telemere-drafts.txt`
+;; - Initial wiki docs
-;;
-;; - Decide on module/import/alias/project approach
-;; - Initial README, wiki docs, etc.
 ;; - Explainer/demo video
+;; - v1.0.0-beta1
+;;
+;; - First OpenTelemetry tools
+;; - Update Tufte  (signal API, config API, signal keys, etc.)
+;; - Update Timbre (signal API, config API, signal keys, backport improvements)
 
 ;;;; Shared signal API
 
@@ -206,14 +192,7 @@
      (let [opts (impl/signal-opts `event! {:kind :event, :level :info} :id :level :dsc args)]
        (enc/keep-callsite `(impl/signal! ~opts)))))
 
-(comment
+(comment (with-signal (event! ::my-id :info)))
-  (with-signal (event! ::my-id))
-  (with-signal (event! ::my-id :warn))
-  (with-signal
-    (event! ::my-id
-      {:let  [x "x"] ; Available to `:data` and `:msg`
-       :data {:x x}
-       :msg  ["My msg:" x]})))
 
 #?(:clj
    (defmacro log!
@@ -224,14 +203,7 @@
      (let [opts (impl/signal-opts `log! {:kind :log, :level :info} :msg :level :asc args)]
        (enc/keep-callsite `(impl/signal! ~opts)))))
 
-(comment
+(comment (with-signal (log! :info "My msg")))
-  (with-signal (log! "My msg"))
-  (with-signal (log! :warn "My msg"))
-  (with-signal
-    (log!
-      {:let  [x "x"] ; Available to `:data` and `:msg`
-       :data {:x x}}
-      ["My msg:" x])))
 
 #?(:clj
    (defmacro error!
@@ -248,16 +220,7 @@
             ~'__error ; Unconditional!
             )))))
 
-(comment
+(comment (with-signal (throw (error! ::my-id (ex-info "MyEx" {})))))
-  (with-signal (throw (error!         (ex-info "MyEx" {}))))
-  (with-signal (throw (error! ::my-id (ex-info "MyEx" {}))))
-  (with-signal
-    (throw
-      (error!
-        {:let  [x "x"] ; Available to `:data` and `:msg`
-         :data {:x x}
-         :msg  ["My msg:" x]}
-        (ex-info "MyEx" {})))))
 
 #?(:clj
    (defmacro trace!
@@ -268,14 +231,7 @@
      (let [opts (impl/signal-opts `trace! {:kind :trace, :level :info, :msg ::impl/spy} :run :id :asc args)]
        (enc/keep-callsite `(impl/signal! ~opts)))))
 
-(comment
+(comment (with-signal (trace! ::my-id (+ 1 2))))
-  (with-signal (trace! (+ 1 2)))
-  (with-signal (trace! ::my-id (+ 1 2)))
-  (with-signal
-    (trace!
-      {:let  [x "x"] ; Available to `:data` and `:msg`
-       :data {:x x}}
-      (+ 1 2))))
 
 #?(:clj
    (defmacro spy!
@@ -286,14 +242,7 @@
      (let [opts (impl/signal-opts `spy! {:kind :spy, :level :info, :msg ::impl/spy} :run :level :asc args)]
        (enc/keep-callsite `(impl/signal! ~opts)))))
 
-(comment
+(comment (with-signal (spy! :info (+ 1 2))))
-  (with-signal (spy! (+ 1 2)))
-  (with-signal (spy! ::my-id (+ 1 2)))
-  (with-signal
-    (spy!
-      {:let  [x "x"] ; Available to `:data` and `:msg`
-       :data {:x x}}
-      (+ 1 2))))
 
 #?(:clj
    (defmacro catch->error!
@@ -304,24 +253,20 @@
      (let [opts     (impl/signal-opts `catch->error! {:kind :error, :level :error} ::__form :id :asc args)
            rethrow? (if (contains? opts :catch-val) false (get opts :rethrow?))
            catch-val    (get       opts :catch-val)
+           catch-sym    (get       opts :catch-sym '__caught-error) ; Undocumented
            form         (get       opts ::__form)
-           opts         (dissoc    opts ::__form :catch-val :rethrow?)]
+           opts         (dissoc    opts ::__form :catch-val :catch-sym :rethrow?)]
 
        (enc/keep-callsite
          `(enc/try* ~form
-            (catch :any ~'__caught-error
+            (catch :any ~catch-sym
-              (impl/signal! ~(assoc opts :error '__caught-error))
+              (impl/signal! ~(assoc opts :error catch-sym))
-              (if ~rethrow? (throw ~'__caught-error) ~catch-val)))))))
+              (if ~rethrow? (throw ~catch-sym) ~catch-val)))))))
 
 (comment
-  (with-signal (catch->error! (/ 1 0)))
+  (with-signal (catch->error! ::my-id (/ 1 0)))
-  (with-signal (catch->error! {:id ::my-id, :catch-val "threw"} (/ 1 0)))
+  (with-signal (catch->error! {                  :msg_ ["Error:" __caught-error]} (/ 1 0)))
-  (with-signal
+  (with-signal (catch->error! {:catch-sym my-err :msg_ ["Error:" my-err]}         (/ 1 0))))
-    (catch->error!
-      {:let  [x "x"] ; Available to `:data` and `:msg`
-       :data {:x x}
-       :msg_ ["My msg:" x __caught-error]}
-     (/ 1 0))))
 
 #?(:clj
    (defmacro uncaught->error!
@@ -342,7 +287,7 @@
             (fn [~'__thread ~'__throwable]
               (impl/signal! ~opts)))))))
 
-(comment (macroexpand '(uncaught->error! :id1)))
+(comment (macroexpand '(uncaught->error! ::my-id)))
 
 ;;;; Utils
 
@@ -365,11 +310,13 @@
      (^String [                         ] (enc/get-hostname (enc/msecs :mins 1) 5000 "UnknownHost"))
      (        [timeout-msecs timeout-val] (enc/get-hostname (enc/msecs :mins 1) timeout-msecs timeout-val))))
 
-(comment (enc/qb 1e6 (hostname))) ; 76.64
+(comment (enc/qb 1e6 (hostname))) ; 69.13
 
 #?(:clj (defn thread-name ^String [] (.getName (Thread/currentThread))))
 #?(:clj (defn thread-id   ^String [] (.getId   (Thread/currentThread))))
 
+(comment (thread-name) (thread-id))
+
 (defn format-instant
   "TODO Docstring"
   {:tag #?(:clj 'String :cljs 'string)}

test/taoensso/telemere_tests.cljc

@@ -453,7 +453,12 @@
       (let [[rv     [sv]] (ws  (tel/catch->error! {:catch-val :foo}  (ex1!)))] [(is (= rv :foo)) (is (sm? sv {:kind :error, :line :submap/ex, :level :error, :error ex1-pred, :id  nil}))])
       (let [[rv     [sv]] (ws  (tel/catch->error! {:catch-val :foo} (+ 1 2)))] [(is (= rv 3))    (is (nil? sv))])
       (let [[rv     [sv]] (ws  (tel/catch->error! {:catch-val :foo ; Overrides `:rethrow?`
-                                                   :rethrow?  true} (+ 1 2)))] [(is (= rv 3))    (is (nil? sv))])])
+                                                   :rethrow?  true} (+ 1 2)))] [(is (= rv 3))    (is (nil? sv))])
+
+      (let [[rv     [sv]] (ws  (tel/catch->error!  {:catch-val     nil
+                                                    :catch-sym     my-err
+                                                    :data {:my-err my-err}} (ex1!)))]
+        [(is (= rv nil)) (is (sm? sv {:kind :error, :data {:my-err ex1-pred}}))])])
 
    #?(:clj
       (testing "uncaught->error!"