Merge pull request #22 from e-kotov/issue-21-add-version-parameter

Issue 21 add version parameter

Author: e-kotov

.Rbuildignore

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

.gemini/settings.json

@@ -0,0 +1,7 @@
+{
+  "maxSessionTurns": 50,
+  "telemetry": {
+    "enabled": false,
+    "target": "gcp"
+  }
+}

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{
@@ -70,6 +71,7 @@ rdd_to_txt <- function(
   file = NULL,
   content = "all",
   force_fetch = FALSE,
+  version = NULL,
   keep_files = "none",
   cache_path = getOption("rdocdump.cache_path"),
   repos = getOption("rdocdump.repos", getOption("repos"))
@@ -98,7 +100,13 @@ rdd_to_txt <- function(
   }
 
   # Resolve package source path using the existing helper.
-  pkg_info <- resolve_pkg_path(pkg, cache_path, force_fetch = force_fetch)
+  pkg_info <- resolve_pkg_path(
+    pkg,
+    cache_path,
+    force_fetch = force_fetch || !is.null(version),
+    version = version,
+    repos = repos
+  )
   pkg_path <- pkg_info$pkg_path
 
   # Initialize component texts.
@@ -122,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

@@ -14,6 +14,7 @@ resolve_pkg_path <- function(
   pkg,
   cache_path = NULL,
   force_fetch = FALSE,
+  version = NULL,
   repos = getOption("rdocdump.repos", getOption("repos"))
 ) {
   if (!is.character(pkg) || length(pkg) != 1L) {
@@ -111,7 +112,7 @@ resolve_pkg_path <- function(
     } else {
       NULL
     }
-    if (!is.null(pkg_found)) {
+    if (!is.null(pkg_found) && is.null(version)) {
       # Installed package found.
       return(list(
         pkg_path = pkg_found,
@@ -134,12 +135,63 @@ resolve_pkg_path <- function(
           "Using a repository URL from posit.co or r-universe.dev may result in pre-built binaries being downloaded instead of the package source."
         )
       }
-      dp <- utils::download.packages(
-        pkg,
-        destdir = dest_dir,
-        type = "source",
-        repos = repos
-      )
+
+      if (!is.null(version)) {
+        # Construct URL for a specific version.
+        repo_url <- repos[1] # Use the first repo.
+        tar_filename <- paste0(pkg, "_", version, ".tar.gz")
+        # Try archive first.
+        url <- file.path(repo_url, "src/contrib/Archive", pkg, tar_filename)
+        # Try downloading.
+        res <- try(
+          suppressWarnings(
+            utils::download.file(
+              url,
+              destfile = file.path(dest_dir, tar_filename),
+              mode = "wb",
+              quiet = TRUE
+            )
+          ),
+          silent = TRUE
+        )
+        # If archive fails, try main contrib.
+        if (inherits(res, "try-error") || res != 0) {
+          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
+              )
+            ),
+            silent = TRUE
+          )
+        }
+        if (inherits(res, "try-error") || res != 0) {
+          stop(paste(
+            "Could not download package",
+            pkg,
+            "version",
+            version,
+            "from",
+            url
+          ))
+        }
+        dp <- matrix(
+          c(tar_filename, file.path(dest_dir, tar_filename)),
+          nrow = 1
+        )
+      } else {
+        dp <- utils::download.packages(
+          pkg,
+          destdir = dest_dir,
+          type = "source",
+          repos = repos
+        )
+      }
+
       if (nrow(dp) < 1L) {
         stop("Package not found on CRAN.")
       }

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
   )
 }
@@ -262,3 +269,186 @@ test_that("rdd_to_txt keeps both tar.gz archive and extracted files when keep_fi
   # Clean up the cache directory.
   unlink(cache_dir, recursive = TRUE)
 })
+
+test_that("rdd_to_txt fetches a specific package version when 'version' is provided", {
+  skip_on_cran()
+  skip_if_offline()
+
+  cache_dir <- tempfile("cache_version_test")
+  dir.create(cache_dir)
+
+  # Use a package with a known version history, e.g., "jsonlite"
+  # and a version that is not the latest.
+  pkg_name <- "ini"
+  pkg_version <- "0.1"
+
+  old_repos <- getOption("repos")
+  options(repos = c(CRAN = "https://cloud.r-project.org"))
+
+  # Fetch the package with the specified version.
+  out <- suppressWarnings(rdd_to_txt(
+    pkg_name,
+    version = pkg_version,
+    force_fetch = TRUE,
+    keep_files = "extracted",
+    cache_path = cache_dir
+  ))
+
+  options(repos = old_repos)
+
+  # Check that the extracted directory for the correct version exists.
+  expected_dir <- file.path(cache_dir, pkg_name, pkg_version)
+  expect_true(dir.exists(expected_dir))
+
+  # Verify the version from the DESCRIPTION file.
+  desc_file <- file.path(expected_dir, "DESCRIPTION")
+  expect_true(file.exists(desc_file))
+
+  desc_content <- readLines(desc_file)
+  version_line <- grep("Version:", desc_content, value = TRUE)
+  expect_true(grepl(pkg_version, version_line))
+
+  # 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))
+})