The improved performance rarely matters in practice, and can
cause issues for folks using deep-walking macros.
Better solution would be to eventually get the optimisation
implemented upstream in Clojure core.
The old (deeply-nested) return value seemed to be difficult
for users to read, and prone to mistakes when destructuring.
The new (map) return value is a little more verbose, but
more obvious and less error-prone. Overall a good trade-off
given that this util is anyway used mostly for debugging
or unit tests.
`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.
Objectives:
- Support single map opts arg in all cases.
- Make it easier for folks to inspect the source to understand how
the common creators use/wrap underlying `signal!`.
Also updated relevant docstrings, etc.
New opts:
- `:format-id-fn`
- `:format-msg-fn`
This way its easier to reuse signal-preamble-fn for custom handlers.
If nil is passed as any format fn: value won't be logged.
The `-` char before the msg is now part of the formatter fn.
