when_api_same: Compare APIs across package versions

Description Usage Arguments Details Value Speed Search strategies Parallelism Examples

View source: R/search.R

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

1
2
3
4
5
6
7
8
9
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

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.

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

1
2
3
4
5
6
7
8
## Not run: 
when_api_same("read.dta", "foreign")

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

## End(Not run)

hughjonesd/apicheck documentation built on July 17, 2018, 7:21 a.m.