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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deprecate.R
\name{deprecate_soft}
\alias{deprecate_soft}
\alias{deprecate_warn}
\alias{deprecate_stop}
\title{Deprecate functions and arguments}
\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{
\item{when}{A string giving the version when the behaviour was deprecated.}
\item{what}{A string describing what is deprecated:
\itemize{
\item Deprecate a whole function with \code{"foo()"}.
\item Deprecate an argument with \code{"foo(arg)"}.
\item Partially deprecate an argument with
\code{"foo(arg = 'must be a scalar integer')"}.
\item Deprecate anything else with a custom message by wrapping it in \code{I()}.
}
You can optionally supply the namespace: \code{"ns::foo()"}, but this is
usually not needed as it will be inferred from the caller environment.}
\item{with}{An optional string giving a recommended replacement for the
deprecated behaviour. This takes the same form as \code{what}.}
\item{details}{In most cases the deprecation message can be
automatically generated from \code{with}. When it can't, use \code{details}
to provide a hand-written message.
\code{details} can either be a single string or a character vector,
which will be converted to a \link[cli:cli_bullets]{bulleted list}.
By default, info bullets are used. Provide a named vectors to
override.}
\item{id}{The id of the deprecation. A warning is issued only once
for each \code{id}. Defaults to the generated message, but you should
give a unique ID when the message in \code{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.}
\item{env, user_env}{Pair of environments that define where \verb{deprecate_*()}
was called (used to determine the package name) and where the function
called the deprecating function was called (used to determine if
\code{deprecate_soft()} should message).
These are only needed if you're calling \verb{deprecate_*()} from an internal
helper, in which case you should forward \code{env = caller_env()} and
\code{user_env = caller_env(2)}.}
\item{always}{If \code{FALSE}, the default, will warn every 8 hours. If
\code{TRUE}, will always warn in direct usages. Indirect usages keep
warning every 8 hours to avoid disrupting users who can't fix the
issue. Only use \code{always = TRUE} after at least one release with
the default.}
}
\value{
\code{NULL}, invisibly.
}
\description{
These functions provide three levels of verbosity for deprecated
functions. Learn how to use them in \code{vignette("communicate")}.
\itemize{
\item \code{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.
\item \code{deprecate_warn()} warns unconditionally.
\item \code{deprecate_stop()} fails unconditionally.
}
Warnings are only issued once every 8 hours to avoid overwhelming
the user. Control with \code{\link[=verbosity]{options(lifecycle_verbosity)}}.
}
\section{Conditions}{
\itemize{
\item Deprecation warnings have class \code{lifecycle_warning_deprecated}.
\item Deprecation errors have class \code{lifecycle_error_deprecated}.
}
}
\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?"
)
)
}
\seealso{
\code{\link[=lifecycle]{lifecycle()}}
}
|
