Learn R Programming

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

To get a bug fix or to use a feature from the development version, you can install the development version of assertions from GitHub.

# 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:

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.

Copy Link

Version

Install

install.packages('assertions')

Monthly Downloads

913

Version

0.1.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Sam El-Kamand

Last Published

June 2nd, 2023

Functions in assertions (0.1.0)

assert_directory_exists

Assert are directory exists
assert_flag

Assert input is a scalar logical
assert_excludes

Assert object does not include any illegal values
assert_greater_than

Assert input is greater than some minimum value
assert_numeric_vector

Assert input is a numeric vector
assert_int

Assert input is an integer
assert_names_include

Assert that the input object includes a specified name
assert_greater_than_or_equal_to

Assert input is greater than or equal to a specified minimum value
assert_matrix

Assert input is a matrix
assert_logical_vector

Assert input is an atomic logical vector
assert_reactive

Assert that x is reactive
assert_function_expects_n_arguments

Assert function expects n arguments
excludes_advanced

Check if an object does not contain prohibited elements
assert_identical

Assert that the input object is identical to a specified value
assert_includes

Assert object includes required
assert_no_duplicates

Assert that the input vector has no duplicates
assert_function

Assert input is a function
assert_subset

Check if a vector is a subset of another
assert_string

Assert input is a character string
has_missing_values

Check if a vector has missing values
assert_list

Assert input is a list
has_extension

Title
assert_logical

Assert input is logical
is_flag

Check if a value is a logical flag
check_all_assertions_are_tested_enough

Check assertions are tested enough
has_no_duplicates

Check if a vector has no duplicates
format_as_bullets

Preprocess character vectors for cli::cli_abort()
assert_no_missing

Assert that the input vector has no missing values
assert_non_empty_string

Assert input is a non empty character string
is_identical

Check if two objects are identical
assert_vector

Assert input is a vector
assert_whole_number

Assert that the input object is a whole number
includes

Check if All Values in Required are in x
assertion_tests

Count tests per Assertion
assertion_names

List assertion names
includes_advanced

Check if an object contains required elements
is_reactive

Check if a value is reactive
util_get_duplicated_values

Get the duplicated values in a vector
is_numeric_vector

Check if an object is a numeric vector
has_no_missing_values

Check if a vector has no missing values
is_string

Check if an object is a single string
is_flag_advanced

Check if x is a flag
is_same_type

Check equality of type
is_equal

Check equality of two objects
is_character_vector

Check if an object is a character vector
common_roxygen_params

Common Parameter Descriptions
is_logical_vector

Check if an object is a logical vector
has_class

Check object is some class
has_duplicates

Check if a vector has duplicates
format_inline

Preprocess character vectors for cli package functions
assert_number

Assert input is a number
assert_numeric

Assert input is numeric
is_subset

Check if one set is a subset of another
is_string_advanced

Check if x is a string
is_greater_than_or_equal_to

Check if a numeric vector is greater than or equal to a specified minimum value
is_number

Check if an object is a single number
has_all_names

Check if a named object has all specified names
is_greater_than

Check if a numeric vector is greater than a specified minimum value
util_count_duplicates

Count the number of duplicated values in a vector
util_count_missing

Count the number of missing values in a vector
is_number_advanced

Check if x is a number
setopts_count_exlusive_to_first

Count of Elements Exclusive to First Set
is_non_empty_string_advanced

Check if x is a nonempty string
setopts_exlusive_to_first

Elements Exclusive to First Set
is_list

Check if a value is a list
is_vector

Check if an object is a vector This function checks if an object is a vector
setopts_are_equal

Compare Sets for Equality
is_superset

Check if one set is a superset of another
setopts_common_elements

Find Common Elements
assert

Assert that conditions are met
assert_all_directories_exist

Assert all files are directories
assert_all_greater_than_or_equal_to

Assert input is greater than or equal to a specified minimum value
assert_all_greater_than

Assert input is greater than a specified minimum value
assert_create_chain

Create Chains of Assertions
assert_character_vector

Assert input is a character vector
assert_character

Assert input is a character vector
assert_dataframe

Assert input is a data frame
assert_class

Assert object belongs to class
assert_file_has_extension

Assert file extensions
assert_file_exists

Assert a file exists
assert_factor_vector

Assert input is a factor
assert_file_does_not_exist

Assert a file does not exist
assert_equal

Assert that the input objects are equal
assert_create

Create an assertion function
assert_all_files_have_extension

Assert file extensions
assert_directory_does_not_exist

Assert a directory does not exist
assert_all_files_exist

Assert that all files exist