Extend constructive

library(constructive)

We detail in this vignette how {constructive} works and how you might extend it by defining custom .cstr_construct.<class>() and .cstr_construct.<class>.<constructor>() methods.

The functions .cstr_new_class() and .cstr_new_constructor() can be used to create custom constructors from templates. The easiest workflow is probably to take a look at the package {constructive.examples} which will guide you through the process, then call these functions with the argument commented = TRUE.

If this is not enough, or if you want to know more, we describe below in more details how the package and its key functions work.

`construct()` and `.cstr_construct()`

.cstr_construct() builds code recursively, without checking the inputs or output validity, without error handling, and without formatting.
construct() wraps .cstr_construct() and does this extra work.
.cstr_construct() is a generic and many methods are implemented in the package, for instance construct(iris) will call .cstr_construct.data.frame() which down the line will call .cstr_construct.numeric() and .cstr_construct.factor() to construct its columns.
.cstr_construct() contains extra logic to :
- Attempt to match its data input to a list of objects provided to the data argument.
- Restrict the dispatch so the classes argument and the functions construct_base() and construct_dput() can work.

.cstr_construct
#> function(x, ..., data = NULL, classes = NULL) {
#>   data_name <- perfect_match(x, data)
#>   if (!is.null(data_name)) return(data_name)
#>   if (is.null(classes)) {
#>     UseMethod(".cstr_construct")
#>   } else if (identical(classes, "-")) {
#>     .cstr_construct.default(x, ..., classes = classes)
#>   } else if (classes[[1]] == "-") {
#>     cl <- setdiff(.class2(x), classes[-1])
#>     UseMethod(".cstr_construct", structure(NA_integer_, class = cl))
#>   } else {
#>     cl <- intersect(.class2(x), classes)
#>     UseMethod(".cstr_construct", structure(NA_integer_, class = cl))
#>   }
#> }
#> <bytecode: 0x5579bd9f7070>
#> <environment: namespace:constructive>
# a character vector
.cstr_construct(letters)
#> [1] "c("                                                                                                        
#> [2] "  \"a\", \"b\", \"c\", \"d\", \"e\", \"f\", \"g\", \"h\", \"i\", \"j\", \"k\", \"l\", \"m\", \"n\", \"o\","
#> [3] "  \"p\", \"q\", \"r\", \"s\", \"t\", \"u\", \"v\", \"w\", \"x\", \"y\", \"z\""                             
#> [4] ")"
# a constructive object, 
construct(letters)
#> c(
#>   "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o",
#>   "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"
#> )

`.cstr_construct.<class>()` methods

.cstr_construct.<class>() methods are generics themselves, they typically have this form:

.cstr_construct.Date <- function(x, ...) {
  opts <- list(...)$opts$Date %||% opts_Date()
  if (is_corrupted_Date(x) || opts$constructor == "next") return(NextMethod())
  UseMethod(".cstr_construct.Date", structure(NA, class = opts$constructor))
}

opts contains options passed to the ... or template arguments of construct() through the opts_*() functions, we fall back to a default value if none were provided. The list(...)$opts idiom is used in various places, it allows us to forward the dots conveniently.
If the object is corrupted or if the user decided to bypass the current method by choosing “next” as a constructor for this class, we return NextMethod() to forward all our inputs to a lower level constructor.
We finally dispatch to a method based on the constructor, and not on the object’s class as is done traditionally. This explains the unusual look of the UseMethod() call above.

`opts_<class>()` function

When implementing a new method you’ll need to define and export the corresponding opts_<class>() function. It provides to the user with a way to choose a constructor and additional parameters, and sets the default behavior.

It should always have this form:

opts_Date <- function(
    constructor = c(
      "as.Date", "as_date", "date", "new_date", "as.Date.numeric", "as_date.numeric", "next", "double"), 
    ..., 
    origin = "1970-01-01") {
  .cstr_options("Date", constructor = constructor[[1]], ..., origin = origin)
}

The class is present in the name of the opts_<class>() function and as the first argument of .cstr_options().
A character vector of constructors is provided, starting with the default constructor
A “next” value is mandatory except for internal types.
Additional options retrievable by the constructor might be added, as we did here with origin
Note that we don’t use match.arg() here, because new constructors can be defined outside of the package.

`is_corrupted_<class>()` function

is_corrupted_<class>() checks if x has the right internal type and attributes, sometimes structure, so that it satisfies the expectations of a well formatted object of a given class.

If an object is corrupted for a given class we cannot use constructors for this class, so we move on to a lower level constructor by calling NextMethod() in .cstr_construct().

This is important so that constructive doesn’t choke on corrupted objects but instead helps us understand them.

For instance in the following example x prints like a date but it’s corrupted, a date should not be built on top of characters and this object cannot be built with as.Date() or other idiomatic date constructors.

x <- structure("12345", class = "Date")
x
#> [1] "2003-10-20"
x + 1
#> Error in unclass(e1) + unclass(e2): non-numeric argument to binary operator

We have defined :

is_corrupted_Date <- function(x) {
  !is.double(x)
}

And as a consequence the next method, .cstr_construct.default() will be called through NextMethod() and will handle the object using an atomic vector constructor:

construct(x)
#> "12345" |>
#>   structure(class = "Date")

Constructors

constructors are functions named as .cstr_construct.<class>.<constructor>.

For instance the default constructor for “Date” is :

constructive:::.cstr_construct.Date.as.Date
#> function(x, ...) {
#>   opts <- list(...)$opts$Date %||% opts_Date()
#>   origin <- opts$origin
#>   compatible_with_char <-
#>     all(rlang::is_integerish(x) & (is.finite(x) | (is.na(x) & !is.nan(x))))
#>   if (!compatible_with_char || all(is.na(x))) {
#>     return(.cstr_construct.Date.as.Date.numeric(x, ...))
#>   }
#>   code <- .cstr_apply(list(format(x)),  "as.Date", ..., new_line = FALSE)
#>   repair_attributes_Date(x, code, ...)
#> }
#> <bytecode: 0x5579bdbbc640>
#> <environment: namespace:constructive>

Their arguments are x and ..., and not more. Additional parameters fed to the opt_<class>() function can be fetched from list(...)$opts$<class>

The function .cstr_apply() is used to construct arguments recursively.

Sometimes a constructor cannot handle all cases and we need to fall back to another constructor, it happens below because Inf, NA, or decimal dates cannot be represented by a string wrapped by as.Date().

x <- structure(c(12345, 20000), class = "Date")
y <- structure(c(12345, Inf), class = "Date")
construct(x)
#> as.Date(c("2003-10-20", "2024-10-04"))
construct(y)
#> as.Date(c(12345, Inf), origin = "1970-01-01")

That last line of the function is essential, it does the attribute repair.

Attribute repair

Constructors should always end by a call to .cstr_repair_attributes() or a function that wraps it.

These are needed to adjust the attributes of an object after idiomatic constructors such as as.Date() have defined their data and canonical attributes.

x <- structure(c(12345, 20000), class = "Date", some_attr = 42)
# attributes are not visible due to "Date"'s printing method
x
#> [1] "2003-10-20" "2024-10-04"

construct(x)
#> as.Date(c("2003-10-20", "2024-10-04")) |>
#>   structure(some_attr = 42)

.cstr_repair_attributes() essentially sets attributes with exceptions :

It doesn’t set names by default, these should be handled by the constructors
It doesn’t set the class explicitly if it’s identical to the idiomatic class, i.e. the class returned by the constructor before the repair call, and provided through the idiomatic_class argument
It doesn’t set attributes that we choose to ignore because they are set by the constructor (e.g. row names for data frames or levels for factors)

constructive:::repair_attributes_Date
#> function(x, code, ...) {
#>   .cstr_repair_attributes(
#>     x, code, ...,
#>     idiomatic_class = "Date"
#>   )
#> }
#> <bytecode: 0x5579bf3d1d18>
#> <environment: namespace:constructive>

constructive:::repair_attributes_factor
#> function(x, code, ...) {
#>   .cstr_repair_attributes(
#>     x, code, ...,
#>     ignore = "levels",
#>     idiomatic_class = "factor"
#>   )
#> }
#> <bytecode: 0x5579bb2e4c78>
#> <environment: namespace:constructive>

constructive:::repair_attributes_tbl_df
#> function(x, code, ...) {
#>   .cstr_repair_attributes(
#>     x, code, ...,
#>     ignore = "row.names",
#>     idiomatic_class = c("tbl_df", "tbl", "data.frame")
#>   )
#> }
#> <bytecode: 0x5579bb1a6028>
#> <environment: namespace:constructive>

construct() and .cstr_construct()

.cstr_construct.<class>() methods