R.utils (version 2.9.0)

Verbose: Class to writing verbose messages to a connection or file

Description

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.

Usage

Verbose(con=stderr(), on=TRUE, threshold=0, asGString=TRUE, timestamp=FALSE,
  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.

timestamp

If TRUE, each output is preceded with a timestamp.

removeFile

If TRUE and con is a filename, the file is first deleted, if it exists.

asGString

If TRUE, all messages are interpreted as GString 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.
	enterf	-
	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, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, 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.

• <= -100Only for debug messages, i.e. messages containing all necessary information for debugging purposes and to find bugs in the code. Normally these messages are so detailed so they will be a pain for the regular user, but very useful for bug reporting and bug tracking by the developer.

• -99 -- -11Detailed verbose messages. These will typically be useful for the user to understand what is going on and do some simple debugging fixing problems typically due to themselves and not due to bugs in the code.

• -10 -- -1Verbose messages. For example, these will typically report the name of the file to be read, the current step in a sequence of analysis steps and so on. These message are not very useful for debugging.

• 0Default level in all output methods and default threshold. Thus, by default, messages at level 0 are not shown.

• >= +1Message that are always outputted (if threshold is kept at 0). We recommend not to output message at this level, because methods should be quiet by default (at the default threshold 0).

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

NullVerbose.

Examples

# NOT RUN {
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 == 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)) {
    enterf(verbose, "Sub analysis #%d", 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)
# }