adorn 
A framework for creating function decorators in R.
A decorator wraps a function to add behaviour such as logging, timing or caching, without changing the function itself. adorn applies decorators with an infix operator, %@%, which reads top to bottom:
library(adorn)
shout <- decorator(function(f, ...) toupper(f(...)))
greet <- shout %@% function(who) paste("hello", who)
greet("world")
#> [1] "HELLO WORLD"The point of adorn is that writing your own decorator is easy. adorn ships no decorators of its own; it is the framework for making them. The examples below use two small decorators, logged and timed, defined in Using decorators. vignette("writing-decorators") builds more, such as memoize, once and retry, with the public API.
adorn is in early development, so the API may still change.
Installation
# install.packages("pak")
pak::pak("dyfanjones/adorn")Using decorators
First, two basic decorators (see Writing your own decorator for how they work):
logged <- decorator(function(f, ...) {
name <- decorator_context()$name
message("-> ", name)
on.exit(message("<- ", name))
f(...)
})
timed <- decorator(function(f, ..., digits = 1) {
name <- decorator_context()$name
start <- Sys.time()
on.exit({
secs <- round(as.numeric(Sys.time() - start, units = "secs"), digits)
message(name, " took ", secs, " s")
})
f(...)
})Apply one with %@%:
slow_add <- timed %@% function(x, y = 1) {
Sys.sleep(0.1)
x + y
}
slow_add(2)
#> slow_add took 0.1 s
#> [1] 3Stack decorators with more %@%; the one on the left is the outermost. decorators() lists the stack and undecorate() returns the original function.
tracked <- logged %@% timed(digits = 2) %@% function(x) x * 2
tracked(21)
#> -> tracked
#> tracked took 0 s
#> <- tracked
#> [1] 42
decorators(tracked) # "logged" "timed"
undecorate(tracked)(5) # 10, the original functionDecorators can be combined into a reusable bundle before they are applied:
logged_timed <- logged %@% timed
f <- logged_timed %@% function(x) x + 1Names
A decorator is named from how you write it next to %@%: timed %@% f and timed(digits = 2) %@% f both give "timed". That is the name decorators() reports. Pass name to decorator() to set it yourself. Inside a decorator, decorator_context()$name is the name the decorated function was called by (fib(10) gives "fib"); calls with no usable name, such as lapply(x, f), fall back to the name of the decorated function, or "<anonymous>".
A decorated function keeps the formal arguments of the original, so argument matching, defaults, missing(), lazy evaluation and formals() behave as before.
Writing your own decorator
A decorator is an ordinary function whose first argument is the function being decorated. decorator() turns it into a decorator. There are two styles, chosen by whether your function has a ... argument.
The first argument always receives the function to decorate, whatever you name it, and it can’t have a default. Decorator parameters go after it. adorn can’t check the name, so a signature like function(bob, f) is accepted but treats bob as the function.
Call style runs on every call. Arguments after ... are parameters, set by calling the decorator.
require_positive <- decorator(function(f, ..., arg = "x") {
args <- list(...)
if (any(args[[arg]] <= 0)) stop(arg, " must be positive", call. = FALSE)
f(...)
})
root <- require_positive(arg = "x") %@% function(x) sqrt(x)
root(16) # 4
root(-1) # Error: x must be positiveFactory style has no .... Your function runs once, when the function is decorated, and returns the replacement, so each decorated function gets its own state.
counted <- decorator(function(f) {
n <- 0
function(...) {
n <<- n + 1
message(decorator_context()$name, " call #", n)
f(...)
}
})
ping <- counted %@% function() "pong"
ping()
#> ping call #1
#> [1] "pong"| You want | Write |
|---|---|
| Code on every call | decorator(function(f, ...) { ...; f(...) }) |
| State per decorated function | decorator(function(f) { state <- ...; function(...) { ...; f(...) } }) |
| Options | Arguments after ... (call style) or after f (factory style) |
| The function’s name | decorator_context()$name |
If a decorator’s own code fails, the error is reported against the decorator, for example Error in logged(f, ...). vignette("writing-decorators") has fuller examples, including memoize, once and retry. vignette("designing-decorators") covers choosing between the two styles, what a decorated call costs, and the mistakes that are easy to make. vignette("partial-decorators") shows how a factory can change the decorated function’s signature with formals = "replace", for partial application.
Decorating existing code: decorate()
%@% is for functions you write. decorate() is for code that already exists, and is the only way to reach a method that lives inside a generic or class. It is an S7 generic that dispatches on the target:
target |
Example | Returns |
|---|---|---|
| a function | decorate(stats::runif, logged) |
the decorated function (the original is untouched) |
| the name of an S3 generic | decorate("print", logged, class = "money") |
the method, replaced in place |
| an S4 generic | decorate(area, timed, signature = "Square") |
the method, replaced in place |
| an S7 generic | decorate(speak, timed, class = Dog) |
the method, replaced in place |
| the name of an R6 method | decorate("add", logged, class = Counter) |
the generator, with the method replaced |
For a function, decorate(fn, d) is the same as d %@% fn. Pass a stack to apply several at once; the first is outermost.
sq <- decorate(function(x) x^2, logged %@% timed(digits = 1))
decorators(sq)
#> [1] "logged" "timed"Every method can be decorated in the explicit form, decorate(method, decorator, class), where S3 and R6 name the method with a string and S4 and S7 pass the generic itself. There is also a replacement form that works for all of them and mirrors S7’s method(generic, class) <- fn:
decorate(speak, Dog) <- logged %@% timed # S7
decorate(area, "Square") <- timed # S4
decorate(print, "money") <- logged # S3, give the generic function
decorate(Counter, "add") <- logged # R6, public methodsEach call wraps whatever the method is now, so calling decorate() again adds another layer on the outside. A method is replaced in place, so every caller of the generic sees the decorated version. In a package that decorates another package’s classes, do it in .onLoad() and expect the change to be seen by the whole session.
vignette("classes") walks through S3, S4, S7 and R6, both for methods you define and for methods that already exist.
Any package can add a target type, because decorate() is an S7 generic:
library(S7)
Pipeline <- new_class("Pipeline", properties = list(steps = class_list))
method(decorate, Pipeline) <- function(target, decorator, ...) {
target@steps <- lapply(target@steps, decorator)
target
}