Create a decorator

Description

decorator() turns an ordinary function into a decorator. The first argument of wrapper receives the function being decorated, whatever it is named, and it can’t have a default. adorn can’t check the name, so function(bob, f) is accepted but treats bob as the function; put parameters after the first argument. There are two styles, chosen by whether wrapper has a … argument:

Usage

decorator(wrapper, name = NULL, formals = c("keep", "replace"))

Arguments

wrapper A function, as described above. Its first argument receives the function to decorate, so it can’t have a default.
name Name shown when printing the decorator and in decorators(). By default it is taken from how the decorator is written when applied with %@% (timed %@% f gives “timed”, and retry(times = 5) %@% f gives “retry”). Set it to override that; “decorator” is the last resort.
formals What happens to the formal arguments of the decorated function. “keep” (the default) keeps those of the original. “replace” swaps them for those of the function a factory returns; it is an error for call style, which has no returned function. With “replace”, matching, defaults and missing() follow the returned function, so getting them right is up to the decorator. S3, S4 and S7 methods must still match their generic.

Details

  • Call style, function(f, …, <params>): the body runs on every call. … holds the arguments of that call; forward them with f(…).

  • Factory style, function(f, <params>): the body runs once, when the function is decorated, and returns the replacement function. Use this when the decorator needs state, such as a cache.

Arguments after … (call style) or after f (factory style) are decorator parameters. Set them by calling the decorator with named arguments: retry(times = 5), for a decorator named retry.

The decorator takes the formals of wrapper without the …, so args(retry) shows function(f, times = 3) and editors can complete it. A function passed to the decorator is always the one to decorate, never a parameter value, so give function-valued parameters by name: on_call(hook = my_hook). If the first argument is not a function, it is taken as the first parameter, so retry(5) means retry(times = 5).

If your decorator stores the result of f(…) before returning it, use withVisible() to keep functions that return invisible() quiet.

By default the decorated function keeps the formal arguments of the original, so argument matching, missing() and defaults behave as before. A factory can instead set formals = “replace” to give the decorated function the formals of the function it returns, which lets it change the signature (see vignette(“partial-decorators”)).

Value

A decorator: a function with the formals function(f, <params>). It decorates f when given one, and returns a configured decorator when f is missing.

Examples

library("adorn")

# Call style: runs on every call
shout <- decorator(function(f, ...) toupper(f(...)))

# Call style with a parameter
repeated <- decorator(function(f, ..., times = 2) {
  rep(f(...), times)
})

# Factory style: keeps state between calls
counted <- decorator(function(f) {
  n <- 0
  function(...) {
    n <<- n + 1
    message("call ", n)
    f(...)
  }
})

greet <- shout %@% function(who) paste("hello", who)
greet("world")
#> [1] "HELLO WORLD"

ones <- repeated(times = 3) %@% function() 1
ones()
#> [1] 1 1 1

# Replacing the formals: the decorated function takes only `y`
two_to := decorator(function(f) function(y) f(2, y), formals = "replace")
pow := two_to %@% function(x, y) x^y
pow(3)
#> [1] 8