when_api_same: Compare APIs across package versions

In hughjonesd/pastapi: Explore the Historical API of R Packages

Description

when_api_same reports package versions where the API of a function was the same as now (or the same as current_fun).

when_fun_exists reports package versions where a function exists.

Usage

when_api_same(fun, package, current_fun = NULL, search = c("binary",
  "forward", "backward", "all", "parallel"), report = c("full", "brief"),
  quiet = TRUE, progress = interactive() && search != "parallel",
  min_version = NULL, max_version = NULL, ...)

when_fun_exists(fun, package, search = c("binary", "forward", "backward",
  "all", "parallel"), report = c("full", "brief"), quiet = TRUE,
  progress = interactive() && search != "parallel", min_version = NULL,
  max_version = NULL, ...)

Arguments

fun	Function name as a character string. fun can be an S3 method; S4 methods aren't yet supported.
package	Package. Alternatively, specify the function name as e.g. "package::function".
current_fun	Current function for comparison. By default, fun in the current version of the package (which is assumed to be already installed). This must be an actual function, not the name of one: use fun_at().
search	"binary", "forward", "backward", "all" or "parallel". See Search strategies.
report	"brief" or "full". See Value.
quiet	Logical. Try to minimize output from package installation. (Some output comes from R CMD INSTALL and may be unavoidable.)
progress	Print a progress bar.
min_version	Lowest version to check.
max_version	Highest version to check.
...	Arguments passed to versions::install.versions() or remotes::install_version(), and thence to install.packages(). Ncpus may be useful.

Details

"Same API" means having the same function arguments, as reported by formals().

Value

If report is "brief", the earliest "known good" version. Otherwise, a data frame of versions with a full results column.

Speed

This function may download and install multiple versions from MRAN, so it is likely to be slow when first used (and even afterwards if library loading is slow). Using search = "parallel" may help, but not if the network is the bottleneck: see https://hughjonesd.github.io/apicheck/performance2.html for details.

Search strategies

• "forward" ("backward") searches incrementally from the earliest (latest) version.

• "binary" does a binary search from the midpoint.

These strategies assume that API changes happen just once - i.e. once a function exists or API is the same as now, it will stay so in future versions. This allows them to stop before searching every version.

• "all" searches every version.

• "parallel" searches every version in parallel using parallel::parLapply().

Parallelism

For parallel search, you can set up your own parallel cluster by using parallel::setDefaultCluster(); otherwise one will be created, using getOption("cl.cores") cores if that is set. If you set up your own cluster, it will not be stopped automatically (see parallel::stopCluster()).

Examples

## Not run: 
when_api_same("read.dta", "foreign")

## End(Not run)
## Not run: 
when_fun_exists('read.dta', 'foreign')

## End(Not run)

hughjonesd/pastapi documentation built on Sept. 9, 2019, 12:56 p.m.