Package 'apicheck' reference manual

Title:	Explore the Historical API of R Packages
Description:	Check when functions were introduced and/or APIs changed in packages, using the 'MRAN' service.
Authors:	David Hugh-Jones [aut, cre]
Maintainer:	David Hugh-Jones <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0.9000
Built:	2024-08-09 02:46:38 UTC
Source:	https://github.com/hughjonesd/apicheck

apicheck: check function APIs in different versions of packages

Description

This is a small package to check when functions were introduced and/or APIs changed in packages. It automatically installs different versions of a package in a separate directory and loads them without attaching them.

Details

Packages are cached within a session. To cache packages across sessions, use set_lib_dir() to point to a persistent directory.

By default, apicheck`` uses theremotespackage to install source versions from CRAN. Alternatively, it can use theversions“ package to install different versions of a package from https://mran.microsoft.com/. To do this set options(apicheck.use_mran = TRUE).

Be aware that functions can take a long time to return, as different versions of a package are installed and/or loaded.

Also, be aware that namespace loading and unloading can be unreliable. If this happens to you, try restarting your session.

Warning

Do not try to use apicheck on itself. This will lead to fiery elephants in the sky.

Test if a function's API is unchanged

Description

api_same_at reports whether a function had the same API at a previous version or date.

Usage

api_same_at(fun, version = version_at_date(package, date), package,
  date = NULL, quiet = TRUE, current_fun = NULL, ...)
api_same_at(fun, version = version_at_date(package, date), package,
  date = NULL, quiet = TRUE, current_fun = NULL, ...)

Arguments

`fun`	Function name as a character string. `fun` can be an S3 method; S4 methods aren't yet supported.
`version`	Version as a character string. If omitted, use the version available at `date`.
`package`	Package. Alternatively, specify the function name as e.g. `"package::function"`.
`date`	Date, as a character string that can be read by `as.Date()` e.g. "2016-01-01".
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`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()`.
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Details

If fun is not exported at version, api_same_at returns FALSE with a warning.

Value

TRUE or FALSE.

Examples

## Not run: 
api_same_at("clipr::write_clip", version = "0.1.1")
# equivalently
api_same_at("write_clip", "clipr", "0.1.1")

## End(Not run)
## Not run: 
api_same_at("clipr::write_clip", version = "0.1.1")
# equivalently
api_same_at("write_clip", "clipr", "0.1.1")

## End(Not run)

Report available versions

Description

This returns packages ordered by date, using either MRAN or metacran (or rcheology for R core packages). Results are cached so as to relieve pressure on the server. If options("apicheck.use_mran") is TRUE (and package is non-core), then only versions available on MRAN (i.e. after 2014-09-17) will be returned; otherwise older versions will be returned too.

Usage

available_versions(package)
available_versions(package)

Arguments

package

Package name.

Value

A data frame with columns "version" and "date".

Speed

In my limited experience, metacran is much faster. YMMV.

Examples

## Not run: 
available_versions("clipr")

## End(Not run)

## Not run: 
available_versions("clipr")

## End(Not run)

Install and/or load a version of a package

Description

cached_install checks the package cache, installs the specified version if it is not already installed, and loads the versioned package namespace.

Usage

cached_install(package, version, return = c("namespace", "path"),
  cache = TRUE, quiet = TRUE, partial = TRUE, ...)
cached_install(package, version, return = c("namespace", "path"),
  cache = TRUE, quiet = TRUE, partial = TRUE, ...)

Arguments

`package`	Package name.
`version`	Version as a character string.
`return`	Return the file "path" to the installed package, or the "namespace" object?
`cache`	If `FALSE`, always reinstall the package.
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`partial`	Default `TRUE`. Passed to `loadNamespace()`.
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Details

If the package is already loaded, cached_install will first attempt to unload it with a warning. This may not always work!

Note that the namespace is not attached. Partial loading is faster and safer when you are (un)loading multiple versions, but does not export functions etc.

Value

The namespace object or directory where the package is installed.

Examples

## Not run: 
cached_install("clipr", "0.4.0")

## End(Not run)
## Not run: 
cached_install("clipr", "0.4.0")

## End(Not run)

Load a package namespace and pass it to a function

Description

The package is downloaded and installed if necessary, and its namespace is loaded. Then test(ns) is called with the namespace object, and its value is returned. On exit, the namespace is unloaded.

Usage

call_with_namespace(package, version, test, quiet = TRUE, ...)
call_with_namespace(package, version, test, quiet = TRUE, ...)

Arguments

`package`	Package name.
`version`	Version as a character string.
`test`	A one-argument function.
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Value

The value returned by test.

Examples

## Not run: 
can_it_expand_urls <- function (namespace) "expand_urls" %in% names(namespace)
call_with_namespace("longurl", "0.3.0", test = can_it_expand_urls)

## End(Not run)
## Not run: 
can_it_expand_urls <- function (namespace) "expand_urls" %in% names(namespace)
call_with_namespace("longurl", "0.3.0", test = can_it_expand_urls)

## End(Not run)

Compare versions of a package

Description

compare_versions reports how functions and APIs changed between versions of a package.

Usage

compare_versions(package, version = previous_version(package, version2),
  version2, methods = FALSE, quiet = TRUE, ...)

## S3 method for class 'versions_report'
print(x, ...)

## S3 method for class 'versions_report'
summary(object, ...)
compare_versions(package, version = previous_version(package, version2),
  version2, methods = FALSE, quiet = TRUE, ...)

## S3 method for class 'versions_report'
print(x, ...)

## S3 method for class 'versions_report'
summary(object, ...)

Arguments

`package`	Package name.
`version`	First version to compare. By default, the previous version to that currently installed.
`version2`	Second version to compare. By default, the current installed version.
`methods`	Logical: include non-exported S3 methods?
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.
`x`, `object`	An object of class `versions_report`.

Value

compare_versions returns a data frame of class versions_report, reporting functions that have been "Added", "Removed" or had "API changed", and details of function arguments. Extra information is in the "package" and "versions" attributes.

summary returns a string representation of changed function arguments.

Examples

## Not run: 
compare_versions("clipr", "0.2.1", "0.3.0")

## End(Not run)
## Not run: 
compare_versions("clipr", "0.2.1", "0.3.0")

## End(Not run)

Retrieve a function from a package version

Description

Retrieve a function from a package version

Usage

fun_at(fun, version = version_at_date(package, date), package, date = NULL,
  quiet = TRUE, allow_core = FALSE, ...)
fun_at(fun, version = version_at_date(package, date), package, date = NULL,
  quiet = TRUE, allow_core = FALSE, ...)

Arguments

`fun`	Function name as a character string. `fun` can be an S3 method; S4 methods aren't yet supported.
`version`	Version as a character string. If omitted, use the version available at `date`.
`package`	Package. Alternatively, specify the function name as e.g. `"package::function"`.
`date`	Date, as a character string that can be read by `as.Date()` e.g. "2016-01-01".
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`allow_core`	See below.
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Details

By default, you cannot get functions from previous versions of R core packages, which are not available on CRAN/MRAN. If allow_core is TRUE, then a function will be returned from the rcheology dataset, with a null body but the same formal arguments as the historical function.

Value

The function itself.

Examples

## Not run: 
fun_at("write_clip", "clipr", "0.1.1")

## End(Not run)
## Not run: 
fun_at("write_clip", "clipr", "0.1.1")

## End(Not run)

Test if a function exists at a given package version

Description

fun_exists_at reports whether a function exists (i.e. is exported) from a package at a specific previous version or date.

Usage

fun_exists_at(fun, version = version_at_date(package, date), package,
  date = NULL, quiet = TRUE, ...)
fun_exists_at(fun, version = version_at_date(package, date), package,
  date = NULL, quiet = TRUE, ...)

Arguments

`fun`	Function name as a character string. `fun` can be an S3 method; S4 methods aren't yet supported.
`version`	Version as a character string. If omitted, use the version available at `date`.
`package`	Package. Alternatively, specify the function name as e.g. `"package::function"`.
`date`	Date, as a character string that can be read by `as.Date()` e.g. "2016-01-01".
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Value

TRUE or FALSE.

Examples

## Not run: 
fun_exists_at("clipr::dr_clipr", version = "0.3.1")
# or
fun_exists_at("dr_clipr", "clipr", "0.3.1")

## End(Not run)
## Not run: 
fun_exists_at("clipr::dr_clipr", version = "0.3.1")
# or
fun_exists_at("dr_clipr", "clipr", "0.3.1")

## End(Not run)

Get help for a function at a package version

Description

Get help for a function at a package version

Usage

help_at(fun, version = version_at_date(package, date), package, date = NULL,
  quiet = TRUE, ...)
help_at(fun, version = version_at_date(package, date), package, date = NULL,
  quiet = TRUE, ...)

Arguments

`fun`	Function name as a character string. `fun` can be an S3 method; S4 methods aren't yet supported.
`version`	Version as a character string. If omitted, use the version available at `date`.
`package`	Package. Alternatively, specify the function name as e.g. `"package::function"`.
`date`	Date, as a character string that can be read by `as.Date()` e.g. "2016-01-01".
`quiet`	Logical. Try to minimize output from package installation. (Some output comes from `R CMD INSTALL` and may be unavoidable.)
`...`	Arguments passed to `versions::install.versions()` or `remotes::install_version()`, and thence to `install.packages()`. `Ncpus` may be useful.

Value

The help object (text format only).

Examples

## Not run: 
help_at("clipr::write_clip", "0.1.1")
help_at("clipr::write_clip", "0.2.0")

## End(Not run)
## Not run: 
help_at("clipr::write_clip", "0.1.1")
help_at("clipr::write_clip", "0.2.0")

## End(Not run)

Report on backwards compatibility of a source package

Description

package_report lists all external function calls from a source package using pkgapi::map_package(). It then checks backward-compatibility of each call with previous versions.

Usage

package_report(path = ".", include, exclude = core_packages(),
  cutoff_date = Sys.Date() - 2 * 365, max_n_versions = NULL,
  parallel = FALSE, progress = !parallel, ...)
package_report(path = ".", include, exclude = core_packages(),
  cutoff_date = Sys.Date() - 2 * 365, max_n_versions = NULL,
  parallel = FALSE, progress = !parallel, ...)

Arguments

`path`	Path to the root of an R source package.
`include`	Packages to include. By default, all are included except core packages and the package at `path` itself.
`exclude`	Packages to exclude from checking. Overrides `include`.
`cutoff_date`	Don't check versions before this date (default: 2 years ago). Set to `NULL` for no cutoff.
`max_n_versions`	Check at most this number of previous versions. Set to `NULL` for no limit.
`parallel`	Run in parallel.
`progress`	Show a progress bar.
`...`	Arguments passed to `call_with_namespace()`.

Value

A data frame with three rows:

package for the external package
version for the latest version which caused problems or NA if there were no problems
funs a list-column of function names where the API changed

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: 
package_report(".")
# to include base packages also:
package_report(".", exclude = character(0))

## End(Not run)
## Not run: 
package_report(".")
# to include base packages also:
package_report(".", exclude = character(0))

## End(Not run)

Location of the package cache

Description

set_lib_dir() specifies where packages will be downloaded to. get_lib_dir() returns this directory. clear_lib_dir() deletes all downloaded packages.

Usage

set_lib_dir(lib_dir, create = FALSE)

get_lib_dir()

clear_lib_dir()
set_lib_dir(lib_dir, create = FALSE)

get_lib_dir()

clear_lib_dir()

Arguments

`lib_dir`	Path to a directory, or `NULL` to unset.
`create`	Logical. Try to create the directory if it doesn't exist.

Details

If lib_dir is set to NULL, a subdirectory of tempdir() will be used. lib_dir will be normalized via normalizePath().

The package cache is under the directory specified by getOption("apicheck.lib_dir"), or, if that is unset, in a per-session temporary directory. You should use set_lib_dir() to change this rather than setting the option directly. Within this directory, subdirectories are named like package-version, e.g. longurl-0.3.0. Within these subdirectories are the actual installed libraries. So, lib_dir is not appropriate for passing to functions like library. To load a library from the cache yourself, do e.g. library("blah", lib.loc = file.path(get_lib_dir(), "blah-0.1.0")).

Value

set_lib_dir invisibly returns the old library location, or NULL if none was set in options.

get_lib_dir returns the actual library location, whether or not an option has been set.

clear_lib_dir invisibly returns TRUE if all files and directories could be removed, FALSE otherwise.

Examples

## Not run: 
set_lib_dir("~/.apicheck")

## End(Not run)
get_lib_dir()
## Not run: 
clear_lib_dir()

## End(Not run)
## Not run: 
set_lib_dir("~/.apicheck")

## End(Not run)
get_lib_dir()
## Not run: 
clear_lib_dir()

## End(Not run)

Return the current version of a package at a given date

Description

Return the current version of a package at a given date

Usage

version_at_date(package, date)
version_at_date(package, date)

Arguments

`package`	Package. Alternatively, specify the function name as e.g. `"package::function"`.
`date`	Date, as a character string that can be read by `as.Date()` e.g. "2016-01-01".

Value

A version string.

Examples

## Not run: 
version_at_date("huxtable", "2017-01-01")

## End(Not run)
## Not run: 
version_at_date("huxtable", "2017-01-01")

## End(Not run)

Compare APIs across package versions

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, ...)
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

Examples

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

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

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

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

## End(Not run)

Package 'apicheck'

Help Index

apicheck: check function APIs in different versions of packages

Description

Details

Warning

Test if a function's API is unchanged

Description

Usage

Arguments

Details

Value

Examples

Report available versions

Description

Usage

Arguments

Value

Speed

Examples

Install and/or load a version of a package

Description

Usage

Arguments

Details

Value

Examples

Load a package namespace and pass it to a function

Description

Usage

Arguments

Value

Examples

Compare versions of a package

Description

Usage

Arguments

Value

Examples

Retrieve a function from a package version

Description

Usage

Arguments

Details

Value

Examples

Test if a function exists at a given package version

Description

Usage

Arguments

Value

Examples

Get help for a function at a package version

Description

Usage

Arguments

Value

See Also

Examples

Report on backwards compatibility of a source package

Description

Usage

Arguments

Value

Parallelism

Examples

Location of the package cache

Description

Usage

Arguments

Details

Value

Examples

Return the current version of a package at a given date

Description

Usage

Arguments

Value

Examples

Compare APIs across package versions