Verbose
Class to writing verbose messages to a connection or file
Package: R.utils
Class Verbose
Object
~~|
~~+--
Verbose
Directly known subclasses:
MultiVerbose, NullVerbose
public static class Verbose
extends Object
Class to writing verbose messages to a connection or file.
- Keywords
- classes, programming, IO
Usage
Verbose(con=stderr(), on=TRUE, threshold=0, asGString=TRUE, timestamp=FALSE, removeFile=TRUE, core=TRUE, ...)
Arguments
- con
- A
connection
or acharacter
string filename. - on
- A
logical
indicating if the writer is on or off. - threshold
- A
numeric
threshold that thelevel
argument of any write method has to be equal to or larger than in order to the message being written. Thus, the lower the threshold is the more - timestamp
- If
TRUE
, each output is preceded with a timestamp. - removeFile
- If
TRUE
andcon
is a filename, the file is first deleted, if it exists. - asGString
- If
TRUE
, all messages are interpreted asGString
before being output, otherwise not. - core
- Internal use only.
- ...
- Not used.
Fields and Methods
Methods:
as.character
Returns a character string version of this object.
as.double
Gets a numeric value of this object.
as.logical
Gets a logical value of this object.
capture
Captures output of a function.
cat
Concatenates and prints objects if above threshold.
enter
Writes a message and indents the following output.
equals
Checks if this object is equal to another.
evaluate
Evaluates a function and prints its results if above threshold.
exit
Writes a message and unindents the following output.
getThreshold
Gets current verbose threshold.
getTimestampFormat
Gets the default timestamp format.
header
Writes a header.
isOn
Checks if the output is on.
isVisible
Checks if a certain verbose level will be shown or not.
less
Creates a cloned instance with a higher threshold.
more
Creates a cloned instance with a lower threshold.
newline
Writes one or several empty lines.
off
Turn off the output.
on
Turn on the output.
popState
-
print
Prints objects if above threshold.
printf
Formats and prints object if above threshold.
pushState
Pushes the current indentation state of the Verbose object.
ruler
Writes a ruler.
setDefaultLevel
Sets the current default verbose level.
setThreshold
Sets verbose threshold.
setTimestampFormat
Sets the default timestamp format.
str
Prints the structure of an object if above threshold.
summary
Generates a summary of an object if above threshold.
timestamp
Writes a timestamp.
timestampOff
-
timestampOn
Turns automatic timestamping on and off.
warnings
Outputs any warnings recorded.
writeRaw
Writes objects if above threshold.
}
Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save
Output levels
As a guideline, use the following levels when outputting verbose/debug message using the Verbose class. For a message to be shown, the output level must be greater than (not equal to) current threshold. Thus, the lower the threshold is set, the more messages will be seen.
- <= -100<="" li="">=>
A compatibility trick and a speed-up trick
If you want to include calls to Verbose in a package of yours in order
to debug code, but not use it otherwise, you might not want to load
R.utils all the time, but only for debugging.
To achieve this, the value of a reference variable to a Verbose class
is always set to TRUE
, cf. typically an Object reference has value NA
.
This makes it possible to use the reference variable as a first test
before calling Verbose methods. Example:
foo <- function(..., verbose=FALSE) {
# enter() will never be called if verbose==FALSE, thus no error.
verbose && enter(verbose, "Loading")
}
Thus, R.utils is not required for foo()
, but for
foo(verbose==Verbose(level=-1))
it is.
Moreover, if using the NullVerbose
class for ignoring all verbose
messages, the above trick will indeed speed up the code, because
the value of a NullVerbose reference variable is always FALSE
.
Extending the Verbose class
If extending this class, make sure to output messages via
*writeRaw()
or one of the other output methods (which in
turn all call the former).
This guarantees that *writeRaw()
has full control of the
output, e.g. this makes it possible to split output to standard
output and to file.
See Also
Examples
verbose <- Verbose(threshold=-1)
header(verbose, "A verbose writer example", padding=0)
enter(verbose, "Analysis A")
for (kk in 1:10) {
printf(verbose, "step %d
", kk)
if (kk == 2) {
cat(verbose, "Turning ON automatic timestamps")
timestampOn(verbose);
} else if (kk == 4) {
timestampOff(verbose);
cat(verbose, "Turned OFF automatic timestamps")
cat(verbose, "Turning OFF verbose messages for steps ", kk, "-6")
off(verbose)
} else if (kk == 6) {
on(verbose)
cat(verbose, "Turned ON verbose messages just before step ", kk+1)
}
if (kk %in% c(5,8)) {
enter(verbose, "Sub analysis ", kk)
for (jj in c("i", "ii", "iii")) {
cat(verbose, "part ", jj)
}
exit(verbose)
}
}
cat(verbose, "All steps completed!")
exit(verbose)
ruler(verbose)
cat(verbose, "Demo of some other methods:")
str(verbose, c(a=1, b=2, c=3))
print(verbose, c(a=1, b=2, c=3))
summary(verbose, c(a=1, b=2, c=3))
evaluate(verbose, rnorm, n=3, mean=2, sd=3)
ruler(verbose)
newline(verbose)