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

`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.

examples.cljc

@@ -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

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

@@ -1,25 +1,26 @@
 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> ...}
   (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 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:
 

projects/main/src/taoensso/telemere.cljc

@@ -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))))
 

projects/main/src/taoensso/telemere/impl.cljc

@@ -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]}

projects/main/test/taoensso/telemere_tests.cljc

@@ -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!"