tryLog: Try an expression with condition logging and error recovery

Description

tryLog is implemented by calling tryCatchLog and traps any errors that occur during the evaluation of an expression without stopping the execution of the script (similar to try). Errors, warnings and messages are logged. In contrast to tryCatchLog it returns but does not stop in case of an error and therefore does not have the error and finally parameters to pass in custom handler functions.

Usage

tryLog(
  expr,
  write.error.dump.file = getOption("tryCatchLog.write.error.dump.file", FALSE),
  write.error.dump.folder = getOption("tryCatchLog.write.error.dump.folder", "."),
  silent.warnings = getOption("tryCatchLog.silent.warnings", FALSE),
  silent.messages = getOption("tryCatchLog.silent.messages", FALSE),
  include.full.call.stack = getOption("tryCatchLog.include.full.call.stack", TRUE),
  include.compact.call.stack = getOption("tryCatchLog.include.compact.call.stack",
    TRUE),
  logged.conditions = getOption("tryCatchLog.logged.conditions", NULL),
  execution.context.msg = ""
)

Arguments

expr

R expression to be evaluated

write.error.dump.file

TRUE: Saves a dump of the workspace and the call stack named dump_<YYYYMMDD>_at_<HHMMSS.sss>_PID_<process id>.rda. This dump file name pattern shall ensure unique file names in parallel processing scenarios.

write.error.dump.folder

path: Saves the dump of the workspace in a specific folder instead of the working directory

silent.warnings

TRUE: Warnings are logged only, but not propagated to the caller. FALSE: Warnings are logged and treated according to the global setting in getOption("warn"). See also warning.

silent.messages

TRUE: Messages are logged, but not propagated to the caller. FALSE: Messages are logged and propagated to the caller.

include.full.call.stack

Flag of type logical: Shall the full call stack be included in the log output? Since the full call stack may be very long and the compact call stack has enough details normally the full call stack can be omitted by passing FALSE. The default value can be changed globally by setting the option tryCatchLog.include.full.call.stack. The full call stack can always be found via last.tryCatchLog.result.

include.compact.call.stack

Flag of type logical: Shall the compact call stack (including only calls with source code references) be included in the log output? Note: If you ommit both the full and compact call stacks the message text will be output without call stacks. The default value can be changed globally by setting the option tryCatchLog.include.compact.call.stack. The compact call stack can always be found via last.tryCatchLog.result.

logged.conditions

NULL: Conditions are not logged. vector of strings: Only conditions whose class name is contained in this vector are logged. NA: All conditions are logged.

execution.context.msg

a text identifier (eg. the PID or a variable value) that will be added to msg.text for catched conditions. This makes it easier to identify the runtime state that caused a condition esp. in parallel execution scenarios. The value must be of length 1 and will be coerced to character. Expressions are not allowed. The added output has the form: {execution.context.msg: your_value}

Value

The value of the expression (if expr is evaluated without an error. In case of an error: An invisible object of the class "try-error" containing the error message and error condition as the "condition" attribute.

Details

tryLog is implemented using tryCatchLog. If you need need more flexibility for catching and handling errors use the latter. Error messages are never printed to the stderr connection but logged only.

Examples

Run this code

# NOT RUN {
tryLog(log(-1))   # logs a warning (logarithm of a negative number is not possible)
tryLog(log("a"))  # logs an error
tryCatchLog(log(-1), execution.context.msg = Sys.getpid())
# }