% File src/library/utils/man/txtProgressBar.Rd
% Part of the R package, https://www.R-project.org
% Copyright 2008-21 R Core Team
% Distributed under GPL 2 or later

\name{txtProgressBar}
\alias{txtProgressBar}
\alias{getTxtProgressBar}
\alias{setTxtProgressBar}
\alias{close.txtProgressBar}
\title{Text Progress Bar}
\description{
  Text progress bar in the \R console.
}
\usage{
txtProgressBar(min = 0, max = 1, initial = 0, char = "=",
               width = NA, title, label, style = 1, file = "")

getTxtProgressBar(pb)
setTxtProgressBar(pb, value, title = NULL, label = NULL)
\method{close}{txtProgressBar}(con, \dots)
}
\arguments{
  \item{min, max}{(finite) numeric values for the extremes of the
    progress bar. Must have \code{min < max}.}
  \item{initial, value}{initial or new value for the progress bar.  See
    \sQuote{Details} for what happens with invalid values.}
  \item{char}{the character (or character string) to form the progress
    bar.  Must have non-zero display width.}
  \item{width}{the width of the progress bar, as a multiple of the width
    of \code{char}.  If \code{NA}, the default, the number of characters
    is that which fits into \code{getOption("width")}.}
  \item{style}{the \sQuote{style} of the bar -- see \sQuote{Details}.}
  \item{file}{an open connection object or \code{""} which indicates
    the console: \code{\link{stderr}()} might be useful here.}
  \item{pb, con}{an object of class \code{"txtProgressBar"}.}
  \item{title, label}{ignored, for compatibility with other progress bars.}
  \item{\dots}{for consistency with the generic.}
}
\details{
  \code{txtProgressBar} will display a progress bar on the \R console
  (or a connection) via a text representation.

  \code{setTxtProgessBar} will update the value.  Missing
  (\code{\link{NA}}) and out-of-range values of \code{value} will be
  (silently) ignored.  (Such values of \code{initial} cause the progress
  bar not to be displayed until a valid value is set.)

  The progress bar should be \code{close}d when finished with: this
  outputs the final newline character.

  \code{style = 1} and \code{style = 2} just shows a line of
  \code{char}. They differ in that \code{style = 2} redraws the line
  each time, which is useful if other code might be writing to the \R
  console.  \code{style = 3} marks the end of the range by \samp{|} and
  gives a percentage to the right of the bar.
}
\value{
  For \code{txtProgressBar} an object of class \code{"txtProgressBar"}.

  For \code{getTxtProgressBar} and \code{setTxtProgressBar}, a
  length-one numeric vector giving the previous value (invisibly for
  \code{setTxtProgressBar}).
}
\note{
  Using \code{style} 2 or 3 or reducing the value with \code{style = 1}
  uses \samp{\r} to return to the left margin -- the interpretation of
  carriage return is up to the terminal or console in which \R is
  running, and this is liable to produce ugly output on a connection
  other than a terminal, including when \code{stdout()} is
  redirected to a file.
}
\seealso{
  \code{\link{winProgressBar}} (Windows only),
  \code{\link{tkProgressBar}} (Unix-alike platforms).
}
\examples{\donttest{ # slow
testit <- function(x = sort(runif(20)), ...)
{
    pb <- txtProgressBar(...)
    for(i in c(0, x, 1)) {Sys.sleep(0.5); setTxtProgressBar(pb, i)}
    Sys.sleep(1)
    close(pb)
}
testit()
testit(runif(10))
testit(style = 3)
testit(char=' \u27a4')
}}
\keyword{utilities}