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.
Trade off a small performance hit with tracing to avoid duplication
of potentially large expansions, and to help further eliminate potential
issues when embedding within IOT-style macros (`core.async/go`, etc.)
Problem:
(clojure.core.async/go (taoensso.telemere/log! "hello")) ; Compiles fine
(cljs.core.async/go (taoensso.telemere/log! "hello")) ; Compile fails
I could try to get to the bottom of exactly what's going on - but ultimately
IOC mechanisms like `go` are always going to be a bit fragile, especially for
heavily-optimized/unusual code.
In this case, the problem is thankfully only with Cljs - and Telemere's Cljs
performance isn't too critical - so I think we can afford to just bypass any
potential fiddling by the `go` macro by wrapping Cljs Telemere expansions in
an IIFE ((fn [] ...)).
Downside is the (small) added cost of a function construction and call.
Upside is avoiding potential issues with core.async and other similar
IOC-style systems (Electric Clojure, etc.)
