CRAN version badge Travis build status Code coverage

nseval is the missing API for non-standard evaluation and metaprogramming in R.

Who NSEval is for

nseval might be for you if:



What nseval does

nseval introduces two S3 classes: quotation, and dots, which mirror R’s promises and ..., respectively. Unlike their counterparts, these are ordinary data objects, and can be assigned to variables and be manipulated without triggering evaluation.

There is a set of consistently-named accessors and constructors for capturing, constructing, and manipulating these objects.

Quick intro / transitioning from base R to NSEval

Why nse is needed

Before R, there was S, and S had some metaprogramming facilities, exposed by functions like parent.frame, substitute, match.call, do.call, quote, alist, eval, and so on. R duplicated that API. But S did not have lexical scoping, closures, or the notion of an environment, whereas R has all those things.

In S, lazily evaluated arguments could be evaluated simply by stepping one step up in the call stack and evaluating them in that context. This is not the case with R, because environments can come from different sources via ..., drop off the stack, and then be re-activated via closures (and these situations happen frequently enough in everyday code).

So R has been coping with a metaprogramming API that was not designed with R’s capabilities in mind. Because the S interface is not sufficient to model R behavior, we end up with consequences such as:

and so on. As a result, R functions that use the S metaprogramming API often end up with unintended behaviors that don’t “fit” R: they lose track of variable scope, suffer name collisions, are difficult to compose, etc.

The good news is that you can simply replace most uses of match.call, parent.frame, do.call and such with their equivalents from nseval, and may then have fewer of these kinds of problems.

What nseval doesn’t do

nseval doesn’t implement quasiquotation or hygeinic macros or code coverage or DSLs or interactive debugging. But it is intended to be a solid foundation to build those kinds of tools on! Watch this space.

nseval doesn’t introduce any fancy syntax – the only nonstandard evaluation in its own interface is name lookup and quoting, and standard-evaluating equivalents are always also present.

nseval doesn’t try and remake all of R’s base library, just the parts about calls and lazy evaluation.

nseval has no install dependencies and should play well with base R or any other ’verse.

Similar packages

Some other packages have tread similar ground:

Further reading

It turns out that R’s implementation of lazy evaluation via “promise” objects amount to a recreation of fexprs. On the topic of how to work with fexprs, particularly in combination with lexical scope and environments, John Shutt’s 2010 PhD thesis has been helpful.