vetr: Verify Function Arguments Meet Structural Requirements

Description

Use vetting expressions to enforce structural requirements for function arguments. Works just like vet(), except that the formals of the enclosing function automatically matched to the vetting expressions provided in ....

Usage

vetr(..., .VETR_SETTINGS = NULL)

Arguments

...

vetting expressions, each will be matched to the enclosing function formals as with match.call() and will be used to validate the value of the matching formal.

.VETR_SETTINGS

a settings list as produced by vetr_settings(), or NULL to use the default settings. Note that this means you cannot use vetr with a function that takes a .VETR_SETTINGS argument

Value

TRUE if validation succeeds, otherwise stop with error message detailing nature of failure.

Vetting Expressions

Vetting expressions can be template tokens, standard tokens, or any combination of template and standard tokens combined with && and/or ||. Template tokens are R objects that define the required structure, much like the FUN.VALUE argument to vapply(). Standard tokens are tokens that contain the . symbol and are used to vet values.

See vignette('vetr', package='vetr') and examples for details on how to craft vetting expressions.

Examples

Run this code

# NOT RUN {
fun1 <- function(x, y) {
  vetr(integer(), LGL.1)
  TRUE   # do some work
}
fun1(1:10, TRUE)
try(fun1(1:10, 1:10))

## only vet the second argument
fun2 <- function(x, y) {
  vetr(y=LGL.1)
  TRUE   # do some work
}
try(fun2(letters, 1:10))

## Nested templates; note, in packages you should consider
## defining templates outside of `vet` or `vetr` so that
## they are computed on load rather that at runtime
tpl <- list(numeric(1L), matrix(integer(), 3))
val.1 <- list(runif(1), rbind(1:10, 1:10, 1:10))
val.2 <- list(runif(1), cbind(1:10, 1:10, 1:10))
fun3 <- function(x, y) {
  vetr(x=tpl, y=tpl && ncol(.[[2]]) == ncol(x[[2]]))
  TRUE   # do some work
}
fun3(val.1, val.1)
try(fun3(val.1, val.2))
val.1.a <- val.1
val.1.a[[2]] <- val.1.a[[2]][, 1:8]
try(fun3(val.1, val.1.a))
# }