dreamerr (version 1.5.0)

stop_up: Stops (or warns in) sub-function execution

Description

Useful if you employ non-user level sub-functions within user-level functions or if you want string interpolation in error messages. When an error is thrown in the sub function, the error message will integrate the call of the user-level function, which is more informative and appropriate for the user. It offers a similar functionality for warning.

Usage

stop_up(..., up = 1, msg = NULL, envir = parent.frame(), verbatim = FALSE)
stopi(..., envir = parent.frame())
warni(..., envir = parent.frame(), immediate. = FALSE)
warn_up(
  ...,
  up = 1,
  immediate. = FALSE,
  envir = parent.frame(),
  verbatim = FALSE
)

Arguments

...

Objects that will be coerced to character and will compose the error message.

up

The number of frames up, default is 1. The call in the error message will be based on the function up frames up the stack. See examples. If you have many calls to stop_up/warn_up with a value of up different than one, you can use set_up to change the default value of up within the function.

msg

A character vector, default is NULL. If provided, this message will be displayed right under the error message. This is mostly useful when the text contains formatting because the function stop used to send the error message erases any formatting.

envir

An environment, default is parent.frame(). Only relevant if the error/warning message contains interpolation (interpolation is performed with stringmagic). It tells where the variables to be interpolated should be found. In general you should not worry about this argument.

verbatim

Logical scalar, default is FALSE. By default the error/warning message allows variable interpolation with stringmagic. To disable interpolation, use verbatim = TRUE.

immediate.

Whether the warning message should be prompted directly. Defaults to FALSE.

Functions

• stopi(): Error messages with string interpolation

• warni(): Warnings with string interpolation

• warn_up(): Warnings at the level of user-level functions

Author

Laurent Berge

Details

These functions are really made for package developers to facilitate the good practice of providing informative user-level error/warning messages.

The error/warning messages allow variable interpolation by making use of stringmagic's interpolation.

See Also

For general argument checking, see check_arg() and check_set_arg().

Examples

# We create a main user-level function
# The computation is done by an internal function
# Here we compare stop_up with a regular stop

main_function = function(x = 1, y = 2){
  my_internal_function(x, y)
}

my_internal_function = function(x, y){
  if(!is.numeric(x)){
    stop_up("Argument 'x' must be numeric but currently isn't.")
  }

  # Now regular stop
  if(!is.numeric(y)){
    stop("Argument 'y' must be numeric but currently isn't.")
  }

  nx = length(x)
  ny = length(y)
  if(nx != ny){
    # Note that we use string interpolation with {}
    warn_up("The lengths of x and y don't match: {nx} vs {ny}.")
  }

  x + y
}

# Let's compare the two error messages
# stop_up:
try(main_function(x = "a"))
# => the user understands that the problem is with x

# Now compare with the regular stop:
try(main_function(y = "a"))
# Since the user has no clue of what my_internal_function is,
#  s/he will be puzzled of what to do to sort this out

# Same with the warning => much clearer with warn_up
main_function(1, 1:2)