fix tests and docs

Author: e-kotov

.Rbuildignore

@@ -14,3 +14,4 @@
 ^man/figures/logo\.png$
 ^man/figures/card\.png$
 ^CRAN-SUBMISSION$
+^.gemini$

R/to_txt.R

@@ -11,7 +11,8 @@
 #'   \item a package name not installed (which will then be downloaded from CRAN).
 #' }
 #' @param file Optional. Save path for the output text file. If set, the function will return the path to the file instead of the combined text. Defaults to `NULL`.
-#' @param force_fetch `logical`. If `TRUE`, the package source will be fetched from CRAN as a tar.gz archive even if the package is already installed locally. Default is `FALSE`.
+#' @param force_fetch `logical`. If `TRUE`, the package source will be fetched from CRAN as a tar.gz archive even if the package is already installed locally. Default is `FALSE`, but when `version` is specified, it will be set to `TRUE`.
+#' @param version Optional. A `character` string specifying the package version to fetch from CRAN. If not provided, the latest version will be used.
 #' @param content A character vector specifying which components to include in the output.
 #' Possible values are:
 #' \itemize{
@@ -102,7 +103,7 @@ rdd_to_txt <- function(
   pkg_info <- resolve_pkg_path(
     pkg,
     cache_path,
-    force_fetch = force_fetch,
+    force_fetch = force_fetch || !is.null(version),
     version = version,
     repos = repos
   )
@@ -129,9 +130,9 @@ rdd_to_txt <- function(
       file = NULL,
       include_tests = FALSE,
       include_roxygen = FALSE,
-      force_fetch = force_fetch,
+      force_fetch = force_fetch || !is.null(version),
       cache_path = cache_path,
-      keep_files = "both", # make sure the files are not deleted prematurely, as rdd_to_txt will take care of that later
+      keep_files = "both" # make sure the files are not deleted prematurely, as rdd_to_txt will take care of that later
     )
   }
 

R/util_resolve_pkg_path.R

@@ -24,7 +24,7 @@ resolve_pkg_path <- function(
   # Helper function to parse tarball filename into package name and version.
   parse_tarball_name <- function(tar_path) {
     base_name <- basename(tar_path) # e.g., "rJavaEnv_0.2.2.tar.gz"
-    folder_name <- sub("\.tar\.gz$", "", base_name)
+    folder_name <- sub("\\.tar\\.gz$", "", base_name)
     parts <- strsplit(folder_name, "_")[[1]]
     if (length(parts) < 2) {
       stop(
@@ -51,7 +51,7 @@ resolve_pkg_path <- function(
       # Check if directory is a source package by looking for Rd files in "man/"
       man_dir <- file.path(pkg, "man")
       rd_files <- if (dir.exists(man_dir)) {
-        list.files(man_dir, pattern = "\.Rd$", full.names = TRUE)
+        list.files(man_dir, pattern = "\\.Rd$", full.names = TRUE)
       } else {
         character(0)
       }
@@ -75,7 +75,7 @@ resolve_pkg_path <- function(
       }
     } else {
       # pkg is a file; assume it is a tar.gz archive.
-      if (!grepl("\.tar\.gz$", pkg)) {
+      if (!grepl("\\.tar\\.gz$", pkg)) {
         stop(
           "The specified file is not a recognized package archive (expected extension .tar.gz)."
         )
@@ -129,7 +129,7 @@ resolve_pkg_path <- function(
       }
       # Warn if repos contains known problematic URLs.
       if (
-        any(grepl("posit\.co|r-universe\.dev", repos, ignore.case = TRUE))
+        any(grepl("posit\\.co|r-universe\\.dev", repos, ignore.case = TRUE))
       ) {
         warning(
           "Using a repository URL from posit.co or r-universe.dev may result in pre-built binaries being downloaded instead of the package source."
@@ -145,7 +145,12 @@ resolve_pkg_path <- function(
         # Try downloading.
         res <- try(
           suppressWarnings(
-            utils::download.file(url, destfile = file.path(dest_dir, tar_filename), mode = "wb", quiet = TRUE)
+            utils::download.file(
+              url,
+              destfile = file.path(dest_dir, tar_filename),
+              mode = "wb",
+              quiet = TRUE
+            )
           ),
           silent = TRUE
         )
@@ -154,15 +159,23 @@ resolve_pkg_path <- function(
           url <- file.path(repo_url, "src/contrib", tar_filename)
           res <- try(
             suppressWarnings(
-              utils::download.file(url, destfile = file.path(dest_dir, tar_filename), mode = "wb", quiet = TRUE)
+              utils::download.file(
+                url,
+                destfile = file.path(dest_dir, tar_filename),
+                mode = "wb",
+                quiet = TRUE
+              )
             ),
             silent = TRUE
           )
         }
         if (inherits(res, "try-error") || res != 0) {
           stop(paste("Could not download package", pkg, "version", version))
         }
-        dp <- matrix(c(tar_filename, file.path(dest_dir, tar_filename)), nrow = 1)
+        dp <- matrix(
+          c(tar_filename, file.path(dest_dir, tar_filename)),
+          nrow = 1
+        )
       } else {
         dp <- utils::download.packages(
           pkg,

man/rdd_to_txt.Rd

@@ -1,10 +1,17 @@
 # Tests for the rdd_to_txt function in the rdocdump package
-fake_resolve_pkg_path <- function(pkg, cache_path, force_fetch, repos) {
+fake_resolve_pkg_path <- function(
+  pkg,
+  cache_path,
+  force_fetch,
+  version,
+  repos
+) {
   list(
     pkg_path = pkg,
     is_installed = FALSE,
     pkg_name = "testpkg",
     tar_path = NULL,
+    version = NULL,
     extracted_path = NULL
   )
 }
@@ -272,8 +279,8 @@ test_that("rdd_to_txt fetches a specific package version when 'version' is provi
 
   # Use a package with a known version history, e.g., "jsonlite"
   # and a version that is not the latest.
-  pkg_name <- "jsonlite"
-  pkg_version <- "1.7"
+  pkg_name <- "ini"
+  pkg_version <- "0.1"
 
   old_repos <- getOption("repos")
   options(repos = c(CRAN = "https://cloud.r-project.org"))
@@ -304,3 +311,144 @@ test_that("rdd_to_txt fetches a specific package version when 'version' is provi
   # Clean up the cache directory.
   unlink(cache_dir, recursive = TRUE)
 })
+
+test_that("rdd_to_txt sets force_fetch=TRUE internally whenever 'version' is provided", {
+  calls <- new.env(parent = emptyenv())
+  calls$resolve_force_fetch <- NULL
+  calls$rdd_force_fetch <- NULL
+
+  fake_resolve_pkg_path_spy <- function(
+    pkg,
+    cache_path,
+    force_fetch,
+    version,
+    repos
+  ) {
+    calls$resolve_force_fetch <- force_fetch
+    list(
+      pkg_path = tempfile("pkg_"),
+      is_installed = FALSE,
+      pkg_name = "ini",
+      tar_path = NULL,
+      version = version,
+      extracted_path = NULL
+    )
+  }
+
+  fake_rdd_extract_code_spy <- function(
+    pkg,
+    file,
+    include_tests,
+    include_roxygen,
+    force_fetch,
+    cache_path,
+    keep_files
+  ) {
+    calls$rdd_force_fetch <- force_fetch
+    "CODE"
+  }
+
+  # No-op helpers to avoid touching filesystem or requiring real pkg content
+  fake_cleanup_files <- function(pkg_info, keep_files) invisible(NULL)
+  fake_combine_rd <- function(...) "" # not used when content = "code"
+  fake_combine_vignettes <- function(...) "" # not used when content = "code"
+
+  local_mocked_bindings(
+    resolve_pkg_path = fake_resolve_pkg_path_spy,
+    rdd_extract_code = fake_rdd_extract_code_spy,
+    cleanup_files = fake_cleanup_files,
+    combine_rd = fake_combine_rd,
+    combine_vignettes = fake_combine_vignettes,
+    .package = "rdocdump"
+  )
+
+  out <- rdd_to_txt(
+    "ini",
+    version = "0.1", # << the trigger
+    force_fetch = FALSE, # user-specified FALSE should be overridden
+    content = "code",
+    keep_files = "none"
+  )
+
+  expect_identical(out, "CODE")
+  expect_true(isTRUE(calls$resolve_force_fetch))
+  expect_true(isTRUE(calls$rdd_force_fetch))
+})
+
+test_that("rdd_to_txt passes through force_fetch unchanged when 'version' is NULL", {
+  calls <- new.env(parent = emptyenv())
+  calls$resolve_force_fetch <- NULL
+  calls$rdd_force_fetch <- NULL
+
+  fake_resolve_pkg_path_spy <- function(
+    pkg,
+    cache_path,
+    force_fetch,
+    version,
+    repos
+  ) {
+    calls$resolve_force_fetch <- force_fetch
+    list(
+      pkg_path = tempfile("pkg_"),
+      is_installed = FALSE,
+      pkg_name = "ini",
+      tar_path = NULL,
+      version = version,
+      extracted_path = NULL
+    )
+  }
+
+  fake_rdd_extract_code_spy <- function(
+    pkg,
+    file,
+    include_tests,
+    include_roxygen,
+    force_fetch,
+    cache_path,
+    keep_files
+  ) {
+    calls$rdd_force_fetch <- force_fetch
+    "CODE"
+  }
+
+  fake_cleanup_files <- function(pkg_info, keep_files) invisible(NULL)
+  fake_combine_rd <- function(...) ""
+  fake_combine_vignettes <- function(...) ""
+
+  local_mocked_bindings(
+    resolve_pkg_path = fake_resolve_pkg_path_spy,
+    rdd_extract_code = fake_rdd_extract_code_spy,
+    cleanup_files = fake_cleanup_files,
+    combine_rd = fake_combine_rd,
+    combine_vignettes = fake_combine_vignettes,
+    .package = "rdocdump"
+  )
+
+  # Case A: user passes force_fetch = FALSE, version = NULL -> internal should be FALSE
+  out_A <- rdd_to_txt(
+    "ini",
+    version = NULL,
+    force_fetch = FALSE,
+    content = "code",
+    keep_files = "none"
+  )
+  expect_identical(out_A, "CODE")
+  expect_false(isTRUE(calls$resolve_force_fetch))
+  expect_false(isTRUE(calls$rdd_force_fetch))
+
+  # Reset captured values
+  calls$resolve_force_fetch <- NULL
+  calls$rdd_force_fetch <- NULL
+
+  # Case B: user passes force_fetch = TRUE, version = NULL -> internal should be TRUE
+  out_B <- rdd_to_txt(
+    "ini",
+    version = NULL,
+    force_fetch = TRUE,
+    content = "code",
+    keep_files = "none"
+  )
+  expect_identical(out_B, "CODE")
+  expect_true(isTRUE(calls$resolve_force_fetch))
+  expect_true(isTRUE(calls$rdd_force_fetch))
+})