deprecate_soft {lifecycle} | R Documentation |
Deprecate functions and arguments
Description
These functions provide three levels of verbosity for deprecated
functions. Learn how to use them in vignette("communicate")
.
-
deprecate_soft()
warns only if the deprecated function is called directly, i.e. a user is calling a function they wrote in the global environment or a developer is calling it in their package. It does not warn when called indirectly, i.e. the deprecation comes from code that you don't control. -
deprecate_warn()
warns unconditionally. -
deprecate_stop()
fails unconditionally.
Warnings are only issued once every 8 hours to avoid overwhelming
the user. Control with options(lifecycle_verbosity)
.
Usage
deprecate_soft(
when,
what,
with = NULL,
details = NULL,
id = NULL,
env = caller_env(),
user_env = caller_env(2)
)
deprecate_warn(
when,
what,
with = NULL,
details = NULL,
id = NULL,
always = FALSE,
env = caller_env(),
user_env = caller_env(2)
)
deprecate_stop(when, what, with = NULL, details = NULL, env = caller_env())
Arguments
when |
A string giving the version when the behaviour was deprecated. |
what |
A string describing what is deprecated:
You can optionally supply the namespace: |
with |
An optional string giving a recommended replacement for the
deprecated behaviour. This takes the same form as |
details |
In most cases the deprecation message can be
automatically generated from
|
id |
The id of the deprecation. A warning is issued only once
for each |
env , user_env |
Pair of environments that define where These are only needed if you're calling |
always |
If |
Value
NULL
, invisibly.
Conditions
Deprecation warnings have class
lifecycle_warning_deprecated
.Deprecation errors have class
lifecycle_error_deprecated
.
See Also
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 custom message:
deprecate_warn(
when = "1.0.0",
what = "foo()",
details = "Please use `otherpackage::bar(foo = TRUE)` instead"
)
# A deprecated function with custom bulleted list:
deprecate_warn(
when = "1.0.0",
what = "foo()",
details = c(
x = "This is dangerous",
i = "Did you mean `safe_foo()` instead?"
)
)