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
144
145
146
147
148
149
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/status-bar.R
\name{cli_process_start}
\alias{cli_process_start}
\alias{cli_process_done}
\alias{cli_process_failed}
\title{Indicate the start and termination of some computation in the status bar
(superseded)}
\usage{
cli_process_start(
msg,
msg_done = paste(msg, "... done"),
msg_failed = paste(msg, "... failed"),
on_exit = c("auto", "failed", "done"),
msg_class = "alert-info",
done_class = "alert-success",
failed_class = "alert-danger",
.auto_close = TRUE,
.envir = parent.frame()
)
cli_process_done(
id = NULL,
msg_done = NULL,
.envir = parent.frame(),
done_class = "alert-success"
)
cli_process_failed(
id = NULL,
msg = NULL,
msg_failed = NULL,
.envir = parent.frame(),
failed_class = "alert-danger"
)
}
\arguments{
\item{msg}{The message to show to indicate the start of the process or
computation. It will be collapsed into a single string, and the first
line is kept and cut to \code{\link[=console_width]{console_width()}}.}
\item{msg_done}{The message to use for successful termination.}
\item{msg_failed}{The message to use for unsuccessful termination.}
\item{on_exit}{Whether this process should fail or terminate
successfully when the calling function (or the environment in \code{.envir})
exits.}
\item{msg_class}{The style class to add to the message. Use an empty
string to suppress styling.}
\item{done_class}{The style class to add to the successful termination
message. Use an empty string to suppress styling.a}
\item{failed_class}{The style class to add to the unsuccessful
termination message. Use an empty string to suppress styling.a}
\item{.auto_close}{Whether to clear the status bar when the calling
function finishes (or \code{.envir} is removed from the stack, if
specified).}
\item{.envir}{Environment to evaluate the glue expressions in. It is
also used to auto-clear the status bar if \code{.auto_close} is \code{TRUE}.}
\item{id}{Id of the status bar container to clear. If \code{id} is not the id
of the current status bar (because it was overwritten by another
status bar container), then the status bar is not cleared. If \code{NULL}
(the default) then the status bar is always cleared.}
}
\value{
Id of the status bar container.
}
\description{
\strong{The \verb{cli_process_*()} functions are superseded by
the \code{\link[=cli_progress_message]{cli_progress_message()}} and \code{\link[=cli_progress_step]{cli_progress_step()}} functions,
because they have a better default behavior.}
Typically you call \code{cli_process_start()} to start the process, and then
\code{cli_process_done()} when it is done. If an error happens before
\code{cli_process_done()} is called, then cli automatically shows the message
for unsuccessful termination.
}
\details{
If you handle the errors of the process or computation, then you can do
the opposite: call \code{cli_process_start()} with \code{on_exit = "done"}, and
in the error handler call \code{cli_process_failed()}. cli will automatically
call \code{cli_process_done()} on successful termination, when the calling
function finishes.
See examples below.
}
\examples{
## Failure by default
fun <- function() {
cli_process_start("Calculating")
if (interactive()) Sys.sleep(1)
if (runif(1) < 0.5) stop("Failed")
cli_process_done()
}
tryCatch(fun(), error = function(err) err)
## Success by default
fun2 <- function() {
cli_process_start("Calculating", on_exit = "done")
tryCatch({
if (interactive()) Sys.sleep(1)
if (runif(1) < 0.5) stop("Failed")
}, error = function(err) cli_process_failed())
}
fun2()
}
\seealso{
This function supports \link[=inline-markup]{inline markup}.
The \code{\link[=cli_progress_message]{cli_progress_message()}} and \code{\link[=cli_progress_step]{cli_progress_step()}}
functions, for a superior API.
Other status bar:
\code{\link{cli_status}()},
\code{\link{cli_status_clear}()},
\code{\link{cli_status_update}()}
Other functions supporting inline markup:
\code{\link{cli_abort}()},
\code{\link{cli_alert}()},
\code{\link{cli_blockquote}()},
\code{\link{cli_bullets}()},
\code{\link{cli_bullets_raw}()},
\code{\link{cli_dl}()},
\code{\link{cli_h1}()},
\code{\link{cli_li}()},
\code{\link{cli_ol}()},
\code{\link{cli_progress_along}()},
\code{\link{cli_progress_bar}()},
\code{\link{cli_progress_message}()},
\code{\link{cli_progress_output}()},
\code{\link{cli_progress_step}()},
\code{\link{cli_rule}},
\code{\link{cli_status}()},
\code{\link{cli_status_update}()},
\code{\link{cli_text}()},
\code{\link{cli_ul}()},
\code{\link{format_error}()},
\code{\link{format_inline}()}
}
\concept{functions supporting inline markup}
\concept{status bar}
|
