docs/src/guide/get-started.md

In devOpifex/erratum: Handle Error and Warning Messages

Get Started

Basics

The two core functions of the package are e and w, the former creates and error and the latter a warning.

e("erratum!")

erratum!

Note that this printed the error message (with cat) and thus does not actually stops code execution. However, e can stop code execution with the stop or fatal method (different names, identical execution, fatal is more expressive).

::: tip The raise method works for both errors and warnings. :::

Perhaps even better is the method named raise which will simply raise the error (stop) or raise the warning: one method for all "issues."

err <- e("erratum!")

# err$raise()
# err$stop()

err$fatal()

Error: erratum!

Similar for warnings, use w to create a warning object and use the warn method to throw an actual warning.

www <- w("attention!")

# err$raise()
www$warn()

Warning message:
attention! 

If you want to retrieve the message as a string to process it differently you can use the message field.

(string <- www$message)

class(string)

[1] "attention!"
[1] "character"

Standardisation

Erratum treats errors and warning as objects. This, amongst other things, allows for easy standardisation of messages.

err <- e("Input must be a numeric")

add_ <- function(x){
  if(!is.numeric(x))
    err$raise()

  x + 1
}

log_ <- function(x){
  if(!is.numeric(x))
    err$raise()

  log(x)
}

add_("one")
log_("two")

Error: Input must be a numeric
Error: Input must be a numeric

::: tip Using rules and checks is more convenient. :::

Return

In the example given above we raise the error if input conditions are not met. Instead of doing this using the stop, raise, or fatal, one could use the return methods which returns the error from the parent function.

In the example below add_ returns the error if the input is not numeric but does not halt code execution with stop.

err <- e("Input must be a numeric")

add_ <- function(x){
  if(!is.numeric(x))
    err$return()

  x + 1
}

(x <- add_("one"))
is.e(x)

Input must be a numeric
TRUE

::: tip Read more about this in the escalation section. :::

Templating

You can create a template that will be used to print errors and warnings. Make sure it includes %s: the warning or error message.

template.e("Whoops: %s - sorry!")

e("Sumin' went wrong")

Whoops: Sumin' went wrong - sorry!

Note that it supports crayon.

template.e(crayon::red("%s"))

e("Sumin' went wrong")

These can be reset by simply re-running the respective template function.

template.e()

devOpifex/erratum documentation built on Feb. 5, 2024, 1:58 p.m.