These functions provide three levels of verbosity for deprecated functions.

  • deprecate_soft() warns only if the deprecated function is called from the global environment (so the user can change their script) or from the package currently being tested (so the package developer can fix the package). Use for soft-deprecated functions.

  • deprecate_warn() warns unconditionally. Use for deprecated functions.

  • deprecate_stop() fails unconditionally. Use for defunct functions.

Warnings are only issued once per session to avoid overwhelming the user. See the verbosity option to control this behaviour.

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

Examples

# A deprecated function `foo`: deprecate_warn("1.0.0", "foo()")
#> Warning: `foo()` is deprecated as of <NA> 1.0.0. #> This warning is displayed once per session. #> Call `lifecycle::last_warnings()` to see where this warning was generated.
# A deprecated argument `arg`: deprecate_warn("1.0.0", "foo(arg = )")
#> Warning: The `arg` argument of `foo()` is deprecated as of <NA> 1.0.0. #> This warning is displayed once per session. #> Call `lifecycle::last_warnings()` to see where this warning was generated.
# A deprecated function with a function replacement: deprecate_warn("1.0.0", "foo()", "bar()")
#> Warning: `foo()` is deprecated as of <NA> 1.0.0. #> Please use `bar()` instead. #> This warning is displayed once per session. #> Call `lifecycle::last_warnings()` to see where this warning was generated.
# A deprecated function with a function replacement from a # different package: deprecate_warn("1.0.0", "foo()", "otherpackage::bar()")
#> Warning: `foo()` is deprecated as of <NA> 1.0.0. #> Please use `otherpackage::bar()` instead. #> This warning is displayed once per session. #> Call `lifecycle::last_warnings()` to see where this warning was generated.
# A deprecated function with an argument replacement: deprecate_warn("1.0.0", "foo()", "foo(bar = )")
#> Warning: `foo()` is deprecated as of <NA> 1.0.0. #> Please use the `bar` argument instead. #> This warning is displayed once per session. #> Call `lifecycle::last_warnings()` to see where this warning was generated.