Check Arguments and Generate Readable Error Messages

In erify: Check Arguments and Generate Readable Error Messages

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = TRUE
)

The package name "erify" is derived from "verify" and "error", which are the package's two main themes.

Motivation

When creating functions for other people to use, you always need some validator functions which

1. check if arguments passed by users are valid, and if not,
2. generate informative and well-formatted error messages in a consistent style.

erify serves the exact purpose. Specifically, erify provides

1. several handy validator functions for checking if an argument has valid type, class, length, etc., and
2. tools with which you can create your own validator functions.

Installation

Install erify from CRAN:

install.packages("erify")

Or install the development version from GitHub:

# install devtools if not
# install.packages("devtools")

devtools::install_github("flujoo/erify")

Validator Functions

erify has some ready-to-use validator functions. Let's have a look.

library(erify)

Suppose you are creating a function which prints a string several times to emphasize it:

# print `what` `n` times
emphasize <- function(what, n) {
  for (i in 1:n) {
    cat(what, "\n")
  }
}

# example
emphasize("You're beautiful!", 3)

And suppose a novice user accidentally passes a function to argument what, he/she will get an error message which is not very readable:

emphasize(c, 3)

You can improve this by adding erify's check_type() into emphasize():

emphasize <- function(what, n) {
  # check the type of `what`
  check_type(what, "character")

  # main
  for (i in 1:n) {
    cat(what, "\n")
  }
}

emphasize(c, 3)

In the above code, check_type(what, "character") checks if what has type character, and if not, generates improved error message.

You can add more validator functions. For example, suppose you want what to be a single character, which means it must have length 1. You can check its length with check_length():

emphasize <- function(what, n) {
  # check the type of `what`
  check_type(what, "character")
  # check the length of `what`
  check_length(what, 1)

  # main
  for (i in 1:n) {
    cat(what, "\n")
  }
}

emphasize(c("apple", "orange"), 3)

In the above code, check_length(what, 1) checks if what has length exactly 1.

Maybe this is too strict. You feel any non-empty character vector is acceptable. You can change the second argument of check_length() in the above code:

emphasize <- function(what, n) {
  # check the type of `what`
  check_type(what, "character")
  # check the length of `what`
  check_length(what, c(0, NA))

  # main
  for (i in 1:n) {
    cat(what, "\n")
  }
}

emphasize(character(0), 3)

check_length(what, c(0, NA)) checks if what has length larger than 0.

erify's validator functions return silently if the argument they are checking is valid. For example,

emphasize("You're beautiful again!", 3)

Error Message Style

So far, you may have noticed that the error messages generated by erify's validator functions have a consistent style.

Specifically, in this style, an error message usually has two components:

First, a general statement of the problem. For example:

#> Error: `what` must have type character.

Second, a concise description of what went wrong. For example:

#> * `what` has type builtin.

The second component may contain more items, as you will see.

This style is adopted from Hadley Wickham's The tidyverse style guide. Check the link for more details.

Customize Error Messages

You can change the error message generated by any erify's validator function by specify arguments general, specific and supplement.

For example, suppose you want an argument arg to take only "yes" or "no" as input. You can put this restriction with check_content():

arg <- "I'm invalid."

# check the content of `arg`
check_content(arg, c("yes", "no"))

To change the default general statement of the error, you can specify argument general. For example,

check_content(arg, c("yes", "no"), general = "You are wrong.")

To change the default description of the error, you can specify argument specific. For example,

check_content(arg, c("yes", "no"), specific = "You are wrong.")

You can add more details with argument supplement. For example,

supplement <- c(x = "You're wrong.", i = "But you're beautiful.")
check_content(arg, c("yes", "no"), supplement = supplement)

In the above code, x means "error", while i means "hint".

Create Validator Functions

You can create your own validator functions with throw(). Below is an example:

general <- "You're beautiful."

specifics <- c(
  i = "Your eyes are big.",
  i = "Your hair is long.",
  x = "But you broke my heart."
)

throw(general, specifics)

You can change argument as to generate a message:

throw(general, specifics, as = "message")

Now let's create a validator function to check if an argument is a positive number.

check_positive <- function(x) {
  check_type(x, c("integer", "double"))
  check_length(x, 1)

  if (is.na(x) || x <= 0) {
    general <- "`x` must be a positive number."
    specifics <- "`x` is `{x}`."
    throw(general, specifics, env = list(x = x))
  }
}

check_positive(-2)

As you might have noticed, you can insert R code into general and specifics as {x} in

specifics <- "`x` is `{x}`."

To execute the code, you need to pass the arguments involved to argument env, as in

throw(general, specifics, env = list(x = x))

See glue::glue() for more details.

Other Tools

join() connects given words with a conjunction:

x <- c("Pink Floyd", "Pink Freud", "Pink Florida")
join(x, "and")

back_quote() convert an R object to character and add back quotations:

cat(back_quote(x))

back_quote(c(1, 2, NA))

These two functions are useful to create error messages, as in the inside of check_content():

arg <- "Pink Florence"
check_content(arg, x)

erify documentation built on Oct. 4, 2022, 5:07 p.m.