Wrap R Tools for Debugging and Parametric Programming

Tools for writing and debugging R code. Provides: 'let()' (converts non-standard evaluation interfaces to parametric standard evaluation interfaces), '%.>%' dot-pipe (an 'S3' configurable pipe), 'build_frame()'/'draw_frame()' ('data.frame' example tools), 'qc()' (quoting concatenate), ':=' (named map builder), 'DebugFnW()' (capture function context on error for debugging), and more.

wrapr, is an R package that supplies powerful tools for writing and debugging R code.


Primary wrapr services include:

  • let() (let block)
  • %.>% (dot arrow pipe)
  • := (named map builder)
  • λ() (anonymous function builder)
  • DebugFnW() (function debug wrappers)


let() allows execution of arbitrary code with substituted variable names (note this is subtly different than binding values for names as with base::substitute() or base::with()).

The function is simple and powerful. It treats strings as variable names and re-writes expressions as if you had used the denoted variables. For example the following block of code is equivalent to having written "a + a".

a <- 7
  c(VAR = 'a'),

This is useful in re-adapting non-standard evaluation interfaces (NSE interfaces) so one can script or program over them.

We are trying to make let() self teaching and self documenting (to the extent that makes sense). For example try the arguments "eval=FALSE" prevent execution and see what would have been executed, or debug=TRUE to have the replaced code printed in addition to being executed:

  c(VAR = 'a'),
  eval = FALSE,
    VAR + VAR
 #  {
 #      a + a
 #  }
  c(VAR = 'a'),
  debugPrint = TRUE,
    VAR + VAR
 #  $VAR
 #  [1] "a"
 #  {
 #      a + a
 #  }
 #  [1] 14

Please see vignette('let', package='wrapr') for more examples. For working with dplyr 0.7.* we suggest also taking a look at an alternate approach called seplyr.

%.>% (dot arrow pipe)

%.>% dot arrow pipe is a strict pipe with intended semantics:

That is: %.>% does not alter any function arguments that are not explicitly named. %.>% is designed to be explicit and simple.

The effect looks is show below.

The following two expressions should be equivalent:

 #  [1] 0.8919465
4 %.>% sin(.) %.>% exp(.) %.>% cos(.)
 #  [1] 0.8919465

The notation is quite powerful as it treats pipe stages as expression parameterized over the variable ".". This means you do not need to introduce functions to express stages. The following is a valid dot-pipe:

1:4 %.>% .^2 
 #  [1]  1  4  9 16

The notation is also very regular in that expressions have the same iterpretation be then surrounded by parenthesis, braces, or as-is:

1:4 %.>% { .^2 } 
 #  [1]  1  4  9 16
1:4 %.>% ( .^2 )
 #  [1]  1  4  9 16

Regularity can be a big advantage in teaching and comprehension. Please see "In Praise of Syntactic Sugar" for more details.

:= (named map builder)

:= is the "named map builder". It allows code such as the following:

'a' := 'x'
 #    a 
 #  "x"

The important property of named map builder is it accepts values on the left-hand side allowing the following:

name <- 'variableNameFromElsewhere'
name := 'newBinding'
 #  variableNameFromElsewhere 
 #               "newBinding"

A nice property is := commutes (in the sense of algebra or category theory) with R's concatenation function c(). That is the following two statements are equivalent:

c('a', 'b') := c('x', 'y')
 #    a   b 
 #  "x" "y"
c('a' := 'x', 'b' := 'y')
 #    a   b 
 #  "x" "y"

The named map builder is used to make seplyr notation much more manageable.

λ() (anonymous function builder)

λ() is a concise abstract function creator or "lambda abstraction". It is a placeholder that allows the use of the λ-character for very concise function abstraction.


# Make sure lambda function builder is in our enironment.
# square numbers 1 through 4
sapply(1:4, λ(x, x^2))
 #  [1]  1  4  9 16


DebugFnW() wraps a function for debugging. If the function throws an exception the execution context (function arguments, function name, and more) is captured and stored for the user. The function call can then be reconstituted, inspected and even re-run with a step-debugger. Please see our free debugging video series and vignette('DebugFnW', package='wrapr') for examples.


Install with either:



# install.packages("devtools")


Note: wrapr is meant only for "tame names", that is: variables and column names that are also valid simple (without quotes) R variables names.


wrapr 1.1.1 2018-01-20

  • Fix some null/blank substitution issues.
  • Minor documentation improvements.

wrapr 1.1.0 2018-01-03

  • minor doc improvements.
  • fix deparse in qae() and qe().
  • Deprecate ateval(), seval(), beval(), and "stringsubs".
  • add qs().
  • add dereference and class-supplied function to pipes.

wrapr 1.0.2 2017-12-13

  • add "to dot" pipe.
  • harden := a bit.
  • let qc() have names.
  • add qae().
  • add map_to_char().

wrapr 1.0.1 2017-11-17

  • Better error msgs.
  • Bit more debugging info.
  • Add grepdf() and qc().

wrapr 1.0.0 2017-10-04

  • Add mapsyms() function.

wrapr 0.4.2 2017-08-31

  • Work on location of lambda-definition (do NOT write into environment until asked).
  • Minor check fixes.

wrapr 0.4.1 2017-08-24

  • Do not insist let-mapping be invertible.
  • Migrate named map builder and lambda from seplyr.

wrapr 0.4.0 2017-07-22

  • Allow non-strict names.
  • Insist let-mapping be invertible.

wrapr 0.3.0 2017-07-08

  • Introduce "dot arrow" pipe %.>%

wrapr 0.2.0 2017-07-05

  • Switch to abstract syntax tree substitution.
  • Allow variable swaps.

wrapr 0.1.3 2017-06-13

  • More flexible treatment of NULL.
  • Add non string based version of let() replacement.

wrapr 0.1.2 2017-04-13

  • add ateval()

wrapr 0.1.1 2017-03-13

  • Allow names in let.

wrapr 0.1.0 2017-02-10

  • First version (some fns, from replyr package).

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.5.0 by John Mount, 10 days ago

https://github.com/WinVector/wrapr, http://winvector.github.io/wrapr/

Report a bug at https://github.com/WinVector/wrapr/issues

Browse source code at https://github.com/cran/wrapr

Authors: John Mount [aut, cre], Nina Zumel [aut], Win-Vector LLC [cph]

Documentation:   PDF Manual  

GPL-3 license

Imports utils

Suggests parallel, testthat, knitr, rmarkdown

Imported by WVPlots, cdata, rqdatatable, rquery, vtreat.

Depended on by replyr, seplyr, sigr.

See at CRAN