Exception: Create a base Exception object.

In jefferys/Exception: Classed exception object hierarchy

Description

The generated Exception object is a subclass of condition. It describes an anomalous event and is intended to be the basis of a hierarchy of exception classes. Exceptions are signaled by calling stop, warning, or message on an Exception or Exception-derived object and can be caught individually or in groups using try/catch signal handlers. Exception objects inherit the message and call fields from condition and add a package field that describes what package this exception event happened in. They also add any unused argName= value arguments as extra data, storing this inside the exception object for internal use.

Usage

Exception(message = "An Exception occurred.", call = sys.calls(),
  package = packageName(), ...)

## S3 method for class 'Exception'
conditionMessage(c)

Arguments

message	The message associated with the exception. By default this is "An Exception occurred.". conditionMessage(e) is overridden for Exception and its extensions so that most of the time the name of package where the exception was generated will be prepended upon access, making the message appear to be "[package] message".
call	The call or call stack associated with the exception. By default this is the list returned by calling sys.calls at the point where this object was constructed. Set NULL when an exception does not involve code, or with sys.call when only a specific code line is involved.
package	The package where this exception is generated; tries to guess this by default. When not called from within a package, this will likely be NULL, e.g. when exceptions are constructed interactively or from script. If given or guessed and not NULL, the package is automatically prepended to the message.
...	Additional arguments defining key=value data to include in the object. These are accessible by treating the generated exception as a list.
c	An excepetion object. This parameter is called "c" to be compatible with the underlying S3 object "condition" class.

Value

Exception returns an Event object, which is an object of class c("Exception", "condition") describing some problematic event, usually signaled from within a package e.g. with stop.

conditionMessage called on a Exception object returns the message associated with that exception, with the package of the exception prepended.

Extra data

Data provided through extra arguments are accessible by treating an Exception as a list. This is intended to be used only internally in the package or script that signaled the Exception. If data is included for use by handlers in external code (from other packages or users), S3 accessors should be defined. Similarly, external code should never need to include extra data in exceptions for use by internal code. Custom exception generating functions with appropriate arguments should be exported. See extendException.

Exceptions are part of your API

If exceptions are visible to users they are part of that functions public API just like arguments are. Any exception that a function signals by e.g. stop, warning, message, etc, that are not handled within that function are visible to users. These should be clearly documented and generally can be changed only in a backward-compatible manner. User code that catches exceptions will depend on them being thrown with the same class name and having both the same parent classes and the same accessible data, if any. Defining custom exception classes and using S3 accessors for any data makes this easier.

See Also

condition, conditionMessage, conditionCall, exceptionPackage, tryCatch

Examples

e <- Exception()
conditionMessage(e)
conditionCall(e)
exceptionPackage(e)

e <- Exception( "Extra data included", x=1, y=2, z=list(A=1, B="two") )
x <- e$x
y <- e$y
z <- e$z

## Not run: 
  stop(Exception( "Oops, that didn't work." ))

  # Convert a fatal Exception into a warning.
  e <- Exception( "Lying about the package", package="NotMine" )
  tryCatch( stop(e), Exception= function(e) {warning(e)})

## End(Not run)

jefferys/Exception documentation built on May 19, 2019, 3:59 a.m.