vetr (version 0.2.7)

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

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. “%sshould be greater than 2”)

Value

a quoted expressions with err.msg attribute set

Format

An object of class call of length 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 “%sshould 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)).

See Also

vet()

Examples

Run this code
# NOT RUN {
## 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(.), "%sshould 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), "%sshould 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), "%sshould be numeric matrix")
SQR.NUM.MX.V2 <-
  vet_token(NUM.MX && SQR, "%sshould be a square numeric matrix")
vet(SQR.NUM.MX.V2, mx)
# }

Run the code above in your browser using DataCamp Workspace