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
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/progress-along.R
\name{cli_progress_along}
\alias{cli_progress_along}
\title{Add a progress bar to a mapping function or for loop}
\usage{
cli_progress_along(
x,
name = NULL,
total = length(x),
...,
.envir = parent.frame()
)
}
\arguments{
\item{x}{Sequence to add the progress bar to.}
\item{name}{Name of the progress bar, a label, passed to
\code{\link[=cli_progress_bar]{cli_progress_bar()}}.}
\item{total}{Passed to \code{\link[=cli_progress_bar]{cli_progress_bar()}}.}
\item{...}{Passed to \code{\link[=cli_progress_bar]{cli_progress_bar()}}.}
\item{.envir}{Passed to \code{\link[=cli_progress_bar]{cli_progress_bar()}}.}
}
\value{
An index vector from 1 to \code{length(x)} that triggers progress
updates as you iterate over it.
}
\description{
Note that this function is currently experimental!
Use \code{cli_progress_along()} in a mapping function or in a for loop, to add a
progress bar. It uses \code{\link[=cli_progress_bar]{cli_progress_bar()}} internally.
}
\details{
\subsection{\code{for} loop}{
A \code{for} loop with \code{cli_progress_along()} looks like this:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{for (i in cli_progress_along(seq)) \{
...
\}
}\if{html}{\out{</div>}}
A complete example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{clifun <- function() \{
for (i in cli_progress_along(1:100, "Downloading")) \{
Sys.sleep(4/100)
\}
\}
clifun()
}\if{html}{\out{</div>}}
\if{html}{\figure{progress-along-1.svg}}
}
\subsection{\code{lapply()} and other mapping functions}{
They will look like this:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{lapply(cli_progress_along(X), function(i) ...)
}\if{html}{\out{</div>}}
A complete example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{res <- lapply(cli_progress_along(1:100, "Downloading"), function(i) \{
Sys.sleep(4/100)
\})
}\if{html}{\out{</div>}}
\if{html}{\figure{progress-along-2.svg}}
}
\subsection{Custom format string}{
\if{html}{\out{<div class="sourceCode r">}}\preformatted{clifun <- function() \{
for (i in cli_progress_along(1:100,
format = "Downloading data file \{cli::pb_current\}")) \{
Sys.sleep(4/100)
\}
\}
clifun()
}\if{html}{\out{</div>}}
\if{html}{\figure{progress-along-3.svg}}
}
\subsection{Breaking out of loops}{
Note that if you use \code{break} in the \code{for} loop, you probably want to
terminate the progress bar explicitly when breaking out of the loop,
or right after the loop:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{for (i in cli_progress_along(seq)) \{
...
if (cond) cli_progress_done() && break
...
\}
}\if{html}{\out{</div>}}
}
}
\seealso{
This function supports \link[=inline-markup]{inline markup}.
\code{\link[=cli_progress_bar]{cli_progress_bar()}} and the traditional progress bar API.
Other progress bar functions:
\code{\link{cli_progress_bar}()},
\code{\link{cli_progress_builtin_handlers}()},
\code{\link{cli_progress_message}()},
\code{\link{cli_progress_num}()},
\code{\link{cli_progress_output}()},
\code{\link{cli_progress_step}()},
\code{\link{cli_progress_styles}()},
\code{\link{progress-variables}}
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_process_start}()},
\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{progress bar functions}
|
