retire: Deprecate a function or argument

Description Usage Arguments Deprecation levels Deprecation cycle Examples

View source: R/retire.R

Description

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.

Usage

1
2
3
retire(.fn, .cycle, ..., .msg = NULL)

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

Arguments

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

Deprecation levels

There are three deprecation levels:

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.

Deprecation cycle

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 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)

lionel-/oldie documentation built on Sept. 7, 2017, 11 a.m.