deprecate_soft {lifecycle}R Documentation

Deprecate functions and arguments

Description

These functions provide three levels of verbosity for deprecated functions.

Warnings are only issued once every 8 hours to avoid overwhelming the user. See the verbosity option to control this behaviour.

Deprecation warnings have class lifecycle_warning_deprecated. Deprecation errors have class lifecycle_error_deprecated.

Usage

deprecate_soft(
  when,
  what,
  with = NULL,
  details = NULL,
  id = NULL,
  env = caller_env(2)
)

deprecate_warn(
  when,
  what,
  with = NULL,
  details = NULL,
  id = NULL,
  env = caller_env(2)
)

deprecate_stop(when, what, with = NULL, details = NULL)

Arguments

when

The package version when function/argument was deprecated.

what

If the deprecated feature is a whole function, the function name: "foo()". If it's an argument that is being deprecated, the function call should include the argument: "foo(arg = )".

You can optionally supply the namespace: "ns::foo()". If not supplied, it is inferred from the caller environment.

with

An optional replacement for the deprecated feature. This should be a string of the same form as what.

details

The deprecation message is generated from when, what, and with. You can additionally supply a string details to be appended to the message.

id

The id of the deprecation. A warning is issued only once for each id. Defaults to the generated message, but you should give a unique ID when the message in details is built programmatically and depends on inputs, or when you'd like to deprecate multiple functions but warn only once for all of them.

env

The environment in which the deprecated function was called. A warning is issued if called from the global environment. If testthat is running, a warning is also called if the deprecated function was called from the package being tested.

This typically doesn't need to be specified, unless you call deprecate_soft() or deprecate_warn() from an internal helper. In that case, you need to forward the calling environment.

Value

NULL, invisibly.

See Also

lifecycle()

Examples

# A deprecated function `foo`:
deprecate_warn("1.0.0", "foo()")

# A deprecated argument `arg`:
deprecate_warn("1.0.0", "foo(arg = )")

# A partially deprecated argument `arg`:
deprecate_warn("1.0.0", "foo(arg = 'must be a scalar integer')")

# A deprecated function with a function replacement:
deprecate_warn("1.0.0", "foo()", "bar()")

# A deprecated function with a function replacement from a
# different package:
deprecate_warn("1.0.0", "foo()", "otherpackage::bar()")

# A deprecated function with an argument replacement:
deprecate_warn("1.0.0", "foo()", "foo(bar = )")


[Package lifecycle version 0.2.0 Index]