vet_token: Vetting Tokens With Custom Error Messages

Description

Utility function to generate vetting tokens with attached error messages. You should only need to use this if the error message produced naturally by vetr is unclear. Several predefined tokens created by this function are also documented here.

Usage

vet_token(exp, err.msg = "%s")
NO.NA
NO.INF
GTE.0
LTE.0
GT.0
LT.0
INT.1
INT.1.POS
INT.1.NEG
INT.1.POS.STR
INT.1.NEG.STR
INT
INT.POS
INT.NEG
INT.POS.STR
INT.NEG.STR
NUM.1
NUM.1.POS
NUM.1.NEG
NUM
NUM.POS
NUM.NEG
CHR.1
CHR
CPX
CPX.1
LGL
LGL.1

Value

a quoted expressions with err.msg attribute set

Format

An object of class call of length 2.

An object of class call of length 3.

Arguments

exp: an expression which will be captured but not evaluated.
err.msg: character(1L) a message that tells the user what the expected value should be, should contain a "%s" for sprintf to use (e.g. "%s should be greater than 2").

Details

Allows you to supply error messages for vetting to use for each error token. Your token should not contain top level && or ||. If it does your error message will not be reported because vetr looks for error messages attached to atomic tokens. If your token must involve top level && or ||, use I(x && y) to ensure that your error message is used by vet, but beware than in doing so you do not use templates within the I call as everything therein will be interpreted as a vetting expression rather than a template.

Error messages are typically of the form "%s should be XXX".

This package ships with many predefined tokens for common use cases. They are listed in the Usage section of this documentation. The tokens are named in format TYPE[.LENGTH][.OTHER]. For example INT will vet an integer vector, INT.1 will vet a scalar integer vector, and INT.1.POS.STR will vet a strictly positive integer vector. At this time tokens are predefined for the basic types as scalars or any-length vectors. Some additional checks are available (e.g. positive only values).

Every one of the predefined vetting tokens documented here implicitly disallows NAs. Numeric tokens also disallow infinite values. If you wish to allow NAs or infinite values just use a template object (e.g. integer(1L)).

Examples

Run this code

## Predefined tokens:
vet(INT.1, 1:2)
vet(INT.1 || LGL, 1:2)
vet(INT.1 || LGL, c(TRUE, FALSE))

## Check squareness
mx <- matrix(1:3)
SQR <- vet_token(nrow(.) == ncol(.), "%s should be square")
vet(SQR, mx)

## Let `vetr` make up error message; note `quote` vs `vet_token`
## Often, `vetr` does fine without explictly specified err msg:
SQR.V2 <- quote(nrow(.) == ncol(.))
vet(SQR.V2, mx)

## Combine some tokens, notice how we use `quote` at the combining
## step:
NUM.MX <- vet_token(matrix(numeric(), 0, 0), "%s should be numeric matrix")
SQR.NUM.MX <- quote(NUM.MX && SQR)
vet(SQR.NUM.MX, mx)

## If instead we used `vet_token` the overall error message
## is not used; instead it falls back to the error message of
## the specific sub-token that fails:
NUM.MX <- vet_token(matrix(numeric(), 0, 0), "%s should be numeric matrix")
SQR.NUM.MX.V2 <-
  vet_token(NUM.MX && SQR, "%s should be a square numeric matrix")
vet(SQR.NUM.MX.V2, mx)

Run the code above in your browser using DataLab