luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-16 17:41:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

[mod] Remove advanced options from catch->error!

Browse source 
`catch->error!` with default opts is quite handy for use with `trace!`/`spy!`.

But there's a lot that users might want to customize, including:

  - Exactly what error type to catch.
  - Whether or not to rethrow on catch.
  - Error binding sym to enable use within signal message, data, etc.

We could support all of this via `catch->error!` opts but there's not much
point. If anyway customizing such behaviour, it'd be better for the user to just
use an appropriate `try/catch`.

So I've now documented this recommendation, and removed all but the most basic
(:catch-val) options.

This is a BREAKING change for anyone that was previously using any of the
following options:

  :rethrow?
  :catch-sym

Note that `:rethrow?` was never particularly helpful (independently of
`:catch-val` anyway), and the removal of `:catch-sym` will throw a compile-time
error for any existing users.
This commit is contained in:
Peter Taoussanis 2024-12-22 14:13:31 +01:00
parent d2386d62f1
commit 0de5c094e5
5 changed files with 22 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
examples.cljc
View file

@ -169,9 +169,8 @@
(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}
:msg ["My msg:" x]
:catch-val "Return value when form throws"}
(/ 1 0)))
;;;; Wiki examples

19
projects/main/resources/signal-docstrings/catch-to-error!.txt
View file

@ -1,12 +1,15 @@
ALWAYS (unconditionally) executes given `run` form and:
If `run` form succeeds: return the form's result.
If `run` form throws:
Call `error!` with the thrown error and the given signal options [2],
then return (:catch-val opts) if it exists, or rethrow the error.
If `run` form succeeds: returns the form's result.
If `run` form throws ANYTHING:
Calls `error!` with the thrown error and given signal options [2], then
either returns given (:catch-val opts), or rethrows.
Default kind: `:error`
Default level: `:error`
Just a convenience util. For more flexibility use your own `try/catch`.
See `taoensso.encore/try*` for easily catching cross-platform errors.
Examples:
(catch->error! (/ 1 0)) ; %> {:kind :error, :level :error, :error <caught> ...}
@ -14,12 +17,10 @@ Examples:
(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 ; Sym of caught error, available to `:data` and `:msg`
}
:msg ["My msg:" x]
:catch-val "Return value iff form throws"}
(/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
(/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
Tips:

17
projects/main/src/taoensso/telemere.cljc
View file

@ -281,17 +281,16 @@
:arglists (impl/signal-arglists :catch->error!)}
([opts-or-id run] `(catch->error! ~(assoc (merge-or-assoc-opts base-opts &form &env :id opts-or-id) :run run)))
([opts-or-run]
(let [opts (merge-or-assoc-opts base-opts &form &env :run opts-or-run)
rethrow? (if (contains? opts :catch-val) false (get opts :rethrow? true))
catch-val (get opts :catch-val)
catch-sym (get opts :catch-sym '__caught-error) ; Undocumented
run-form (get opts :run)
opts (dissoc opts :run :catch-val :catch-sym :rethrow?)]
(let [opts (merge-or-assoc-opts base-opts &form &env :run opts-or-run)
rethrow? (not (contains? opts :catch-val))
catch-val (get opts :catch-val)
run-form (get opts :run)
opts (dissoc opts :run :catch-val)]
`(enc/try* ~run-form
(catch :all ~catch-sym
(impl/signal! ~(assoc opts :error catch-sym))
(if ~rethrow? (throw ~catch-sym) ~catch-val))))))))
(catch :all ~'__caught
(impl/signal! ~(assoc opts :error '__caught))
(if ~rethrow? (throw ~'__caught) ~catch-val))))))))
(comment (with-signal (catch->error! ::my-id (/ 1 0))))

2
projects/main/src/taoensso/telemere/impl.cljc
View file

@ -444,7 +444,7 @@
'([opts-or-run]
[id run]
[{:as opts-map :keys
[#_defaults #_elide? #_allow? #_expansion-id, rethrow? catch-val,
[#_defaults #_elide? #_allow? #_expansion-id, catch-val,
elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by,
ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}

10
projects/main/test/taoensso/telemere_tests.cljc
View file

@ -627,16 +627,8 @@
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! (ex1!)))] [(is (ex1? re)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id nil}))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! :id1 (ex1!)))] [(is (ex1? re)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id :id1}))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:id :id1} (ex1!)))] [(is (ex1? re)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id :id1}))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:rethrow? false} (ex1!)))] [(is (nil? re)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id nil}))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:catch-val :foo} (ex1!)))] [(is (= rv :foo)) (is (sm? sv {:kind :error, :line :submap/some, :level :error, :error pex1?, :id nil}))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:catch-val :foo} (+ 1 2)))] [(is (= rv 3)) (is (nil? sv))])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:catch-val :foo ; Overrides `:rethrow?`
:rethrow? true} (+ 1 2)))] [(is (= rv 3)) (is (nil? sv))])
(let [[[rv] [sv]] (with-sigs (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 pex1?}}))])])
(let [[[rv re] [sv]] (with-sigs (tel/catch->error! {:catch-val :foo} (+ 1 2)))] [(is (= rv 3)) (is (nil? sv))])])
#?(:clj
(testing "uncaught->error!"