Type: Package
Title: Extend the Behaviour of a Function without Explicitly Modifying it
Version: 0.3.0
Date: 2022-09-23
Maintainer: Harel Lustiger <tidylab@gmail.com>
Description: A decorator is a function that receives a function, extends its behaviour, and returned the altered function. Any caller that uses the decorated function uses the same interface as it were the original, undecorated function. Decorators serve two primary uses: (1) Enhancing the response of a function as it sends data to a second component; (2) Supporting multiple optional behaviours. An example of the first use is a timer decorator that runs a function, outputs its execution time on the console, and returns the original function's result. An example of the second use is input type validation decorator that during running time tests whether the caller has passed input arguments of a particular class. Decorators can reduce execution time, say by memoization, or reduce bugs by adding defensive programming routines.
License: MIT + file LICENSE
URL: https://tidylab.github.io/decorators/, https://github.com/tidylab/decorators
BugReports: https://github.com/tidylab/decorators/issues
Depends: R (≥ 3.5)
Imports: purrr, methods
Suggests: testthat
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-GB
RoxygenNote: 7.2.0
NeedsCompilation: no
Packaged: 2022-09-30 15:31:29 UTC; BETA
Author: Harel Lustiger ORCID iD [aut, cre], Tidylab [cph, fnd]
Repository: CRAN
Date/Publication: 2022-09-30 16:00:02 UTC

Pipe operator

Description

Pipe operator

NULL operator

Usage

lhs %>% rhs

x %||% y

Value

The result of rhs(lfs).

If rhs is NULL, will return lhs; otherwise returns rhs.


Measure Execution Time of Functions

Description

Wrap a function with a timer.

Usage

time_it(func, units = "auto", digits = 2)

Arguments

func

(function) A function to decorate.

units

(character) Units in which the results are desired, including: "auto", "secs", "mins", "hours", "days", and "weeks". See difftime.

digits

(integer) The number of significant digits to be used. See signif.

Value

(closure) An object that contains the original function bound to the environment of the decorator.

References

Examples

Sys.sleep <- time_it(base::Sys.sleep)
Sys.sleep(0.1)

Validate the Type of Input Arguments

Description

Wrap a function with a input validation.

Usage

validate_arguments(func)

Arguments

func

(function) A function to decorate.

Details

validate_arguments decorator allows the arguments passed to a function to be parsed and validated using the function’s annotations before the function is called.

How It Works

validate_arguments provides an extremely easy way to apply validation to your code with minimal boilerplate. The original function needs to have key-value pairs in its declaration, where the each value carries its designated class.

When to Use It

Examples: Functions with Built-in NA classes

Given a Customer ValueObject

Customer <- function(given = NA_character_, family = NA_character_)
    return(data.frame(given = given, family = family))

When Customer is decorated with validate_arguments

Customer <- validate_arguments(Customer)

Then passing arguments of any type other then the declared type prompts an informative error.

In the Customer example, both input arguments given and family are declared as character.

Customer(given = "Bilbo", family = "Baggins") # Works as both arguments are character
#>   given  family
#> 1 Bilbo Baggins
try(Customer(given = "Bilbo", family = 90201)) # Fails because family is not a character
#> Error in Customer(given = "Bilbo", family = 90201) : 
#>   family is of type `numeric` rather than `character`!

Value

(closure) An object that contains the original function bound to the environment of the decorator.

Note

The original function must have default values of the designated type.

References

Examples

Car <- function(model = NA_character_, hp = NA_real_){
    return(data.frame(model = model, hp = hp))
}

Car <- validate_arguments(Car)
try(Car(model = 555, hp = 120)) # fails because model is numeric rather than character