Add --no-eval flag to parsable-roxygen

Author: owenjonesuob

inst/hooks/exported/parsable-roxygen.R

@@ -1,11 +1,27 @@
 #!/usr/bin/env Rscript
-files <- commandArgs(trailing = TRUE)
 
-out <- lapply(files, function(path) {
+"Check whether roxygen comments within files are valid
+Usage:
+  parsable-roxygen [--no-eval] <files>...
+
+Options:
+  --no-eval  Parse, but do not evaluate, file contents - this also suppresses evaluation of `@eval` tags
+
+" -> doc
+
+arguments <- precommit::precommit_docopt(doc)
+
+out <- lapply(arguments$files, function(path) {
   tryCatch(
     # Capture any messages from roxygen2:::warn_roxy()
     msg <- capture.output(
-      roxygen2::parse_file(path, env = NULL),
+      roxygen2::parse_file(
+        path,
+        env = if (isTRUE(arguments$no_eval))
+          NULL
+        else
+          roxygen2::env_file(path)
+      ),
       type = "message"
     ),
 

tests/testthat/in/parsable-roxygen-success.R

@@ -13,3 +13,6 @@
 some_function <- function(x) {
   x
 }
+
+# To check whether code was evaluated
+print("A random print statement")

tests/testthat/test-hook-parsable-roxygen.R

@@ -1,21 +1,45 @@
+# success - code evaluated
 run_test(
   "parsable-roxygen",
   suffix = "-success.R",
-  std_err = NULL
+  std_out = "A random print statement",
+  std_err = NULL,
+  read_only = TRUE
 )
 
-# failure - roxygen not parsed
+# success - code not evaluated
+run_test(
+  "parsable-roxygen",
+  suffix = "-success.R",
+  cmd_args = "--no-eval",
+  std_out = NULL,
+  std_err = NULL,
+  read_only = TRUE
+)
+
+# failure - roxygen problem
 run_test(
   "parsable-roxygen",
   suffix = "-fail.R",
   std_out = "Roxygen commentary",
-  std_err = "@description has mismatched braces or quotes"
+  std_err = "@description has mismatched braces or quotes",
+  read_only = TRUE
 )
 
-# failure - R not parsed
+# failure - R problem
 run_test(
   "parsable-roxygen",
   suffix = "-fail2.R",
   std_out = "File ",
-  std_err = "unexpected '}'"
+  std_err = "unexpected '}'",
+  read_only = TRUE
+)
+
+
+run_test(
+  "parsable-roxygen",
+  suffix = "-fail4.R",
+  std_out = "File ",
+  std_err = "unexpected '}'",
+  read_only = TRUE
 )

vignettes/available-hooks.Rmd

@@ -146,6 +146,22 @@ running `roxygen2::parse_file()` on them returns any messages.
 
 This hook does not modify files.
 
+**no eval**
+
+The `--no-eval` flag causes `roxygen2::parse_file()` to be run with`env = NULL`.
+This means each file will be parsed, but code will not be evaluated - neither
+any explicit code in the file, nor any `@eval` tags within roxygen comments.
+This can be useful if your files contain anything other than
+"simple object declarations" (e.g. [box modules](https://github.com/klmr/box/)
+containing `box::use()` calls).
+
+If `--no-eval` is set, inline code within roxygen comments (i.e. within
+backticks) _will_ still be evaluated, but in a new empty environment.
+
+      id: parsable-roxygen
+      args: [--no-eval]
+    
+
 ## `no-browser-statement`
 
 Guarantees you that you don't accidentally commit code with a