This change will only affect rare advanced users that depend on
the return value of `log!` or `event!`. For all other users this
will be a non-breaking change.
Before this commit:
`log!` and `event!` returned true iff signal was allowed.
After this commit:
`log!` and `event!` now ALWAYS return nil.
`log!?` and `event!?` have been added that keep the old behaviour.
Motivation:
It's pretty rare to use the return value when generating log or event
signals. I originally included the return value since it CAN be handy,
and I figured it could just be ignored by those that don't need it.
But #53 showed that there's a downside I hadn't anticipated - some
users may actually depend on / prefer a nil return to prevent
accidentally affecting program flow.
I think that's a legitimate enough concern to still make a change now
before v1 final.
Apologies for the nuissance!
Before this commit: A nil signal `:kind` renders as "DEFAULT".
After this commit: A nil signal `:kind` isn't rendered at all.
The previous behaviour wasn't particularly useful, and as Mark
helpfully pointed out - makes it difficult to skip `:kind` rendering.
The new behaviour also better matches the behaviour for other signal
keys, which can mostly be dissoc'ed to skip rendering.
This is the input-side change related to [1], and only
affects folks who've been providing custom callsite info to
Telemere signals (usually in the context of wrapper macros).
To provide custom callsite info BEFORE this commit:
(tel/signal! {:location {:ns "my-ns", :line 10, :column 20}})
To provide custom callsite info AFTER this commit:
(tel/signal! {:ns "my-ns", :coords [10 20]})
Motivation for the new override API:
- It's shorter and cleaner.
- It's less likely to cause confusion since it avoids the
redundant signal keys (signals previously contained callsite
info in 2 duplicate places).
- The underlying implementation is simpler.
- The util for manually getting coords is easier to use and doesn't
require macro-time environment info, making it easier for folks
to write wrapper macros that include line + column info.
- When embedded, the new callsite info is shorter and easier for
Cljs advanced compilation to de-duplicate (so helps reduce .js
build size).
[1] Commit 1f99f7186b
This is a BREAKING change to get in before v1 final.
Signal keys BEFORE this commit:
`:location` ---- ?{:keys [ns file line column]} signal creator callsite
`:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location)
`:line` -------- ?int line of signal creator callsite, same as (:line location)
`:column` ------ ?int column of signal creator callsite, same as (:column location)
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
Signal keys AFTER this commit:
`:ns` ---------- ?str namespace of signal creator callsite
`:coords` ------ ?[line column] of signal creator callsite
Motivation for the breaking change:
The new callsite schema is simpler to use/override, reduces noise, and can reduce
code expansion size (and so Cljs build size).
- `:file` was rarely useful, but often added large embedded strings.
- `:location` was redundant, and often difficult for Closure's
advanced build to properly de-duplicate.
This schema will be shared by Truss v2 and Tufte v3.
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.
