Movatterモバイル変換

Title:	Trust, but Verify
Description:	Declarative template-based framework for verifying that objects meet structural requirements, and auto-composing error messages when they do not.
Version:	0.2.19
Depends:	R (≥ 3.2.0)
License:	GPL-2 |GPL-3 [expanded from: GPL (≥ 2)]
URL:	https://github.com/brodieG/vetr
BugReports:	https://github.com/brodieG/vetr/issues
VignetteBuilder:	knitr
Imports:	methods, stats, utils
Suggests:	knitr, rmarkdown, unitizer
RoxygenNote:	7.3.3
Encoding:	UTF-8
NeedsCompilation:	yes
Packaged:	2025-11-22 22:33:09 UTC; brodie
Author:	Brodie Gaslam [aut, cre], Paxdiablo [cph] (Hash table implementation in src/pfhash.h), R Core Team [cph] (Used/adapted several code snippets from R sources, see src/r-copied.c), Michael Chirico [ctb]
Maintainer:	Brodie Gaslam <brodie.gaslam@yahoo.com>
Repository:	CRAN
Date/Publication:	2025-11-23 06:10:02 UTC

Trust, but Verify

Description

Declarative template-based framework for verifying that objects meetstructural requirements, and auto-composing error messages when they do not.

Author(s)

Maintainer: Brodie Gaslambrodie.gaslam@yahoo.com

Other contributors:

• Paxdiablo (Hash table implementation in src/pfhash.h) [copyright holder]

• R Core TeamR-core@r-project.org (Used/adapted several code snippets from R sources, see src/r-copied.c) [copyright holder]

• Michael Chiricomichaelchirico4@gmail.com (ORCID) [contributor]

See Also

Useful links:

• https://github.com/brodieG/vetr

• Report bugs athttps://github.com/brodieG/vetr/issues

Turn S3 Objects Into Templates

Description

Create templates for use byalike. Currently somewhatexperimental; behavior may change in future.

Usage

abstract(x, ...)## S3 method for class 'data.frame'abstract(x, ...)## Default S3 method:abstract(x, ...)## S3 method for class 'array'abstract(x, ...)## S3 method for class 'matrix'abstract(x, ...)## S3 method for class 'list'abstract(x, ...)## S3 method for class 'lm'abstract(x, ...)## S3 method for class 'environment'abstract(x, ...)## S3 method for class 'ts'abstract(x, what = c("start", "end", "frequency"), ...)

Arguments

Details

abstract is intended to create templates for use byalike. The result of abstraction is often a partiallyspecified object. This type of object may not be suited for use in typicalR computations and may cause errors (or worse) if you try to use them asnormal R objects.

There is no guarantee that theabstracted object is suitable for useas a template toalike as is. You may need to modify it further sothat it suits your purposes.

abstract is an S3 generic. The default method willdispatch on implicit classes, so if you attempt toabstract an objectwithout an explicitabstract method, it will get abstracted based onits implicit class. If you define your ownabstract method and do notwish further abstraction based on implicit classes do not useNextMethod.

S4 and RC objects are returned unchanged.

Value

abstracted object

Time Series

alike will treat time series parameter components with zero inthem as wildcards. This function allows you to create these wild card timeseries attributes since R does not allow direct creation/modification ofts attributes with zero values.

Make sure you do not try to use the templates you create with this foranything other than asalike templates since the result islikely undefined given R expects non zero values for thetsattribute and attempts to prevent such attributes.

Examples

iris.tpl <- abstract(iris)alike(iris.tpl, iris[1:10, ])alike(iris.tpl, transform(iris, Species=as.character(Species)))abstract(1:10)abstract(matrix(1:9, nrow=3))abstract(list(1:9, runif(10)))

Experimental Abstraction Method for GGPlot

Description

Not entirely sure this can ever work well since so much ofggplot isdone withproto objects and those do not really use meta data, whichmakesalike rather useless.

Usage

## S3 method for class 'ggplot'abstract(x, ...)

Compare Object Structure

Description

Similar toall.equal, but compares object structure rather thanvalue. Thetarget argument defines a template that thecurrentargument must match.

Usage

alike(target, current, env = parent.frame(), settings = NULL)

Arguments

Value

TRUE if target and current are alike, character(1L) describing whythey are not if they are not

alikeness

Generally speaking two objects are alike if they are of the same type (asdetermined bytype_alike) and length.type_alikehas special treatment for integer-like numerics and function-like objects.

Attributes on the objects are required to be recursivelyalike, thoughthe following attributes are treated specially:class,dim,dimnames,names,row.names,levels,tsp,andsrcref.

Exactly what makes two objectsalike is complex, but should beintuitive. The best way to understand "alikeness" is to review the examples.For a thorough exposition seethe vignette.

Note

The semantics of alikeness for language objects, formulas, andfunctions may change in the future.

See Also

type_alike,type_of,abstract,vetr_settings for more control ofsettings

Examples

## Type comparisonalike(1L, 1.0)         # TRUE, because 1.0 is integer-likealike(1L, 1.1)         # FALSE, 1.1 is not integer-likealike(1.1, 1L)         # TRUE, by default, integers are always considered realalike(1:100, 1:100 + 0.0)  # TRUE## We do not check numerics for integerness if longer than 100alike(1:101, 1:101 + 0.0)## Scalarness can now be checked at same time as typealike(integer(1L), 1)            # integer-like and length 1?alike(logical(1L), TRUE)         # logical and length 1?alike(integer(1L), 1:3)alike(logical(1L), c(TRUE, TRUE))## Zero length match any length of same typealike(integer(), 1:10)alike(1:10, integer())   # but not the other way around## Recursive objects compared recursivelyalike(  list(integer(), list(character(), logical(1L))),  list(1:10, list(letters, TRUE)))alike(  list(integer(), list(character(), logical(1L))),  list(1:10, list(letters, c(TRUE, FALSE))))## `NULL` is a wild card when nested within recursive objectsalike(list(NULL, NULL), list(iris, mtcars))alike(NULL, mtcars)    # but not at top level## Since `data.frame` are lists, we can compare them recursively:iris.fake <- transform(iris, Species=as.character(Species))alike(iris, iris.fake)## we even check attributes (factor levels must match)!iris.fake2 <- irislevels(iris.fake2$Species) <- c("setosa", "versicolor", "africana")alike(iris, iris.fake2)## We can use partially specified objects as templatesiris.tpl <- abstract(iris)str(iris.tpl)alike(iris.tpl, iris)## any row sample of iris matches our iris templatealike(iris.tpl, iris[sample(1:nrow(iris), 10), ])## but column order mattersalike(iris.tpl, iris[c(2, 1, 3, 4, 5)])## 3 x 3 integeralike(matrix(integer(), 3, 3), matrix(1:9, nrow=3))## 3 x 3, but not integer!alike(matrix(integer(), 3, 3), matrix(runif(9), nrow=3))## partial spec, any 3 row integer matrixalike(matrix(integer(), 3), matrix(1:12, nrow=3))alike(matrix(integer(), 3), matrix(1:12, nrow=4))## Any logical matrix (but not arrays)alike(matrix(logical()), array(rep(TRUE, 8), rep(2, 3)))## In order for objects to be alike, they must share a family## tree, not just a common classobj.tpl <- structure(TRUE, class=letters[1:3])obj.cur.1 <-  structure(TRUE, class=c("x", letters[1:3]))obj.cur.2 <-  structure(TRUE, class=c(letters[1:3], "x"))alike(obj.tpl, obj.cur.1)alike(obj.tpl, obj.cur.2)## You can compare language objects; these are alike if they are self## consistent; we don't care what the symbols are, so long as they are used## consistently across target and current:## TRUE, symbols are consistent (adding two different symbols)alike(quote(x + y), quote(a + b))## FALSE, different functionalike(quote(x + y), quote(a - b))## FALSE, inconsistent symbolsalike(quote(x + y), quote(a + a))

Verify Values in Vector are Between Two Others

Description

Similar toisTRUE(all(x >= lo & x <= hi)) with default settings,except that it is substantially faster and returns a string describing thefirst encountered violation rather than FALSE on failure.

Usage

all_bw(x, lo = -Inf, hi = Inf, na.rm = FALSE, bounds = "[]")

Arguments

Details

You can modify the comparison to be strictly greater/less than via thebounds parameter, and the treatment of NAs withna.rm. Note that NAs areconsidered to be out of bounds by default. While technically incorrectsince we cannot know whether an NA value is in or out of bounds, thisassumption is both conservative and convenient. Zero lengthx will alwayssucceed.

Ifx andlo/hi are different types,lo/hi will be coerced to thetype ofx. Whenlo/hi are numeric andx is integer, iflo/hivalues are outside of the integer range then that side will be treated as ifyou had used-Inf/Inf.-Inf andInf meanlo andhi will beunbounded for all data types.

Value

TRUE if all values inx conform to the specified bounds, a stringdescribing the first position that fails otherwise

Examples

all_bw(runif(100), 0, 1)all_bw(runif(100) * 2, 0, 1)all_bw(NA, 0, 1)              # This is does not return NAall_bw(NA, 0, 1, na.rm=TRUE)vec <- c(runif(100, 0, 1e12), Inf, 0)all_bw(vec, 0)      # All +ve numbersall_bw(vec, hi=0)   # All -ve numbersall_bw(vec, 0, bounds="(]") # All strictly +ve numsall_bw(vec, 0, bounds="[)") # All finite +ve nums

Lightweight Benchmarking Function

Description

Evaluates provided expression in a loop and reports mean evaluation time.This is inferior tomicrobenchmark and other benchmarking tools in manyways except that it has zero dependencies or suggests which helps withpackage build and test times. Used in vignettes.

Usage

bench_mark(..., times = 1000L, deparse.width = 40)

Arguments

Details

Runsgc() before each expression is evaluated. Expressions are evaluatedin the order provided. Attempts to estimate the overhead of the loop byrunning a loop that evaluatesNULL thetimes times.

Unfortunately because this computes the average of all iterations it is verysusceptible to outliers in small sample runs, particularly with fast runningcode. For that reason the default number of iterations is one thousand.

Value

NULL, invisibly, reports timings as a side effect as screen output

Examples

bench_mark(runif(1000), Sys.sleep(0.001), times=10)

Set Element to NULL Without Removing It

Description

This function is required because there is no straightforward way toover-write a value in a list with NULL without completely removing the entryfrom the list as well.

Usage

nullify(obj, index)## Default S3 method:nullify(obj, index)

Arguments

Details

This returns a copy of the object modified with null slots; it doesnot modify the input argument.

Default method will attempt to convert non-list objects to listswithas.list, and then back to whatever they were by using afunction with namepaste0("as.", class(obj)[[1L]])if it exists and works. If the object cannot be coerced backto its original type the corresponding list will be returned.

If this is not appropriate for your object type you can write an S3 methodfor it.

Value

object with selected values NULLified

Note

attributes are copied from original object and re-applied to finalobject before return, which maynot make sense in some circumstances.

Examples

nullify(list(1, 2, 3), 2)nullify(call("fun", 1, 2, 3), 2)

Fuzzily Compare Types of Objects

Description

Type evaluation and comparison is carried out with special treatment fornumerics, integers, and function types. Whole number NA-free numeric vectorsof sufficiently short length (<100 by default) representable in the integertype are considered to be type integer. Closures, built-ins, and specialsare all treated as type closure.

Usage

type_of(object)type_alike(target, current, settings = NULL)

Arguments

Details

Specific behavior can be tuned with thetype.mode parameter to thevetr_settings() object passed as thesettings parameter to this function.

Value

Fortype_of character(1L) the type of the object, fortype_alikeeither TRUE, or a string describing why the types are not alike.

See Also

alike(),vetr_settings(), in particular the section aboutthetype.mode parameter which affects how this function behaves.

Examples

type_of(1.0001)          # numerictype_of(1.0)             # integer (`typeof` returns numeric)type_of(1)               # integer (`typeof` returns numeric)type_of(sum)             # closure (`typeof` returns builtin)type_of(`$`)             # closure (`typeof` returns special)type_alike(1L, 1)type_alike(1L, 1.1)type_alike(integer(), numeric(100))type_alike(integer(), numeric(101))  # too long

Verify Objects Meet Structural Requirements

Description

Use vetting expressions to enforce structural requirements and/or evaluatetest conditions for truth.tev is identical tovet except with reversedarguments for pipe based workflows.

Usage

vet(  target,  current,  env = parent.frame(),  format = "text",  stop = FALSE,  settings = NULL)tev(  current,  target,  env = parent.frame(),  format = "text",  stop = FALSE,  settings = NULL)

Arguments

Value

TRUE if validation succeeds, otherwise varies according to valuechosen with parameterstop

Vetting Expressions

Vetting expressions can be template tokens, standard tokens, or anyexpression built with them,||,&&, and parentheses. Template tokensare R objects that define the required structure, much like theFUN.VALUEargument tovapply(). Standard tokens are R expressions evaluated andchecked for beingall(TRUE).

Standard tokens are distinguished from templates by whether they referencethe. symbol or not. If you have a need to reference an object bound to. in a vetting expression, you can escape the. with an extra dot (i.e.use.., and... for.., and so forth for symbols comprising onlydots). If you use standard tokens in your packages you will need to includeutils::globalVariables(".") as a top-level call to avoid the "no visiblebinding for global variable '.'"' R CMD check NOTE. Standard tokens thatreturn a string like e.g.all.equal(x, .) will result in that string beingincorporated into the error message.

Seevignette('vetr', package='vetr') and examples for details on howto craft vetting expressions.

See Also

vetr() for a version optimized to vet function arguments,alike() for how templates are used,vet_token() for how to specifycustom error messages and also for predefined validation tokens for commonuse cases,all_bw() for fast bounds checks.

Examples

## Template token vettingvet(numeric(2L), runif(2))vet(numeric(2L), runif(3))vet(numeric(2L), letters)try(vet(numeric(2L), letters, stop=TRUE))## Standard token vettingvet(. > 0, runif(2))## Expression made of standard and template tokens.vet(numeric(1) && . > 0, 1)try(vet(numeric(1) && . > 0, 1:2))try(vet(numeric(1) && . > 0, -1))## `tev` just reverses target and current## if(getRversion() >= "4.1.0") { # would be a parse error so commented##   runif(2) |> tev(numeric(2L))##   runif(3) |> tev(numeric(2L))## }## Zero length templates are wild cardsvet(numeric(), runif(2))vet(numeric(), runif(100))vet(numeric(), letters)## This extends to data.framesiris.tpl <- iris[0,]   # zero row matches any # of rowsiris.1 <- iris[1:10,]iris.2 <- iris[1:10, c(1,2,3,5,4)]  # change col ordervet(iris.tpl, iris.1)vet(iris.tpl, iris.2)## Short (<100 length) integer-like numerics will## pass for integervet(integer(), c(1, 2, 3))vet(integer(), c(1, 2, 3) + 0.1)## 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 runtimetpl <- 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))vet(tpl, val.1)vet(tpl, val.2)## See `example(alike)` for more template examples## Standard tokens allow you to check valuesvet(. > 0, runif(10))vet(. > 0, -runif(10))## Zero length token results are considered TRUE,## as is the case with `all(logical(0))`vet(. > 0, numeric())## `all_bw` is like `isTRUE(all(. >= x & . <= y))`, but## ~10x faster for long vectors:vet(all_bw(., 0, 1), runif(1e6) + .1)## You can combine templates and standard tokens with## `&&` and/or `||`vet(numeric(2L) && . > 0, runif(2))vet(numeric(2L) && . > 0, runif(10))vet(numeric(2L) && . > 0, -runif(2))## Using pre-defined tokens (see `?vet_token`)vet(INT.1, 1)vet(INT.1, 1:2)vet(INT.1 && . %in% 0:1 || LGL.1, TRUE)vet(INT.1 && . %in% 0:1 || LGL.1, 1)vet(INT.1 && . %in% 0:1 || LGL.1, NA)## Vetting expressions can be assembled from previously## defined tokensscalar.num.pos <- quote(numeric(1L) && . > 0)foo.or.bar <- quote(character(1L) && . %in% c('foo', 'bar'))vet.exp <- quote(scalar.num.pos || foo.or.bar)vet(vet.exp, 42)vet(scalar.num.pos || foo.or.bar, 42)  # equivalentlyvet(vet.exp, "foo")vet(vet.exp, "baz")## Standard tokens that return strings see the string shown## in the error message:vet(all.equal(., 2), 1)

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 byvetr is unclear. Several predefined tokens created by this functionare also documented here.

Usage

vet_token(exp, err.msg = "%s")NO.NANO.INFGTE.0LTE.0GT.0LT.0INT.1INT.1.POSINT.1.NEGINT.1.POS.STRINT.1.NEG.STRINTINT.POSINT.NEGINT.POS.STRINT.NEG.STRNUM.1NUM.1.POSNUM.1.NEGNUMNUM.POSNUM.NEGCHR.1CHRCPXCPX.1LGLLGL.1

Arguments

Format

An object of classcall of length 2.

An object of classcall of length 2.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

An object of classcall of length 3.

Details

Allows you to supply error messages for vetting to use for each errortoken. Your token should not contain top level&& or||. Ifit does your error message will not be reported becausevetr looks forerror messages attached to atomic tokens. If your token must involvetop level&& or||, useI(x && y) to ensure thatyour error message is used byvet, but beware than in doing so you donot use templates within theI call as everything therein will beinterpreted 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. Theyare listed in theUsage section of this documentation. The tokensare named in formatTYPE[.LENGTH][.OTHER]. For exampleINT will vet an integer vector,INT.1 will vet a scalar integervector, andINT.1.POS.STR will vet a strictly positive integer vector.At this time tokens are predefined for the basic types as scalars orany-length vectors. Some additional checks are available (e.g. positive onlyvalues).

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

Value

a quoted expressions witherr.msg attribute set

Note

This will only work with standard tokens containing.. Anythingelse will be interpreted as a template token.

See Also

vet()

Examples

## Predefined tokens:vet(INT.1, 1:2)vet(INT.1 || LGL, 1:2)vet(INT.1 || LGL, c(TRUE, FALSE))## Check squarenessmx <- 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)

Verify Function Arguments Meet Structural Requirements

Description

Use vetting expressions to enforce structural requirements for functionarguments. Works just likevet(), except that the formals of theenclosing function automatically matched to the vetting expressions providedin....

Usage

vetr(..., .VETR_SETTINGS = NULL)

Arguments

Details

Only named arguments may be vetted; in other words it is not possible to vetarguments passed via....

Value

TRUE if validation succeeds, otherwisestop with error messagedetailing nature of failure.

Vetting Expressions

Vetting expressions can be template tokens, standard tokens, or anyexpression built with them,||,&&, and parentheses. Template tokensare R objects that define the required structure, much like theFUN.VALUEargument tovapply(). Standard tokens are R expressions evaluated andchecked for beingall(TRUE).

Standard tokens are distinguished from templates by whether they referencethe. symbol or not. If you have a need to reference an object bound to. in a vetting expression, you can escape the. with an extra dot (i.e.use.., and... for.., and so forth for symbols comprising onlydots). If you use standard tokens in your packages you will need to includeutils::globalVariables(".") as a top-level call to avoid the "no visiblebinding for global variable '.'"' R CMD check NOTE. Standard tokens thatreturn a string like e.g.all.equal(x, .) will result in that string beingincorporated into the error message.

Seevignette('vetr', package='vetr') and examples for details on howto craft vetting expressions.

Note

vetr will force evaluation of any arguments that are beingchecked (you may omit arguments that should not be evaluate fromvetr)

See Also

vet(), in particularexample(vet).

Examples

## Look at `?vet` examples for more details on how to craft## vetting expressions.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 argumentfun2 <- 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 runtimetpl <- 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.1val.1.a[[2]] <- val.1.a[[2]][, 1:8]try(fun3(val.1, val.1.a))

Test Objects

Description

Objects used for testing purposes only.

Generate Control Settings For vetr and alike

Description

Utility function to generate setting values. We strongly recommendthat you generate the settings outside of function calls so that settinggeneration does not become part of thevet/vetr/alike evaluation asthat could add noticeable overhead to the function evaluation.

Usage

vetr_settings(  type.mode = 0L,  attr.mode = 0L,  lang.mode = 0L,  fun.mode = 0L,  rec.mode = 0L,  suppress.warnings = FALSE,  fuzzy.int.max.len = 100L,  width = -1L,  env.depth.max = 65535L,  symb.sub.depth.max = 65535L,  symb.size.max = 15000L,  nchar.max = 65535L,  track.hash.content.size = 63L,  env = NULL,  result.list.size.init = 64L,  result.list.size.max = 1024L)

Arguments

Details

Settings afterfuzzy.int.max.len are fairly low level and exposed mostlyfor testing purposes. You should generally not need to use them.

Note that a successful evaluation of this function does not guarantee acorrect settings list. Those checks are carried out internally byvet/vetr/alike.

Value

list with all the setting values

See Also

type_alike,alike,vetr

Examples

type_alike(1L, 1.0, settings=vetr_settings(type.mode=2))## better if you are going to re-use settings to reduce overheadset <- vetr_settings(type.mode=2)type_alike(1L, 1.0, settings=set)