retire: Deprecate a function or argument
In lionel-/oldie: Tools for Deprecating and Retiring Functions or Arguments

Description Usage Arguments Deprecation levels Deprecation cycle Examples

View source: R/retire.R

retire() marks a function or some of its arguments as obsolete. This enables automatic documentation by roxygen, signals a condition when a deprecated function is run or when a deprecated argument is supplied, and checks that the deprecation cycle conforms to tidyverse rules.

The conditions are signalled with with signal_retired() which has the same interface as retire(). It should always be called directly within the deprecated function. Since it is added automatically by retire(), you should rarely have to call it yourself.

1
2
3

retire(.fn, .cycle, ..., .msg = NULL)

signal_retired(.fn, .cycle, ..., .msg = NULL)

`.fn`	The function to deprecate or whose arguments are to be deprecated. This should be supplied as a bare name.
`.cycle`	A character vector defining the deprecation cycle. See the relevant section.
`...`	Replacements, supplied as bare names. If no replacement is supplied, the function is deprecated with no replacement. If a single unnamed replacement is supplied, the function is deprecated with the replacement. If the replacement function lives in another package, indicate it with a namespace: `"pkg::replacement"`. If one or several named replacements are supplied, the function is not deprecated. Instead, the supplied arguments are. `old = new` means that the argument `old` is deprecated with replacement `new`. `old =` means that the argument `old` is deprecated without replacement.
`.msg`	An alternative deprecation message.

There are three deprecation levels:

Soft-deprecated: This is the first stage of deprecation. The function or argument continues to work normally without any warning. Soft-deprecated functions will generally not be documented, and should not be used in examples or package code. They are left around so that existing code continues to work, but new code should not use them.

To make soft-deprecated functions signal an error, see below.
Deprecated: The function or argument now issues a warning when used or supplied. Users should upgrade their code to use the suggested replacement, if any.
Defunct: The function or argument now issues an error when used or supplied.

These levels are defined by a deprecation cycle, see section below. You can promote the current deprecation level by setting the global option oldie_verbose_retirement to TRUE. Soft-deprecated functions then become deprecated, deprecated functions become defunct, and so on. This is useful to check whether you're relying on any soft-deprecated functions or arguments.

.cycle associates each deprecation stage to a release version of your package. It should be a character vectors of three versions.

c("0.1.0", "0.3.0", "1.0.0"): Soft-deprecation at after the 0.1.0 release, deprecation after 0.3.0, and defunct after 1.0.0.
"0.1.0": This is equivalent to c("0.1.0", "0.2.0", "0.3.0"). When a single version is supplied, it is assumed that it marks the start of a deprecation cycle that is bumped at each minor version (middle number).
c("0.1.0", "", ""): The function is soft-deprecated but is not planned to ever be deprecated or defunct. This is useful for discouraging users from using a function without forcing them to change their code.

# Let's create an obsolete function:
old_fn <- function() "old"

# You can deprecate it without any replacement:
retire(old_fn, "0.1.0")

# The cycle above specifies only one version. The cycle is
# automatically filled and the above expression is thus equivalent to:
retire(old_fn, c("0.1.0", "0.2.0", "0.3.0"))

# If there is a new function replacing the old one, just supply its
# bare name:
retire(old_fn, "0.1.0", replacement_fn)


# Deprecating an argument is very similar. They are supplied as
# key-value pairs where the key is the deprecated argument and the
# value, if supplied, is the replacement. This deprecates an
# argument without replacement:
fn <- function(..., old) NULL
retire(fn, "0.1.0", old = )

# This deprecates with replacement. The deprecated argument is
# automatically reassigned to the replacement:
fn <- function(..., new, old) NULL
retire(fn, "0.1.0", old = new)

# The deprecated argument will be added to the formals if
# needed. This way you can omit the deprecated arguments from the
# function declaration:
fn <- function(..., new) NULL
retire(fn, "0.1.0", old = new)