The rewrite() function applies a series of transformations to an input
function, fn and returns the result. This result can then be used in a
pipeline of rewrite_with() calls for further analysis.
rewrite_with(fn, callbacks, ...) rewrite(fn) analyse(fn) analyse_with(fn, callbacks, ...) rewrite_expr(expr) rewrite_expr_with(expr, callbacks, ...) analyse_expr(expr) analyse_expr_with(expr, callbacks, ...)
| fn | The function to rewrite |
|---|---|
| callbacks | The callbacks that should do the rewriting |
| ... | Additional parameters passed along to the callbacks. |
| expr | When invoked on expressions, in |
A rewritten function
The flow of transformations goes starts with rewrite() and is followed by a
series of rewrite_with() for additional rewrite callbacks. For analysis, it
starts with analyse() and is followed by a pipeline of analyse_with().
This functions will annotate a function's body with two attributes for each
sub-expression in the body. Each call expression in the body will be
annotated with these two attributes:
assigned_symbols: Variables that appear to the left of an assignment in a sub-expression of the call that is likely to affect the scope of the call.
bound: Variables that are either assigned to, thus potentially local in the scope, or function parameters from an enclosing scope, which will definitely be bound at this position.
Since R does not require that we declare local variables, and since the variables that are assigned to a local scope depend on the runtime execution of functions, we cannot determine with any certainty which variables will be assigned to in any given scope at any given program point. So the best we can do is figure out which variables are potentially assigned to. Which is what this function does.
The rules for when we are assigning to a local variable are a bit
complicated. For control structures, we can assume that assignments will
be to the local scope. People can change the implementation of these so it
isn't, but then they are only hurting themselves and deserve the extra
pain we can give them. For other call arguments, it gets a little more
complicated. With standard-evaluation, if we have an arrow assignment in a
function argument, then the assignment happens in the calling scope. So we
will assume this happens unless we are handling cases we know have NSE,
such as with. If an assignment is inside a block, however, we will
assume that NSE is in play, by default, and not consider it a local
assignment.
rewrite_with: Apply callbacks over fn to rewrite it.
rewrite: Function for starting a rewrite.
analyse: Function for running analysis callbacks
analyse_with: Apply callbacks over fn to analyse it.
rewrite_expr: Expression version of rewrite()
rewrite_expr_with: Expression version of rewrite_with()
analyse_expr: Expression version of analyse()
analyse_expr_with: Expression version of analyse_with()
rewrite_callbacks
f <- function(x) 2 + x cb <- rewrite_callbacks() %>% add_call_callback(f, function(expr, ...) { quote(2 + x) }) tr_f <- . %>% rewrite() %>% rewrite_with(cb) g <- function(y) y + f(y) tr_f(g)#> function (y) #> y + (2 + x) #> <environment: 0x107e42d50>collect_symbols <- function(expr, ...) { list(symbols = as.character(expr)) } callbacks <- analysis_callbacks() %>% with_symbol_callback(collect_symbols) f %>% analyse() %>% analyse_with(callbacks)#> $symbols #> [1] "+" "x" #>