reportr: The reportr message reporting system

Description

Functions for reporting informative messages, warnings and errors. These are provided as alternatives to the message, warning and stop functions in base R.

Usage

setOutputLevel(level, usePrefix = NA)
report(level, ..., default = NULL, showDepth = TRUE, outputErrors = FALSE)
flag(level, ...)
reportFlags()

Arguments

level

The level of output message to produce, or for setOutputLevel, the minimum level to display. See Details.

usePrefix

If TRUE or FALSE, set the useOutputPrefix option appropriately. NA means leave this option at its current value.

...

Objects which can be coerced to mode character. These will be printed with no space between them.

default

For questions, a default return value, to be used when the output level is above OL$Question.

showDepth

If TRUE, add a series of stars at the beginning of the output string to show the depth of the caller in the execution stack. If the useOutputPrefix option is FALSE, this parameter will have no effect.

outputErrors

If TRUE, output errors like other messages. By default this is FALSE because stop produces error messages instead.

Value

These functions are mainly called for their side effects, but report returns a character vector of length one giving the user's response for messages of level Question.

Details

The reportr system for reporting messages provides certain useful features over the standard R system, such as the incorporation of output consolidation, automatic generation of stack traces for debugging, and conditional reporting based on the current "output level". The output level is set by the setOutputLevel function, and governs whether a particular call to report will actually report anything. Output levels are described by the OL object, a list with components Debug, Verbose, Info, Warning, Question and Error; and any call to report using a level lower than the current output level will produce no output. If report is called before setOutputLevel, the output level will default to OL$Info. The flag function is called like report, but it stores messages for later reporting, like warning, rather than reporting them immediately. Stored messages are reported when report is next called, at which point multiple instances of the same message are consolidated where possible. The user may also manually force stored messages to be reported by calling reportFlags. The Question output level is special in that it requests input from the user, using readline. The text argument then forms the text of the question, and report returns the text entered by the user. The call report(OL$Error,...) is largely similar to stop(...) in most cases, except that a stack trace will be printed first if the current output level is Debug. The R error condition is signalled in any case. No other conditions are signalled by report.

Examples

Run this code

setOutputLevel(OL$Warning)
report(OL$Info, "Test message")  # no output
setOutputLevel(OL$Info)
report(OL$Info, "Test message")  # prints the message

flag(OL$Warning, "Test warning")  # no output
flag(OL$Warning, "Test warning")  # repeated warning
reportFlags()  # consolidates the warnings and prints the message

x <- report(OL$Question, "What is 2+2?")
report(OL$Info, ifelse(as.numeric(x)==4,"Correct!","Wrong"))