Significant changes to the reportr package are laid out below for each release. ================================================================================= VERSION 2.0.0 - 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. ================================================================================= VERSION 1.3.1 - Tests have been moved from "testthat" to "tinytest". - Package anchors have been added to documentation references to ore::es(), as now required for CRAN. ================================================================================= VERSION 1.3.0 - 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. ================================================================================= VERSION 1.2.2 - 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. ================================================================================= VERSION 1.2.1 - 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. ================================================================================= VERSION 1.2.0 - 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. ================================================================================= VERSION 1.1.2 - The "level" argument to report() or flag() may now be given without the "OL$" prefix, viz. report(Info, "Test"). ================================================================================= VERSION 1.1.1 - The s() function is now vectorised on its first argument. ================================================================================= VERSION 1.1.0 - 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. ================================================================================= VERSION 1.0.1 - Messages are now only printed to stderr() when their level is Warning or higher. ================================================================================= VERSION 1.0.0 - 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. ================================================================================= VERSION 0.2.0 - 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. ================================================================================= VERSION 0.1.0 - First public release. =================================================================================