rdocdump (version 0.1.0)

rdd_extract_code: Extract R Source Code from a Package

Description

This function extracts the R source code from a package. For installed packages, it retrieves the package namespace and deparses all functions found in the package. For package source directories or archives (non-installed packages), it reads all .R files from the R directory and, optionally, from the tests directory. Optionally, it can include roxygen2 documentation from these files.

Usage

rdd_extract_code(
  pkg,
  file = NULL,
  include_tests = FALSE,
  include_roxygen = FALSE,
  force_fetch = FALSE,
  cache_path = getOption("rdocdump.cache_path"),
  keep_files = "none",
  repos = getOption("rdocdump.repos", getOption("repos"))
)

Value

A single string containing the combined R source code (and, optionally, roxygen2 documentation) from the package.

Arguments

pkg

A character string specifying the package. This can be:

• an installed package name,

• a full path to a package source directory,

• a full path to a package archive file (tar.gz), or

• a package name not installed (which will then be downloaded from CRAN).

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.

include_tests

logical. If TRUE, for non-installed packages, the function will also include R source code from the tests directory. Defaults to FALSE.

include_roxygen

logical. If TRUE, roxygen2 documentation lines (lines starting with "#'") from R files will be included in the output. Defaults to FALSE.

force_fetch

logical. If TRUE, the package source will be fetched from CRAN even if the package is installed locally. Default is FALSE.

cache_path

A character string specifying the directory to use as a cache. Defaults to the value of getOption("rdocdump.cache_path").

keep_files

A character value controlling whether temporary files should be kept. Possible values are:

• "none": Delete both the tar.gz archive and the extracted files (default).

• "tgz": Keep only the tar.gz archive.

• "extracted": Keep only the extracted files.

• "both": Keep both the tar.gz archive and the extracted files.

repos

A character vector of repository URLs. By default, it uses the value of getOption("rdocdump.repos") which sets the repository URLs to the default R repositories and is itself set to c("CRAN" = "https://cloud.r-project.org") on package load to prevent accidental downloads of pre-built packages from Posit Package Manager and R Universe.

Examples

# Extract only R source code (excluding roxygen2 documentation) from an installed package.
code <- rdd_extract_code("splines")
cat(substr(code, 1, 1000))

# Extract R source code including roxygen2 documentation from a package source directory.
# \donttest{
# set cache directory for `rdocdump`
rdd_set_cache_path(paste0(tempdir(), "/rdocdump_cache"))

local({
 code_with_roxygen <- rdd_extract_code(
  "ini",
  include_roxygen = TRUE,
  force_fetch = TRUE,
  repos = c("CRAN" = "https://cran.r-project.org")
)
 cat(substr(code_with_roxygen, 1, 1000))
})

# Extract R source code from a package source directory,
# including test files but excluding roxygen2 docs.
local({
 code_with_tests <- rdd_extract_code(
  "ini",
  include_roxygen = TRUE,
  include_tests = TRUE,
  force_fetch = TRUE,
  repos = c("CRAN" = "https://cran.r-project.org")
)
 cat(substr(code_with_tests, 1, 1000))
})
# clean cache directory
unlink(getOption("rdocdump.cache_path"), recursive = TRUE, force = TRUE)
# }