# Check Arguments and Generate Readable Error Messages

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)
    #> You're beautiful!
    #> You're beautiful!
    #> You're beautiful!

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)
    #> Error in cat(what, "\n"): argument 1 (type 'builtin') cannot be handled by 'cat'

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)
    #> Error: `what` must have type character.
    #>
    #> ✖ `what` has type builtin.

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)
    #> Error: `what` must have length 1.
    #>
    #> ✖ `what` has length 2.

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)
    #> Error: `what` must have length larger than 0.
    #>
    #> ✖ `what` has length 0.

`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)
    #> You're beautiful again!
    #> You're beautiful again!
    #> You're beautiful again!

## 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"))
    #> Error: `arg` must be `"yes"` or `"no"`.
    #>
    #> ✖ `arg` is `"I'm invalid."`.

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.")
    #> Error: You are wrong.
    #>
    #> ✖ `arg` is `"I'm invalid."`.

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.")
    #> Error: `arg` must be `"yes"` or `"no"`.
    #>
    #> ✖ 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)
    #> Error: `arg` must be `"yes"` or `"no"`.
    #>
    #> ✖ `arg` is `"I'm invalid."`.
    #> ✖ You're wrong.
    #> ℹ But you're beautiful.

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)
    #> Error: You're beautiful.
    #>
    #> ℹ Your eyes are big.
    #> ℹ Your hair is long.
    #> ✖ But you broke my heart.

You can change argument `as` to generate a message:

    throw(general, specifics, as = "message")
    #> You're beautiful.
    #>
    #> ℹ Your eyes are big.
    #> ℹ Your hair is long.
    #> ✖ But you broke my heart.

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)
    #> Error: `x` must be a positive number.
    #>
    #> ✖ `x` is `-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")
    #> [1] "Pink Floyd, Pink Freud and Pink Florida"

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

    cat(back_quote(x))
    #> `"Pink Floyd"` `"Pink Freud"` `"Pink Florida"`

    back_quote(c(1, 2, NA))
    #> [1] "`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)
    #> Error: `arg` must be `"Pink Floyd"`, `"Pink Freud"` or `"Pink Florida"`.
    #>
    #> ✖ `arg` is `"Pink Florence"`.