output: The TractoR message reporting system

Description

Functions for working with TractoR's own system for reporting informative messages, warnings and errors. TractoR functions use this system in preference to the message, warning and stop functions.

Usage

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

Arguments

level

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

...

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 tractorUseOutputPrefix option is FALSE, this parameter will have no effect.

toReport

If TRUE, report errors like other messages. By default this is FALSE because stop reports errors instead.

usePrefix

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

Value

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

Details

The tractor.base package uses its own system for reporting messages, which provides certain useful features over the standard R system, such as the incorporation of output , 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 output 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 output using a level lower than the current output level will produce no output. If output is called before setOutputLevel, the output level will default to OL$Info. The flag function is called like output, but it stores messages for later reporting, like warning, rather than reporting them immediately. Stored messages are reported when reportFlags is called, at which point multiple instances of the same message are consolidated where appropriate. 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 output returns the text entered by the user. The call output(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 output.

Examples

Run this code

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

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

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