Merge pull request #462 from cynkra/f-456-improve-templates

Improve templates

R/templates.R

@@ -8,13 +8,16 @@
 #'
 #' @details
 #'
-#' We suggest the following workflow :
-#' * Call these functions, with `commented = TRUE` for more guidance
-#' * Save the scripts unchanged in your package
-#' * `devtools::document()`: this will register the S3 methods
+#' We suggest the following workflow (summarized in a message when you call the functions):
+#' * Call `usethis::use_package(\"constructive\"`, \"Suggests\")` one time at any
+#'   point, this will add a soft dependency on 'constructive' so it's only needed to
+#'   install it when you use it.
+#' * Call `.cstr_new_class()` or `.cstr_new_constructor()`, with `commented = TRUE` for more guidance.
+#' * Save the scripts unchanged in the "R" folder of your package.
+#' * `devtools::document()`: this will register the S3 methods.
 #' * Try `construct()` on your new object, it should print a call to your chosen
-#'   constructor
-#' * Tweak the code, in particular the definition of `args`
+#'   constructor.
+#' * Tweak the code, in particular the definition of `args`.
 #'
 #' The README of the example extension package
 #' ['constructive.example'](https://github.com/cynkra/constructive.example)
@@ -35,32 +38,44 @@
     constructor = "PKG::CONSTRUCTOR",
     commented = FALSE) {
   template <- if (commented) {
-    system.file("new_class_template_commented.R", package = "constructive")
+    system.file("new_class_template_commented_no_import.R", package = "constructive")
   } else {
-    system.file("new_class_template.R", package = "constructive")
+    system.file("new_class_template_no_import.R", package = "constructive")
   }
   code <- readLines(template)
   code <- gsub(".CLASS.", .cstr_construct(class, one_liner = TRUE), code, fixed = TRUE)
   code <- gsub(".CLASS1.", class[[1]], code, fixed = TRUE)
   code <- gsub(".PKG::CONSTRUCTOR.", constructor, code, fixed = TRUE)
   code <- gsub(".CONSTRUCTOR.", sub("^.*::(.*)$", "\\1", constructor), code, fixed = TRUE)
   rstudioapi::documentNew(code)
+  inform(c(
+    `*` = "Call `usethis::use_package(\"constructive\"`, \"Suggests\")`",
+    `*` = "Save the script in your package's R folder",
+    `*` = "Call `devtools::document()`",
+    `*` = "Tweak and iterate"
+  ))
   invisible(NULL)
 }
 
 #' @rdname templates
 #' @export
 .cstr_new_constructor <- function(class = c("CLASS", "PARENT_CLASS"), constructor = "PKG::CONSTRUCTOR", commented = FALSE) {
   template <- if (commented) {
-    system.file("new_constructor_template_commented.R", package = "constructive")
+    system.file("new_constructor_template_commented_no_import.R", package = "constructive")
   } else {
-    system.file("new_constructor_template.R", package = "constructive")
+    system.file("new_constructor_template_no_import.R", package = "constructive")
   }
   code <- readLines(template)
   code <- gsub(".CLASS.", .cstr_construct(class, one_liner = TRUE), code, fixed = TRUE)
   code <- gsub(".CLASS1.", class[[1]], code, fixed = TRUE)
   code <- gsub(".PKG::CONSTRUCTOR.", constructor, code, fixed = TRUE)
   code <- gsub(".CONSTRUCTOR.", sub("^.*::(.*)$", "\\1", constructor), code, fixed = TRUE)
   rstudioapi::documentNew(code)
+  inform(c(
+    `*` = "Call `usethis::use_package(\"constructive\"`, \"Suggests\")`",
+    `*` = "Save the script in your package's R folder",
+    `*` = "Call `devtools::document()`",
+    `*` = "Tweak and iterate"
+  ))
   invisible(NULL)
 }

inst/new_class_template_commented_no_import.R

@@ -0,0 +1,61 @@
+#' Constructive options for class '.CLASS1.'
+#'
+#' These options will be used on objects of class '.CLASS1.'.
+#'
+#' Depending on `constructor`, we construct the object as follows:
+#' * `".CONSTRUCTOR."` (default): We build the object using `.PKG::CONSTRUCTOR.()`.
+#' * `"next"` : Use the constructor for the next supported class.
+#'
+#' @param constructor String. Name of the function used to construct the object.
+#' @param ... Additional options used by user defined constructors through the `opts` object
+#' @return An object of class <constructive_options/constructive_options_.CLASS1.>
+#' @export
+opts_.CLASS1. <- function(constructor = c(".CONSTRUCTOR.", "next"), ...) {
+  # What's forwarded through `...`will be accessible through the `opts`
+  # object in the methods.
+  # You might add arguments to the function, to document those options,
+  # don't forget to forward them below as well
+  constructive::.cstr_options(".CLASS1.", constructor = constructor[[1]], ...)
+}
+
+#' @exportS3Method constructive::.cstr_construct
+.cstr_construct..CLASS1. <- function(x, ...) {
+  # There is probably no need for you to modify this function at all
+  opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+  if (is_corrupted_.CLASS1.(x) || opts$constructor == "next") return(NextMethod())
+  # This odd looking code dispatches to a method based on the name of
+  # the constructor rather than the class
+  UseMethod(".cstr_construct..CLASS1.", structure(NA, class = opts$constructor))
+}
+
+is_corrupted_.CLASS1. <- function(x) {
+  # check here if the object has the right structure to be constructed
+  # leaving FALSE is fine but you'll be vulnerable to corrupted objects
+  FALSE
+}
+
+#' @export
+.cstr_construct..CLASS1...CONSTRUCTOR. <- function(x, ...) {
+  # If needed, fetch additional options fed through opts_.CLASS1.()
+  # opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+
+  # Instead of the call below we need to fetch the args of the constructor in `x`.
+  args <- list()
+
+  # This creates a call .CONSTRUCTOR.(...) where ... is the constructed code
+  # of the arguments stored in `args`
+  # Sometimes we want to construct the code of the args separately, i.e. store
+  # code rather than objects in `args`, and use `recurse = FALSE` below
+  code <- constructive::.cstr_apply(args, fun = ".PKG::CONSTRUCTOR.", ...)
+
+  # .cstr_repair_attributes() makes sure that attributes that are not built
+  # by the idiomatic constructor are generated
+  constructive::.cstr_repair_attributes(
+    x, code, ...,
+    # attributes built by the constructor
+    # ignore =,
+
+    # not necessarily just a string, but the whole class(x) vector
+    idiomatic_class = .CLASS.
+  )
+}

inst/new_class_template_no_import.R

@@ -0,0 +1,37 @@
+#' Constructive options for class '.CLASS1.'
+#'
+#' These options will be used on objects of class '.CLASS1.'.
+#'
+#' Depending on `constructor`, we construct the object as follows:
+#' * `".CONSTRUCTOR."` (default): We build the object using `.PKG::CONSTRUCTOR.()`.
+#' * `"next"` : Use the constructor for the next supported class.
+#'
+#' @param constructor String. Name of the function used to construct the object.
+#' @param ... Additional options used by user defined constructors through the `opts` object
+#' @return An object of class <constructive_options/constructive_options_.CLASS1.>
+#' @export
+opts_.CLASS1. <- function(constructor = c(".CONSTRUCTOR.", "next"), ...) {
+  constructive::.cstr_options(".CLASS1.", constructor = constructor[[1]], ...)
+}
+
+#' @exportS3Method constructive::.cstr_construct
+.cstr_construct..CLASS1. <- function(x, ...) {
+  opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+  if (is_corrupted_.CLASS1.(x) || opts$constructor == "next") return(NextMethod())
+  UseMethod(".cstr_construct..CLASS1.", structure(NA, class = opts$constructor))
+}
+
+is_corrupted_.CLASS1. <- function(x) {
+  FALSE
+}
+
+#' @export
+.cstr_construct..CLASS1...CONSTRUCTOR. <- function(x, ...) {
+  # opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+  args <- list()
+  code <- constructive::.cstr_apply(args, fun = ".PKG::CONSTRUCTOR.", ...)
+  constructive::.cstr_repair_attributes(
+    x, code, ...,
+    idiomatic_class = .CLASS.
+  )
+}

inst/new_constructor_template_commented_no_import.R

@@ -0,0 +1,25 @@
+#' @exportS3Method constructive::.cstr_construct..CLASS1.
+.cstr_construct..CLASS1...CONSTRUCTOR. <- function(x, ...) {
+  # Uncomment if your constructor needs additional options from opts_.CLASS1.()
+  # opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+
+  # Instead of the call below we need to fetch the args of the constructor in `x`.
+  args <- list()
+
+  # This creates a call .CONSTRUCTOR.(...) where ... is the constructed code
+  # of the arguments stored in `args`
+  # Sometimes we want to construct the code of the args separately, i.e. store
+  # code rather than objects in `args`, and use `recurse = FALSE` below
+  code <- constructive::.cstr_apply(args, fun = ".PKG::CONSTRUCTOR.", ...)
+
+  # .cstr_repair_attributes() makes sure that attributes that are not built
+  # by the idiomatic constructor are generated
+  constructive::.cstr_repair_attributes(
+    x, code, ...,
+    # attributes built by the constructor
+    # ignore =,
+
+    # not necessarily just a string, but the whole class(x) vector
+    idiomatic_class = .CLASS.
+  )
+}

inst/new_constructor_template_no_import.R

@@ -0,0 +1,10 @@
+#' @exportS3Method constructive::.cstr_construct..CLASS1.
+.cstr_construct..CLASS1...CONSTRUCTOR. <- function(x, ...) {
+  # opts <- list(...)$opts$.CLASS1. %||% opts_.CLASS1.()
+  args <- list()
+  code <- constructive::.cstr_apply(args, fun = ".PKG::CONSTRUCTOR.", ...)
+  constructive::.cstr_repair_attributes(
+    x, code, ...,
+    idiomatic_class = .CLASS.
+  )
+}