Simple Assertions for Beautiful and Customisable Error Messages

Provides simple assertions with sensible defaults and customisable error messages. It offers convenient assertion call wrappers and a general assert function that can handle any condition. Default error messages are user friendly and easily customized with inline code evaluation and styling powered by the 'cli' package.

assertions

Simple assertions with sensible defaults and customisable error messages.

Overview

The goals with assertions are to provide

1. Convenient assertion calls (e.g. assert_number())

2. A general assert function that asserts any possible condition/s and throws informative error messages

3. Extremely user friendly error message defaults.

4. Easily customisable error messages, with inline code evaluation & styling powered by the cli package

5. Simple creation of custom assertion functions with user-specified defaults

Installation

install.packages("assertions")

Development version

You can install the development version of assertions from GitHub by running:

if (!require("remotes", quietly = TRUE))
    install.packages("remotes")

remotes::install_github("selkamand/assertions")

Quick Start

All assertions start with assert, which means you just type it in and levarage autocomplete suggestions to look through all available options

# Load library
library(assertions)

# Use premade assertions
assert_character(c('a', 'b', 'c'))
assert_number(2)
assert_flag(TRUE)

# Assert anything 
assert(1000 % 2 == 0)

# Assert multiple conditions at once (all must be true)
assert(1000 % 2 == 0, 6/2 == 3)

Customizing Error Messages

# Customise any error messages using the `msg` argument
assert_number("A", msg = "Please supply a number!")

# Evaluate code in your error message using '{}' operators
foo = "A"
assert_number(foo, msg = "'{foo}' is not a number :(. Try again")

# Emphasise cetain words in error using {.strong text_to_emphasise}
assert_number("A", msg = "{.strong Try again}")

For advanced customisation, see cli documentation

Create your own assertion functions

Have a custom assertion you want to use repeatedly?

Creating your own assertion functions is extremely easy

Just use assert_create(), you just need to supply:

1. a function that returns TRUE/FALSE when assertion should PASS/FAIL

2. a default error message

How about an example?

# Create a function that asserts input is lowercase 
assert_lowercase <- assert_create(
  func = function(x) {x == tolower(x)}, 
  default_error_msg = "'{arg_name}' must be entirely lowercase" 
)

#Assertion passes if input is lowercase
assert_lowercase("all lower case")

#But throws the expected error if uppercase characters are present
assert_lowercase("NOT all lower case") 

See ?assert_create() for details

Vectorised assertions

Assertions may have vectorised versions that test whether all elements in a vector/matrix meet a condition.

For example:

• assert_greater_than() expects a single number as an input

• assert_all_greater_than() works on vectors/matrices.

Vectorised functions have the assert_all_ prefix.

Contributing to this package

Two options

Request an assertion

1. Open a github issue and request away. I’m happy to implement a tonne more assertions, just let me know what you want

Creating assertions yourself

1. Create a custom assert_something function with a call to assert_create() or assert_create_chain()

2. Create a github issue with the assertion creation code + any helper function you pass to the func argument (e.g. is_something())

Similar Packages

Great alternative packages for writing assertions include:

• assertthat
• checkmate
• assertive
• ensurer

Each package has its own features and syntax. So hopefully there is one that suits your needs and preferences. I’m a big fan of checkmate for its speed, assertive for its huge library of ready-made assertion functions, and assertthat for its error message customization.