Verbose {R.utils}R Documentation

Class to writing verbose messages to a connection or file

Description

Package: R.utils
Class Verbose

Object
~~|
~~+--Verbose

Directly known subclasses:
NullVerbose

public static class Verbose
extends Object

Class to writing verbose messages to a connection or file.

Usage

Verbose(con=stderr(), on=TRUE, threshold=0, removeFile=TRUE, core=TRUE, ...)

Arguments

con A connection or a character string filename.
on A logical indicating if the writer is on or off.
threshold A numeric threshold that the level 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 and more details will be outputted.
removeFile If TRUE and con is a filename, the file is first deleted, if it exists.
core Internal use only.
... Not used.

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.

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.

Author(s)

Henrik Bengtsson, http://www.braju.com/R/

See Also

NullVerbose.

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\n", kk)
  if (kk == 4) {
    cat(verbose, "Turning OFF verbose messages")
    on(verbose)
  } else if (kk == 6) {
    off(verbose)
    cat(verbose, "Turned ON verbose messages")
  }
  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)

[Package R.utils version 0.5.5 Index]