dwatch {debugr}

Printing debug outputs during runtime

Description

Prints a debug output to the console or to a file. A debug output can consist of a static text message, the values of one or more objects (potentially transformed by applying some functions) or the value of one or multiple (more complex) R expressions. Whether or not a debug message is displayed can be made dependent on the evaluation of a criterion phrased as an R expression. Generally, debug messages are only shown if the debug mode is activated. The debug mode is activated and deactivated with debugr_switchOn and debugr_switchOff, respectively, which change the logical debugr.active value in the global options. Since debug messages are only displayed in debug mode, the dwatch function calls can even remain in the original code as they remain silent and won't have any effect until the debug mode is switched on again.

Usage

dwatch(crit = "", objs = NULL, funs = NULL, args = NULL,
  show.all = FALSE, expr = NULL, msg = "", halt = FALSE,
  unique.id = "", suppress.source = FALSE, show.frame = TRUE,
  filename = "")

Arguments

crit

An string containing an expression that determines if any debug outputs shall be displayed at all. Only, if crit evaluates to TRUE, a debug output will be shown.

objs

A vector of object names (as strings). The values of these objects will be displayed in the debug output.

funs

A vector of function names (as strings) that shall be applied to the objects in objs, one function per object. funs must have the same length as objs. If no function shall be applied to an object, the respective element in the funs vector must be NULL. The functions in funs must undertake the task of printing the object.

args

A list of vectors containing additional arguments for the functions in funs. It is assumed that the first argument of each function in funs is the respective object from objs. Additional arguments can then be supplied with args. The args list must have the same number of elements as funs. If a function does not receive any additional arguments, the respective element in the args list must be NULL. Each element of args is a vector of named elements. The element name is the name of the additions argument to the respective funs function, the elements value is the argument's value.

show.all

Prints all objects from the (calling) environment. If set to TRUE, objs is ignored and all objects in the enviroment (with the exception of functions) are included in the debug output.

expr

A vector of strings containing expressions to be evaluated and displayed in the debug output. This output comes on top of any msg or objs output.

msg

A string containing a general message to be displayed.

halt

If TRUE, the execution of the debugged R script is stopped after printing the output.

unique.id

A unqiue string ID that can be chosen by the user. This ID is displayed in the debug output and is used to identify the code section that contains the dwatch call. By default, when a debug output is displayed, dwatch tries to show an extract from the code thats surrounds the dwatch call (this feature can be turned off by setting suppress.source to TRUE).

suppress.source

If TRUE (default), dwatch tries to find the code section that includes the dwatch call and displays it as part of the debug output. Requires unique.id to be set.

show.frame

If TRUE (default), a frame is displayed at the top and the bottom of the debug output.

filename

If a filename is provided, all debug message are only printed to the file and not shown on the R console.

See Also

debugr_switchOn, debugr_switchOff, debugr_isActive

Examples

library(debugr)

# --- A simple example to print the value of an object
myfunction <- function(x) {
  justastring <- "Not much information here"
  z <- 1

  for(i in 1:x) {
    # This call can remain in your code; it is only activated when
    # the debug mode is switched on
    dwatch(crit = "z > 40000", objs = c("z"))
    z <- z * i
  }
  invisible(z)
}

# Turn debug mode on
debugr_switchOn()

# Call function for debugging
myfunction(10)



# --- Applying a function to the object that is printed
myfunction <- function(x) {
  justastring <- "Not much information here"
  z <- 1

  for(i in 1:x) {
    dwatch(crit = "z > 40000", objs = c("z"), funs=c("format"),
    args = as.list(c(big.mark = "\",\"")))
    z <- z * i
  }
  invisible(z)
}

myfunction(10)



# --- Same thing, this time with a expression
myfunction <- function(x) {
  justastring <- "Not much information here"
  z <- 1

  for(i in 1:x) {
    dwatch(crit = "z > 40000", expr=c("format(z, big.mark = \",\")"))
    z <- z * i
  }
  invisible(z)
}

myfunction(10)