typed

{typed} implements a type system for R, it has 3 main features:

• set variable types in a script or the body of a function, so they can’t be assigned illegal values
• set argument types in a function definition
• set return type of a function

The user can define their own types, or leverage assertions from other packages.

Under the hood variable types use active bindings, so once a variable is restricted by an assertion, it cannot be modified in a way that would not satisfy it.

Installation

Install with:

remotes::install_github("moodymudskipper/typed")

And attach with :

# masking warning about overriding `?`
library(typed, warn.conflicts = FALSE) 

Set variable type

Question mark notation and declare

Here are examples on how we would set types

Character() ? x # restrict x to "character" type
x <- "a"
x
#> [1] "a"

Integer(3) ? y <- 1:3 # restrict y to "integer" type of length 3
y
#> [1] 1 2 3

We cannot assign values of the wrong type to x and y anymore.

x <- 2
#> Error: type mismatch
#> `typeof(value)`: "double"   
#> `expected`:      "character"

y <- 4:5
#> Error: length mismatch
#> `length(value)`: 2
#>      `expected`: 3

y[1] <- 10
#> Error: type mismatch
#> `typeof(value)`: "character"
#> `expected`:      "integer"

But the right type will work.

x <- c("b", "c")

y <- c(1L, 10L, 100L)

declare is a strict equivalent, slightly more efficient, which looks like base::assign.

declare("x", Character())
x <- "a"
x
#> [1] "a"

declare("y", Integer(3), 1:3)
y
#> [1] 1 2 3

Assertion factories and assertions

Integer and Character are function factories (functions that return functions), thus Integer(3) and Character() are functions.

The latter functions operate checks on a value and in case of success return this value, generally unmodified. For instance :

Integer(3)(1:2)
#> Error: length mismatch
#> `length(value)`: 2
#>      `expected`: 3

Character()(3)
#> Error: type mismatch
#> `typeof(value)`: "double"   
#> `expected`:      "character"

We call Integer(3) and Character() assertions, and we call Integer and Character assertion factories.

The package contains many assertion factories (see ?assertion_factories), the main ones are:

• Any (No default restriction)
• Logical
• Integer
• Double
• Character
• List
• Environment
• Factor
• Matrix
• Data.frame
• Date
• Time (POSIXct)

Custom assertions

As we’ve seen with Integer(3), passing arguments to a assertion factory restricts the type.

For instance Integer has arguments length null_ok and ..., we already used length, null_ok is convenient to allow a default NULL value in addition to the "integer" type. In the dots we can use arguments named as functions and with the value of the expected result.

Integer(anyNA = FALSE) ? x <- c(1L, 2L, NA)
#> Error: `anyNA` mismatch
#> `anyNA(value)`: TRUE 
#> `expected`:     FALSE

Useful arguments might be for instance, anyDuplicated = 0L, names = NULL, attributes = NULL… Any available function can be used.

That makes assertion factories very flexible! If it is still not flexible enough, one can provide conditions using formulas in the .... Be careful to skip all named arguments by adding comas, or name the formula arguments ....

fruit <- Character(1, ... = "`value` is not a fruit!" ~ . %in% c("apple", "pear", "cherry"))

fruit ? x <- "potatoe"
#> Error: `value` is not a fruit!
#> `value %in% c("apple", "pear", "cherry")`: FALSE
#> `expected`:                                TRUE

The arguments can differ between assertion factories, for instance Data.frame has nrow, ncol, each, null_ok and ...

Data.frame() ? x <- iris
Data.frame(ncol = 2) ? x <- iris
#> Error: Column number mismatch
#> `ncol(value)`: 5
#>    `expected`: 2
Data.frame(each = Double()) ? x <- iris
#> Error: column 5 ("Species") type mismatch
#> `typeof(value)`: "integer"
#> `expected`:      "double"

Leverage assertions from other packages, build your own assertion factories

Some great packages provide assertions, and they can be used with typed provided that they take the object as a first input and return the object if no failure. Richie Cotton’s {assertive} and Michel Lang’s {checkmate} both qualify.

library(assertive)
assert_is_monotonic_increasing ? z
z <- 3:1
#> Error: is_monotonic_increasing : The values of assigned_value are not monotonic increasing.
#>   Position ValueBefore ValueAfter
#> 1      1/2           3          2
#> 2      2/3           2          1

If we want to use more than the first argument, we should create an assertion factory :

Monotonic_incr <- as_assertion_factory(assert_is_monotonic_increasing)
Monotonic_incr(strictly = TRUE) ? z
z <- c(1, 1, 2)
#> Error: is_monotonic_increasing : The values of value are not strictly monotonic increasing.
#>   Position ValueBefore ValueAfter
#> 1      1/2           1          1

as_assertion_factory can be used to create your own assertion factories from scratch too, in fact it’s used to build the native assertion factories of this package .

Constants

To define a constant, we just surround the variable by parentheses (think of them as a protection)

Double() ? (x) <- 1
x <- 2
#> Error: Can't assign to a constant

? (y) <- 1
y <- 2
#> Error: Can't assign to a constant

Set argument type

We can set argument types this way :

add <- ? function (x= ? Double(), y= 1 ? Double()) {
  x + y
}

Note that we started the definition with a ?, and that we gave a default to y, but not x. Note also the = sign next to x, necessary even when we have no default value. If you forget it you’ll have an error “unexpected ? in …”.

This created the following function, by adding checks at the top of the body

add
#> # typed function
#> function (x, y = 1) 
#> {
#>     check_arg(x, Double())
#>     check_arg(y, Double())
#>     x + y
#> }
#> # Arg types:
#> # x: Double()
#> # y: Double()

Let’s test it by providing a right and wrong type.

add(2, 3)
#> [1] 5
add(2, 3L)
#> Error: In `add(2, 3L)` at `check_arg(y, Double())`:
#> wrong argument to function, type mismatch
#> `typeof(value)`: "integer"
#> `expected`:      "double"

If we want to restrict x and y to the type “integer” in the rest of the body of the function we can use the ?+ notation :

add <- ? function (x= ?+ Double(), y= 1 ?+ Double()) {
  x + y
}

add
#> # typed function
#> function (x, y = 1) 
#> {
#>     check_arg(x, Double(), .bind = TRUE)
#>     check_arg(y, Double(), .bind = TRUE)
#>     x + y
#> }
#> # Arg types:
#> # x: Double()
#> # y: Double()

We see that it is translated into a check_arg call containing a .bind = TRUE argument.

I we want to restrict the quoted expression rather than the value of an argument, we can use ?~ :

identity_sym_only <- ? function (x= ?~ Symbol()) {
  x
}

a <- 1
identity_sym_only(a)
#> [1] 1
identity_sym_only(a + a)
#> Error: In `identity_sym_only(a + a)` at `check_arg(substitute(x), Symbol())`:
#> wrong argument to function, type mismatch
#> `typeof(value)`: "language"
#> `expected`:      "symbol"

identity_sym_only
#> # typed function
#> function (x) 
#> {
#>     check_arg(substitute(x), Symbol())
#>     x
#> }
#> <bytecode: 0x000000001cfe6008>
#> # Arg types:
#> # x: ~Symbol()

We see that it is translated into a check_arg call containing a call to substitute as the first argument. The ~ is kept in the attributes of the function.

We can also check the ..., for instance use function(... = ? Integer()) to check that only integers are passed to the dots, and use function(... = ?~ Symbol()) to check that all quoted values passed to ... are symbols.

The special assertion factory Dots can also be used, in that case the checks will apply to list(...) rather than to each element individually, for instance function(... = ? Dots(2)) makes sure the dots were fed 2 values. In a similar fashion function(... = ?~ Dots(2)) can be used to apply checks to the list of quoted argument passed to ....

Set function return type

To set a return type we use ? before the function definition as in the previous section, but we type an assertion on the left hand side.

add_or_subtract <- Double() ? function (x, y, subtract = FALSE) {
  if(subtract) return(x - y)
  x + y
}
add_or_subtract
#> # typed function
#> function (x, y, subtract = FALSE) 
#> {
#>     if (subtract) 
#>         return(check_output(x - y, Double()))
#>     check_output(x + y, Double())
#> }
#> # Return type: Double()

We see that the returned values have been wrapped inside check_output calls.

Putting it all together, write packages using {typed}

Let’s define our function for our package and document it with {roxygen2}. It is documented as usual,except that you’ll need to make sure to add the @name tag.

We declare types for the return value, for all arguments, and we declare a string msg.

#' add_or_subtract
#'
#' @param x double of length 1
#' @param y double of length 1
#' @param subtract whether to subtract instead of adding
#' @export
#' @name add_or_subtract
add_or_subtract <- 
  Double(1) ? function (
    x= ? Double(1), 
    y= ? Double(1), 
    subtract = FALSE ? Logical(1, anyNA = FALSE)
    ) {
    Character(1) ? msg
    if(subtract) {
      msg <- "subtracting"
      message(msg)
      return(x - y)
    }
      msg <- "adding"
      message(msg)
    x + y
  }

The created function will be the following, we see that Character(1) ? msg was changed into a declare call too, this is both for efficiency and readability. Unfamiliar users might be intimidated by ? and calls to ? don’t print nicely.

add_or_subtract
#> # typed function
#> function (x, y, subtract = FALSE) 
#> {
#>     check_arg(x, Double(1))
#>     check_arg(y, Double(1))
#>     check_arg(subtract, Logical(1, anyNA = FALSE))
#>     declare("msg", Character(1))
#>     if (subtract) {
#>         msg <- "subtracting"
#>         message(msg)
#>         return(check_output(x - y, Double(1)))
#>     }
#>     msg <- "adding"
#>     message(msg)
#>     check_output(x + y, Double(1))
#> }
#> # Return type: Double(1)
#> # Arg types:
#> # x: Double(1)
#> # y: Double(1)
#> # subtract: Logical(1, anyNA = FALSE)

Note that your package would import {typed} but ? won’t be exposed to the user, they will see it in the code but will be able to use ? just as before. In fact the most common standard use ?mean still works even when {typed} is attached.

Acknowledgements

This is inspired in good part by Jim Hester and Gabor Csardi’s work and many great efforts on static typing, assertions, or annotations in R, in particular:

• Gabor Csardy’s {argufy}
• Richie Cotton’s {assertive}
• Tony Fishettti’s {assertr}
• Hadley Wickham’s {assertthat}
• Michel Lang’s {checkmate}
• Joe Thorley’s {checkr}
• Joe Thorley’s {chk}
• Aviral Goel’s {contractr}
• Stefan Bache’s {ensurer}
• Brian Lee Yung Rowe’s {lambda.r}
• Kun Ren’s {rtype}
• Jim Hester’s {types}