Expose three code loading strategies (#914)

Fixes #822

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: roxygen2
 Title: In-Line Documentation for R
-Version: 6.1.99.9000
+Version: 6.1.99.9001
 Authors@R: 
     c(person(given = "Hadley",
              family = "Wickham",
@@ -58,5 +58,5 @@ LinkingTo:
 VignetteBuilder: 
     knitr
 Encoding: UTF-8
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 6.1.99.9000
+Roxygen: list(markdown = TRUE, load = "installed")
+RoxygenNote: 6.1.99.9001

NAMESPACE

@@ -79,7 +79,10 @@ export(env_file)
 export(env_package)
 export(is_s3_generic)
 export(is_s3_method)
+export(load_installed)
 export(load_options)
+export(load_pkgload)
+export(load_source)
 export(namespace_roclet)
 export(object)
 export(object_format)

NEWS.md

@@ -1,5 +1,18 @@
 # roxygen2 (development version)
 
+* roxygen2 now provides three strategies for loading your code:
+
+    * `load_pkgload()` uses pkgload.
+    * `load_installed()` assumes you have installed the package.
+    * `load_source()` attaches required packages and `source()`s code in `R/`.
+
+    If the code loading strategy in roxygen2 6.1.0 and above has caused 
+    you grief, you can revert to the old strategy by using 
+    `Roxygen: list(load = "source")` (#822).
+
+    Compared to the previous release, the default pkgload strategy now will 
+    recompile `src/` if needed.
+
 * New `@order n` tag controls the order in which blocks are processed. You can
   use it to override the usual ordering which proceeds in from the top of 
   each file to the bottom. `@order 1` will be processed before `@order 2`, 

R/load.R

@@ -0,0 +1,99 @@
+#' Load package code
+#'
+#' @description
+#' roxygen2 is a dynamic documentation system, which means it works with the
+#' objects inside your package, not just the source code used to create them.
+#' These functions offer various ways of loading your package to suit various
+#' constraints:
+#'
+#' * `load_pkgload()` uses `pkgload::load_all()` to simulate package loading
+#'   as closely as we know how. It offers high fidelity handling of code that
+#'   uses S4, but requires that the package be compiled.
+#'
+#' * `load_source()` simulates package loading by attaching packages listed in
+#'   `Depends` and `Imports`, then sources all files in the `R/` directory.
+#'   This was the default strategy used in roxygen2 6.0.0 and earlier;
+#'   it's primary advantage is that it does not need compilation.
+#'
+#' * `load_installed()` uses the installed version of the package. Use this
+#'   strategy if you have installed a development version of the package
+#'   already. This is the highest fidelity strategy, but requires work
+#'   outside of roxygen2.
+#'
+#' You can change the default strategy for your function with roxygen2 `load`
+#' option. Override the default off `pkgload` to use the `source` or
+#' `installed` strategies:
+#'
+#' ```
+#' RoxygenNote: list(load = "source")
+#' ```
+#' @name load
+#' @param path Path to source package
+NULL
+
+#' @rdname load
+#' @export
+load_pkgload <- function(path) {
+  pkgload::load_all(path, helpers = FALSE, attach_testthat = FALSE)$env
+}
+
+#' @rdname load
+#' @export
+load_installed <- function(path) {
+  package <- desc::desc_get_field("Package", file = path)
+  asNamespace(package)
+}
+
+#' @rdname load
+#' @export
+load_source <- function(path) {
+  # Create environment
+  env <- new.env(parent = globalenv())
+  methods::setPackageName("roxygen_devtest", env)
+
+  # Attach dependencies
+  deps <- desc::desc_get_deps(path)
+  pkgs <- deps$package[
+    deps$type %in% c("Depends", "Imports") & deps$package != "R"
+  ]
+  lapply(pkgs, require, character.only = TRUE)
+
+  # Source files
+  lapply(package_files(path), sys_source, envir = env)
+
+  env
+}
+
+sys_source <- function(file, envir = baseenv()) {
+  exprs <- parse(text = read_lines(file))
+  for (expr in exprs) {
+    eval(expr, envir = envir)
+  }
+  invisible()
+}
+
+# Helpers -----------------------------------------------------------------
+
+find_load_strategy <- function(x, options) {
+  if (is.function(x)) {
+    return(x)
+  }
+
+  if (is.null(x)) {
+    x <- options$load
+    if (!is.character(x) || length(x) != 1) {
+      abort("roxygen2 `load` option must be a string")
+    }
+  } else {
+    if (!is.character(x) || length(x) != 1) {
+      abort("`load_code` must be a string or function")
+    }
+  }
+
+  switch(x,
+    pkgload = load_pkgload,
+    source = load_source,
+    installed = load_installed,
+    abort("Unknown value of `load` option")
+  )
+}

R/options.R

@@ -18,7 +18,8 @@ load_options <- function(base_path = ".") {
     wrap = FALSE,
     roclets = c("collate", "namespace", "rd"),
     markdown = markdown_global_default,
-    old_usage = FALSE
+    old_usage = FALSE,
+    load = "pkgload"
   )
 
   unknown_opts <- setdiff(names(opts), names(defaults))

R/parse.R

@@ -109,14 +109,9 @@ env_file <- function(file) {
 #' @export
 #' @rdname parse_package
 env_package <- function(path) {
-  pkgload::load_all(path,
-    compile = FALSE,
-    helpers = FALSE,
-    attach_testthat = FALSE
-  )$env
+  load_pkgload(path)
 }
 
-
 # helpers -----------------------------------------------------------------
 
 order_blocks <- function(blocks) {

R/roxygenize.R

@@ -8,25 +8,26 @@
 #'
 #' Note that roxygen2 is a dynamic documentation system: it works by
 #' inspecting loaded objects in the package. This means that you must
-#' be able to load the package in order to document it.
+#' be able to load the package in order to document it: see [load] for
+#' details.
 #'
 #' @param package.dir Location of package top level directory. Default is
 #'   working directory.
 #' @param roclets Character vector of roclet names to use with package.
-#'   This defaults to `NULL`, which will use the `roclets` fields in
-#'   the list provided in the `Roxygen` DESCRIPTION field. If none are
-#'   specified, defaults to `c("collate", "namespace", "rd")`.
+#'   The default, `NULL`, uses the roxygen `roclets` option,
+#'   which defaults to `c("collate", "namespace", "rd")`.
 #' @param load_code A function used to load all the R code in the package
-#'   directory. It is called with the path to the package, and it should return
-#'   an environment containing all the sourced code.
+#'   directory. The default, `NULL`, uses the strategy defined by
+#'   the `load` roxygen option, which defaults to [load_pkgload()].
+#'   See [load] for more details.
 #' @param clean If `TRUE`, roxygen will delete all files previously
 #'   created by roxygen before running each roclet.
 #' @return `NULL`
 #' @export
 #' @importFrom stats setNames
 roxygenize <- function(package.dir = ".",
                        roclets = NULL,
-                       load_code = env_package,
+                       load_code = NULL,
                        clean = FALSE) {
 
   base_path <- normalizePath(package.dir)
@@ -72,6 +73,7 @@ roxygenize <- function(package.dir = ".",
   )
 
   # Now load code
+  load_code <- find_load_strategy(load_code, options)
   env <- load_code(base_path)
   blocks <- lapply(blocks, block_set_env,
     env = env,

tests/testthat/test-load.R

@@ -0,0 +1,36 @@
+test_that("load_installed retrieves installed package", {
+  env <- load_installed(test_path("../.."))
+  expect_identical(env, asNamespace("roxygen2"))
+})
+
+test_that("can load simple package with load_pkgload()", {
+  env <- load_pkgload(test_path("testRbuildignore"))
+  expect_equal(env_get(env, "a"), 1)
+})
+
+test_that("can load simple package with load_source()", {
+  env <- load_source(test_path("testRbuildignore"))
+  expect_equal(env_get(env, "a"), 1)
+})
+
+# find_load_strategy ------------------------------------------------------
+
+test_that("function returned as is", {
+  expect_equal(find_load_strategy(load_installed), load_installed)
+})
+
+test_that("look up string", {
+  expect_equal(find_load_strategy("installed"), load_installed)
+  expect_equal(find_load_strategy("pkgload"), load_pkgload)
+  expect_equal(find_load_strategy("source"), load_source)
+  expect_error(find_load_strategy("blahblahb"), "Unknown value")
+})
+
+test_that("NULL uses option", {
+  expect_equal(find_load_strategy(NULL, list(load = "installed")), load_installed)
+})
+
+test_that("informative errors for bad inputs", {
+  expect_error(find_load_strategy(1), "string or function")
+  expect_error(find_load_strategy(NULL, list()), "string")
+})