extendException: Create a new exception from an existing one.

In jefferys/Exception: Classed exception object hierarchy

Description

This is used mainly to create exception constructors. Given a base exception, this builds a new exception based on it. The base exception is usually constructed inline as the message, call, package, and any data properties in the new exception are inherited from the base exception. They can only be set when the base exception is constructed and can not be overriden by this extension constructor. The new exception can have any additional specified exception class(es), but will also inherit the classes of the base exception.

Usage

extendException(exception, base = Exception())

Arguments

exception	The new exception's class (name). Usually just a single class, but can be a vector of classes. This is prepended to the class vector of the base exception to create the complete class of the new exception
base	An existing exception to base a new exception on. Often constructed in-line to allow setting parameters. By default this is the exception generated by a no-parameter call to "Exception()."

Details

It is not recommended to use "extendException" to directly create new exceptions unless those exceptions are documented and used only in one place. Repeatedly constructing the same class of exception is the job of a constructor function, and an exception constructor function provides an obvious place to put documentation.

Value

extendException returns a new exception class inheriting the message, call, and class hierarchy of the base= exception, and all of that base class's data elements.

Examples

# Function to create a new FruitException
FruitException <- function( fruit,
    message= sprintf("Sorry, %s is a fruit", fruit),
    call=NULL, package= packageName(), ...
){
   e <- extendException( c("FruitException", "PedanticException"),
      base= Exception( message=message, call= call, package= package,
         fruit= fruit, ...)
   )
   return(e)
}

fEx <- FruitException( fruit= "tomato" )
inherits(fEx, "FruitException")
inherits(fEx, "PedanticException")
inherits(fEx, "Exception")
inherits(fEx, "condition")
fEx$fruit == "tomato"   # Internal use only

# Making fruit accessible by external users.
exceptionFruit <- function(...)  UseMethod( "exceptionFruit" )
exceptionFruit.Exception <-function (e, ...) e$fruit

exceptionFruit( fEx )

# Will work for any Exception derived object
ex <- Exception( fruit= "Green Pepper", package="testing" )
exceptionFruit( ex ) == ex$fruit
conditionMessage( ex ) == "[testing] An Exception occurred."

# User putting in extra data for internal use
withComplainerFEx <- FruitException( fruit= "tomato", complainer= "Bob")
tryCatch(
   { stop(withComplainerFEx) },
   FruitException= function(e) {
      if (e$complainer == "Bob") {
         message( paste0( "Ignoring Bob's complaint: \"",
                            conditionMessage(e), "\"" ))
      }
   }
 )

## Not run: 
# Can't use data variables in messages without declaring real function.
ex <- Exception( fruit= "Green Pepper",
   message= paste0( "I hate ", fruit ), package="testing" )
#> Error in paste0("I hate ", fruit) : object 'fruit' not found

## End(Not run)

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