compileTypes: Convert Argument Annotations to Argument Checks

In mb706/typer: Type Annotations and Checks

Description

compileTypes uses function annotations of functions in the given environment and adds them to the functions as type checks. This way, if a function is called, it automatically checks the input value format. With its default values, compileTypes works on all functions in the calling environment. This way, if compileTypes() is called at the end of a package (e.g. in a file named zzz.R in the R directory), it converts all functions in that package.

Usage

compileTypes(env = parent.frame(), ...)

Arguments

env

The environment to parse. Defaults to parent.frame().

...

include or exclude, given as character(1) grep() patterns. These are applied in the order given, so it is possible to first include certain functions, then exclude a subset of these, and then include a subset of these excluded functions etc. This is usually not necessary to give, since compileTypes will automatically ignore functions that do not have decorators, but helps in cases where parameters have default values containing : or | characters. This does not switch of type checks for the function, and in fact may produce errors if a function containing type decorators is not converted.

Details

A function annotation for a parameter has the form

  parname = value : type | type | type

where type can be a class name or a vector of possible (atomic) values indicated as value(...). For special class names logical, character, numeric, list the mode is checked instead. The special class name integer checks for integer values (that may still be given as numeric, i.e. floating point, value). Suffixing any of these special class names with .na allows missing values (NAs): logical.na, character.na etc.

The special class name NULL allows NULL values.

Non-list mode class names can be suffixed with (n), where n is an integer indicating the required vector length. Further possibilities are (n, m) to indicate length between n and m. Leaving out n or m ((, m) or (n, )) only sets a minimum or maximum length.

The (n) suffix also works for value(...): value(1, 2)(1) specifies that a value can be 1 or 2. Note that value(1, 2) also allows c(1, 2) and c(1, 1, 2, 1).

Class names or value lists can be suffixed with [] to indicate "list of", or [n] to indicate "length n list of". Similarly to non list length indicators, a minimum and maximum can also be given ([n, m]), any of which can be omitted.

Conditions for each type can be added in [[ ]] and separated by ,. Special conditions are named, unique, uniquely.named, which apply to lists (and, in case of nested lists, only apply to the outermost list); other conditions should be expressions that are evaluated in the context of the given parameters as well as the function's environment (and should probably involve the value at hand.

A special value of the value part is .(dot), which indicates that no default value is given for the function: param = . : numeric.

Value

NULL

Note

The generated code calls functions from the checkmate package. Therefore, a package using compileTypes, should have checkmate in the Imports section of its DESCRIPTION file.

Examples

# this function takes a parameter that is either a vector of two integer
# numbers (either datatype integer or numeric), a vector of three numbers,
# or a named list of data.frame that all have more than two rows.
fun = function(a = .:integer(2) | numeric(3) |
    data.frame[] [[named, all(sapply(a, nrow) > 2)]]) {
  NULL
}

compileTypes()

mb706/typer documentation built on May 25, 2019, 9:34 p.m.