NEWS
reportr 2.0.0 (2026-10-13)
- Every message is now signalled as a classed R condition before it is
reported. The class vector always includes one derived from the level of the
message, such as "reportrInfo", so existing code gains conditions without
any changes. See ?reportrCondition.
- The report(), flag() and assert() functions gain a "class" argument, which
attaches further classes of the caller's choosing to a message, and a "call"
argument giving the call to associate with the condition. Classed messages
are signalled even when the output level means that they will not be
reported.
- The new reportAs() function changes the level at which particular classes of
condition are reported, so that the caller can decide how serious a situation
is.
- The new fallback() function raises an error which the caller may demote,
returning a value of the signalling function's choosing instead. Only errors
raised this way can be demoted, since others provide no value to continue
with.
- withReportrHandlers() now also accepts named arguments mapping condition
classes to levels or to handler functions, and reportrHandlers() installs the
same translations for a whole session using globalCallingHandlers(), which
requires R 4.0.0 or later. The package itself needs only R 3.5.0.
- Conditions translated by withReportrHandlers() keep the classes of R's
original condition, which is also stored in their "original" element, so a
handler further out can still match them by class.
- Messages can now be written to files, connections and functions as well as,
or instead of, the terminal, using setOutputTargets() with toTerminal(),
toFile() and toFunction(). Each output target may have its own level
threshold and prefix format. See ?targets.
- The new "%t" prefix escape expands to the current time, formatted according
to the new "reportrTimeFormat" option.
- The new "reportrBaseClasses" option, if TRUE, makes conditions at level
Warning inherit from "warning", and those at level Info and below from
"message", so that suppressWarnings() and suppressMessages() affect them.
- The new level OL$Ignore, below OL$Debug, can be used with reportAs() to
suppress a class of condition entirely.
BREAKING CHANGES
- Errors raised by report() and friends are now caught by try() and by
tryCatch(expr, error=...), since the conditions signalled inherit from
"error". Previously they could not be caught at all. Code which wrapped a
reporting function in try() to guard against other errors may now find it
catching reportr errors as well.
- An error is now fatal whatever the current output level, and whether or not
its message is filtered out of the output. Previously either could prevent
it from taking effect.
- OL$Fatal now ends execution in the same way as OL$Error. Previously it was
reported but not acted upon.
- The reportrStackFilterIn and reportrStackFilterOut options have been removed.
- An assertion whose expression itself reports an error is now a failed
assertion, and reports the message given to assert(), rather than ending
execution. This matches what already happened when the expression raised an
error in R's own way.
- flag() signals its condition at the point where the message is flagged,
rather than when it is eventually reported. A flagged message at level Error
or above is therefore fatal at that point.
- Flagged messages, including warnings consolidated by withReportrHandlers(),
are now written with the usual prefix format, rather than always with
"%L: ". With the default format they are therefore indented to show the
call depth at which they were flagged.
- The "prefixFormat" argument to report(), ask() and assert() is deprecated,
since prefix formats now belong to output targets. The value "", which
suppresses the prefix, is still honoured, and is equivalent to the new
"prefix=FALSE"; any other value is ignored, with a warning the first time.
- ask() now asks its question in a non-interactive session, such as a script
run with Rscript, if standard input is a terminal, reading the answer from
there. Previously it always returned its default in such sessions. Setting
the new "reportrAskInScripts" option to FALSE restores the old behaviour.
- The package now requires R 3.5.0 or later.
BUG FIXES
- Expression substitution is no longer applied twice to consolidated messages
reported by reportFlags(), or to messages passed to assert(). Text containing
"#{...}" is now reported literally in these cases, as intended.
- Message text arriving from outside reportr, via withReportrHandlers(), is no
longer passed through es(). Previously a foreign message containing the
"#{...}" syntax would have it evaluated.
- The environment used for expression substitution is now passed explicitly
rather than being inferred from the call depth, so it remains correct
regardless of how a message reaches the reporting code.
- withReportrHandlers() now returns the value of its expression invisibly if
that value was invisible, so wrapping an expression no longer changes what
the console prints.
- Stack traces for messages reported at top level no longer contain a
spurious "NA" entry.
- The "%f" prefix escape no longer causes an error when a message is reported
at top level; it expands to an empty string instead.
- Namespace-qualified calls, such as reportr::report(), no longer add spurious
depth to the "%d" prefix escape or to stack traces, and "%f" now gives just
the function name for a qualified call.
reportr 1.3.1 (2025-03-29)
- Tests have been moved from "testthat" to "tinytest".
- Package anchors have been added to documentation references to ore::es(), as
now required for CRAN.
reportr 1.3.0 (2018-10-26)
- The new assert() function reports a message (by default an error) if its first
argument produces an error or does not evaluate TRUE.
- The ask() function gains a "valid" argument, which specifies valid responses.
If it is given, the user will be asked repeatedly until they give a suitable
answer.
reportr 1.2.2 (2016-10-06)
- The report() function now checks whether the output level is low enough for
the message to be displayed, before constructing it. This can save a lot of
overhead time when many debug-type messages are to be skipped over.
reportr 1.2.1 (2016-04-01)
- Use of the "%p" syntax in a prefix format string previously caused an error.
This has been corrected.
- The tests have been updated for compatibility with a new version of testthat.
reportr 1.2.0 (2015-10-14)
- The "ore" package is now used by "reportr". It provides improved versions of
some of the package's auxiliary functionality. As a result, the s() function
and %~% and %!~% operators are no longer exported by "reportr". Please see
es(), %~% and %~~% from "ore" instead.
- It is now possible to configure the level at which the stderr stream is used,
using the "reportrStderrLevel" option.
- A "Fatal" output level has been added. In practice it is never used, but the
output level can be set to it, to suppress all output.
- Flags are now reported at the end of a call to withReportrHandlers().
- The ask() function now also returns the default value if the R session is
noninteractive.
- The return value from getOutputLevel() is now named with the level name.
- A set of tests, and a README file, have been added to the package.
reportr 1.1.2 (2014-03-12)
- The "level" argument to report() or flag() may now be given without the "OL$"
prefix, viz. report(Info, "Test").
reportr 1.1.1 (2014-02-26)
- The s() function is now vectorised on its first argument.
reportr 1.1.0 (2013-12-04)
- Expression substitution is now performed on messages, using Ruby-like syntax.
This allows R expressions to be interpolated into message strings for brevity
and clarity.
- Error messages and stack trace elements are now truncated to keep output
readable.
reportr 1.0.1 (2013-07-23)
- Messages are now only printed to stderr() when their level is Warning or
higher.
reportr 1.0.0 (2011-10-25)
- Errors generated within the expression passed to withReportrHandlers() are now
reported with information on the call, if available. Relevant information
should therefore no longer be lost when using reportr, as opposed to the
standard R error-reporting system.
- A "reportrStackTraceLevel" option is now available, allowing for the
generation of stack traces at lower output levels than Error if required. The
default behaviour is as before.
- The clearFlags() function has been added, which removes any pending flags.
reportr 0.2.0 (2011-07-28)
- Substantial reworking of the package for greater generality. New functions
ask(), getOutputLevel() and withReportrHandlers(), and new infix operator
%!~%, have been added. Arguments to other functions have been changed in some
cases. The principal mechanisms of report() and flag() remain the same,
however.
- A series of new options can be used for flexible message and stack filtering.
See ?report for details.
- The format of the string prepended to messages can now be customised, rather
than just switched on or off. See ?report for details.
- The new function withReportrHandlers() evaluates an R expression in a context
in which reportr handles any errors, warnings and messages raised by it.
- The new function ask(...) replaces report(OL$Question, ...).
- Various other tweaks have been made, including one for compatibility with
changes coming in R 2.14.0.
reportr 0.1.0 (2010-10-27)