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

Unconditionally executes given form and-
  If form succeeds: return the form's result.
  If 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.

API: [form] [id-or-opts form] => form's result (value/throw) (unconditional), or (:catch-val opts)
Default  kind: `:error`
Default level: `:error`

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

     (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}

Tips:

  - Test using `with-signal`: (with-signal (catch->error! ...)).
  - Supports the same options [2] as other signals [1].

  - Useful for preventing errors from going unnoticed in futures, callbacks,
    agent actions, etc.!: (future (catch->error ::my-future (do-something)))

See also `error!`.

----------------------------------------------------------------------
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options`  - {:keys [kind level id data ...]}
[3] See `help:signal-content`  - {:keys [kind level id data ...]}
[4] See `help:signal-filters`  - (by ns/kind/id/level, sampling, etc.)