Package 'cli'

Description

Align an ANSI colored string

Usage

ansi_align(
  text,
  width = console_width(),
  align = c("left", "center", "right"),
  type = "width"
)

Arguments

Details

str <- c(
  col_red("This is red"),
  style_bold("This is bold")
)
astr <- ansi_align(str, width = 30)
boxx(astr)

#> ┌────────────────────────────────────┐                                          
#> │                                    │                                          
#> │   This is red                      │                                          
#> │   This is bold                     │                                          
#> │                                    │                                          
#> └────────────────────────────────────┘                                          

str <- c(
  col_red("This is red"),
  style_bold("This is bold")
)
astr <- ansi_align(str, align = "center", width = 30)
boxx(astr)

#> ┌────────────────────────────────────┐                                          
#> │                                    │                                          
#> │             This is red            │                                          
#> │            This is bold            │                                          
#> │                                    │                                          
#> └────────────────────────────────────┘                                          

str <- c(
  col_red("This is red"),
  style_bold("This is bold")
)
astr <- ansi_align(str, align = "right", width = 30)
boxx(astr)

#> ┌────────────────────────────────────┐                                          
#> │                                    │                                          
#> │                      This is red   │                                          
#> │                     This is bold   │                                          
#> │                                    │                                          
#> └────────────────────────────────────┘                                          

Value

The aligned character vector.

See Also

Other ANSI string operations: ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Description

Features:

• custom separator (sep),

• custom separator for length-two input (sep2),

• custom last separator (last),

• adds ellipsis to truncated strings,

• uses Unicode ellipsis character on UTF-8 console,

• can collapse "from both ends", with style = "both-ends",

• can consider a limit for the display width of the result, in characters,

• handles ANSI control sequences correctly when measuring display width.

Usage

ansi_collapse(
  x,
  sep = ", ",
  sep2 = sub("^,", "", last),
  last = ", and ",
  trunc = Inf,
  width = Inf,
  ellipsis = symbol$ellipsis,
  style = c("both-ends", "head")
)

Arguments

Value

Character scalar. It is NA_character_ if any elements in x are NA.

See Also

glue_collapse in the glue package inspired this function.

Examples

ansi_collapse(letters)

# truncate
ansi_collapse(letters, trunc = 5)

# head style
ansi_collapse(letters, trunc = 5, style = "head")

Description

This function helps with multi-column output of ANSI styles strings. It works well together with boxx(), see the example below.

Usage

ansi_columns(
  text,
  width = console_width(),
  sep = " ",
  fill = c("rows", "cols"),
  max_cols = 4,
  align = c("left", "center", "right"),
  type = "width",
  ellipsis = symbol$ellipsis
)

Arguments

Details

If a string does not fit into the specified width, it will be truncated using ansi_strtrim().

fmt <- ansi_columns(
  paste(col_red("foo"), 1:10),
  width = 50,
  fill = "rows",
  max_cols=10,
  align = "center",
  sep = "   "
)
boxx(fmt, padding = c(0,1,0,1), header = col_cyan("Columns"))

#> ┌ Columns ───────────────────────────────────────────┐                          
#> │  foo 1     foo 2     foo 3     foo 4     foo 5     │                          
#> │  foo 6     foo 7     foo 8     foo 9     foo 10    │                          
#> └────────────────────────────────────────────────────┘                          

Value

ANSI string vector.

See Also

Other ANSI string operations: ansi_align(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Like base::grep() and base::grepl(), but for ANSI strings

Description

First ANSI sequences will be stripped with ansi_strip(), both

Usage

ansi_grep(pattern, x, ignore.case = FALSE, perl = FALSE, value = FALSE, ...)

ansi_grepl(pattern, x, ...)

Arguments

Details

Note that these functions work on code points (or bytes if useBytes = TRUE), and not graphemes.

Unlike base::grep() and base::grepl() these functions do not special case factors.

Both pattern and x are converted to UTF-8.

Value

The same as base::grep() and base::grepl(), respectively.

Examples

red_needle <- col_red("needle")
haystack <- c("foo", "needle", "foo")
green_haystack <- col_green(haystack)
ansi_grepl(red_needle, haystack)
ansi_grepl(red_needle, green_haystack)

Description

Check if a string has some ANSI styling

Usage

ansi_has_any(string, sgr = TRUE, csi = TRUE, link = TRUE)

Arguments

Value

Logical vector, TRUE for the strings that have some ANSI styling.

See Also

Other low level ANSI functions: ansi_hide_cursor(), ansi_regex(), ansi_string(), ansi_strip()

Examples

## The second one has style if ANSI colors are supported
ansi_has_any("foobar")
ansi_has_any(col_red("foobar"))

Description

This only works in terminal emulators. In other environments, it does nothing.

Usage

ansi_hide_cursor(stream = "auto")

ansi_show_cursor(stream = "auto")

ansi_with_hidden_cursor(expr, stream = "auto")

Arguments

Details

ansi_hide_cursor() hides the cursor.

ansi_show_cursor() shows the cursor.

ansi_with_hidden_cursor() temporarily hides the cursor for evaluating an expression.

See Also

Other terminal capabilities: is_ansi_tty(), is_dynamic_tty()

Other low level ANSI functions: ansi_has_any(), ansi_regex(), ansi_string(), ansi_strip()

Description

Convert ANSI styled text to HTML

Usage

ansi_html(x, escape_reserved = TRUE, csi = c("drop", "keep"))

Arguments

Value

Character vector of HTML.

See Also

Other ANSI to HTML conversion: ansi_html_style()

Examples

## Syntax highlight the source code of an R function with ANSI tags,
## and export it to a HTML file.
code <- withr::with_options(
  list(ansi.num_colors = 256),
  code_highlight(format(ansi_html))
)
hcode <- paste(ansi_html(code), collapse = "\n")
css <- paste(format(ansi_html_style()), collapse=  "\n")
page <- htmltools::tagList(
  htmltools::tags$head(htmltools::tags$style(css)),
  htmltools::tags$pre(htmltools::HTML(hcode))
)

if (interactive()) htmltools::html_print(page)

Description

CSS styles for the output of ansi_html()

Usage

ansi_html_style(
  colors = TRUE,
  palette = c("vscode", "dichro", "vga", "winxp", "win10", "macos", "putty", "mirc",
    "xterm", "ubuntu", "eclipse", "iterm", "iterm-pastel", "iterm-smoooooth",
    "iterm-snazzy", "iterm-solarized", "iterm-tango")
)

Arguments

Value

Named list of CSS declaration blocks, where the names are CSS selectors. It has a format() and print() methods, which you can use to write the output to a CSS or HTML file.

See Also

Other ANSI to HTML conversion: ansi_html()

Examples

ansi_html_style(colors = FALSE)
ansi_html_style(colors = 8, palette = "iterm-snazzy")

Description

This is a color-aware counterpart of utf8_nchar(). By default it counts Unicode grapheme clusters, instead of code points.

Usage

ansi_nchar(x, type = c("chars", "bytes", "width", "graphemes", "codepoints"))

Arguments

Value

Numeric vector, the length of the strings in the character vector.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Examples

str <- paste(
  col_red("red"),
  "default",
  col_green("green")
)

cat(str, "\n")
nchar(str)
ansi_nchar(str)
nchar(ansi_strip(str))

Like base::nzchar(), but for ANSI strings

Description

Like base::nzchar(), but for ANSI strings

Usage

ansi_nzchar(x, ...)

Arguments

Examples

ansi_nzchar("")
ansi_nzchar(col_red(""))

Description

Don't forget to use perl = TRUE when using this with grepl() and friends.

Usage

ansi_regex()

Value

String scalar, the regular expression.

See Also

Other low level ANSI functions: ansi_has_any(), ansi_hide_cursor(), ansi_string(), ansi_strip()

Description

It creates an equivalent, but possibly shorter ANSI styled string, by removing duplicate and empty tags.

Usage

ansi_simplify(x, csi = c("keep", "drop"))

Arguments

Value

Simplified cli_ansi_string vector.

Description

This function sets the class of its argument, activating ANSI-string-specific methods such as for printing.

Usage

ansi_string(x)

Arguments

Value

A cli_ansi_string object, a subclass of character, with the same length and contents as x.

See Also

Other low level ANSI functions: ansi_has_any(), ansi_hide_cursor(), ansi_regex(), ansi_strip()

Description

The input may be of class cli_ansi_string class, this is also dropped from the result.

Usage

ansi_strip(string, sgr = TRUE, csi = TRUE, link = TRUE)

Arguments

Value

The cleaned up string. Note that ansi_strip() always drops the cli_ansi_string class, even if sgr and sciareFALSE'.

See Also

Other low level ANSI functions: ansi_has_any(), ansi_hide_cursor(), ansi_regex(), ansi_string()

Examples

ansi_strip(col_red("foobar")) == "foobar"

Description

This is the color-aware counterpart of base::strsplit(). It works almost exactly like the original, but keeps the colors in the substrings.

Usage

ansi_strsplit(x, split, ...)

Arguments

Value

A list of the same length as x, the i-th element of which contains the vector of splits of x[i]. ANSI styles are retained.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Examples

str <- paste0(
  col_red("I am red---"),
  col_green("and I am green-"),
  style_underline("I underlined")
)

cat(str, "\n")

# split at dashes, keep color
cat(ansi_strsplit(str, "[-]+")[[1]], sep = "\n")
strsplit(ansi_strip(str), "[-]+")

# split to characters, keep color
cat(ansi_strsplit(str, "")[[1]], "\n", sep = " ")
strsplit(ansi_strip(str), "")

Description

This function is similar to base::strtrim(), but works correctly with ANSI styled strings. It also adds ... (or the corresponding Unicode character if Unicode characters are allowed) to the end of truncated strings.

Usage

ansi_strtrim(x, width = console_width(), ellipsis = symbol$ellipsis)

Arguments

Details

Note: ansi_strtrim() does not support NA values currently.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Examples

text <- cli::col_red(cli:::lorem_ipsum())
ansi_strtrim(c(text, "foobar"), 40)

Description

This function is similar to base::strwrap(), but works on ANSI styled strings, and leaves the styling intact.

Usage

ansi_strwrap(
  x,
  width = console_width(),
  indent = 0,
  exdent = 0,
  simplify = TRUE
)

Arguments

Value

If simplify is FALSE, then a list of character vectors, each an ANSI string. Otherwise a single ANSI string vector.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_substr(), ansi_substring(), ansi_toupper(), ansi_trimws()

Examples

text <- cli:::lorem_ipsum()
# Highlight some words, that start with 's'
rexp <- gregexpr("\\b([sS][a-zA-Z]+)\\b", text)
regmatches(text, rexp) <- lapply(regmatches(text, rexp), col_red)
cat(text)

wrp <- ansi_strwrap(text, width = 40)
cat(wrp, sep = "\n")

Description

This is a color-aware counterpart of base::substr(). It works exactly like the original, but keeps the colors in the substrings. The ANSI escape sequences are ignored when calculating the positions within the string.

Usage

ansi_substr(x, start, stop)

Arguments

Value

Character vector of the same length as x, containing the requested substrings. ANSI styles are retained.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substring(), ansi_toupper(), ansi_trimws()

Examples

str <- paste(
  col_red("red"),
  "default",
  col_green("green")
)

cat(str, "\n")
cat(ansi_substr(str, 1, 5), "\n")
cat(ansi_substr(str, 1, 15), "\n")
cat(ansi_substr(str, 3, 7), "\n")

substr(ansi_strip(str), 1, 5)
substr(ansi_strip(str), 1, 15)
substr(ansi_strip(str), 3, 7)

str2 <- paste(
  "another",
  col_red("multi-", style_underline("style")),
  "text"
)

cat(str2, "\n")
cat(ansi_substr(c(str, str2), c(3,5), c(7, 18)), sep = "\n")
substr(ansi_strip(c(str, str2)), c(3,5), c(7, 18))

Description

This is the color-aware counterpart of base::substring(). It works exactly like the original, but keeps the colors in the substrings. The ANSI escape sequences are ignored when calculating the positions within the string.

Usage

ansi_substring(text, first, last = 1000000L)

Arguments

Value

Character vector of the same length as x, containing the requested substrings. ANSI styles are retained.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_toupper(), ansi_trimws()

Examples

str <- paste(
  col_red("red"),
  "default",
  col_green("green")
)

cat(str, "\n")
cat(ansi_substring(str, 1, 5), "\n")
cat(ansi_substring(str, 1, 15), "\n")
cat(ansi_substring(str, 3, 7), "\n")

substring(ansi_strip(str), 1, 5)
substring(ansi_strip(str), 1, 15)
substring(ansi_strip(str), 3, 7)

str2 <- paste(
  "another",
  col_red("multi-", style_underline("style")),
  "text"
)

cat(str2, "\n")
cat(ansi_substring(str2, c(3,5), c(7, 18)), sep = "\n")
substring(ansi_strip(str2), c(3,5), c(7, 18))

Description

There functions are similar to toupper(), tolower() and chartr(), but they keep the ANSI colors of the string.

Usage

ansi_toupper(x)

ansi_tolower(x)

ansi_chartr(old, new, x)

Arguments

Value

Character vector of the same length as x, containing the translated strings. ANSI styles are retained.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_trimws()

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_trimws()

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_trimws()

Examples

ansi_toupper(col_red("Uppercase"))

ansi_tolower(col_red("LowerCase"))

x <- paste0(col_green("MiXeD"), col_red(" cAsE 123"))
ansi_chartr("iXs", "why", x)

Description

This function is similar to base::trimws() but works on ANSI strings, and keeps color and other styling.

Usage

ansi_trimws(x, which = c("both", "left", "right"))

Arguments

Value

ANSI string, with the whitespace removed.

See Also

Other ANSI string operations: ansi_align(), ansi_columns(), ansi_nchar(), ansi_strsplit(), ansi_strtrim(), ansi_strwrap(), ansi_substr(), ansi_substring(), ansi_toupper()

Examples

trimws(paste0("   ", col_red("I am red"), "   "))
ansi_trimws(paste0("   ", col_red("I am red"), "   "))
trimws(col_red("   I am red   "))
ansi_trimws(col_red("   I am red   "))

Description

cli has a number of functions to color and style text at the command line. They provide a more modern interface than the crayon package.

Usage

bg_black(...)

bg_blue(...)

bg_cyan(...)

bg_green(...)

bg_magenta(...)

bg_red(...)

bg_white(...)

bg_yellow(...)

bg_none(...)

bg_br_black(...)

bg_br_blue(...)

bg_br_cyan(...)

bg_br_green(...)

bg_br_magenta(...)

bg_br_red(...)

bg_br_white(...)

bg_br_yellow(...)

col_black(...)

col_blue(...)

col_cyan(...)

col_green(...)

col_magenta(...)

col_red(...)

col_white(...)

col_yellow(...)

col_grey(...)

col_silver(...)

col_none(...)

col_br_black(...)

col_br_blue(...)

col_br_cyan(...)

col_br_green(...)

col_br_magenta(...)

col_br_red(...)

col_br_white(...)

col_br_yellow(...)

style_dim(...)

style_blurred(...)

style_bold(...)

style_hidden(...)

style_inverse(...)

style_italic(...)

style_reset(...)

style_strikethrough(...)

style_underline(...)

style_no_bold(...)

style_no_blurred(...)

style_no_dim(...)

style_no_italic(...)

style_no_underline(...)

style_no_inverse(...)

style_no_hidden(...)

style_no_strikethrough(...)

style_no_color(...)

style_no_bg_color(...)

Arguments

Details

The ⁠col_*⁠ functions change the (foreground) color to the text. These are the eight original ANSI colors. Note that in some terminals, they might actually look differently, as terminals have their own settings for how to show them. col_none() is the default color, this is useful in a substring of a colored string.

The ⁠col_br_*⁠ functions are bright versions of the eight ANSI colors. Note that on some terminal configurations and themes they might be the same as the non-bright colors.

The ⁠bg_*⁠ functions change the background color of the text. These are the eight original ANSI background colors. These, too, can vary in appearance, depending on terminal settings. bg_none() the the default background color, this is useful in a substring of a background-colored string.

The ⁠bg_br_*⁠ functions are the bright versions of the eight ANSI background colors. Note that on some terminal configurations and themes they might be the same as the non-bright colors.

The ⁠style_*⁠ functions apply other styling to the text. The currently supported styling functions are:

• style_reset() to remove any style, including color,

• style_bold() for boldface / strong text, although some terminals show a bright, high intensity text instead,

• style_dim() (or style_blurred() reduced intensity text.

• style_italic() (not widely supported).

• style_underline(),

• style_inverse(),

• style_hidden(),

• style_strikethrough() (not widely supported).

The style functions take any number of character vectors as arguments, and they concatenate them using paste0() before adding the style.

Styles can also be nested, and then inner style takes precedence, see examples below.

Sometimes you want to revert back to the default text color, in the middle of colored text, or you want to have a normal font in the middle of italic text. You can use the ⁠style_no_*⁠ functions for this. Every ⁠style_*()⁠ function has a ⁠style_no_*()⁠ pair, which defends its argument from taking on the style. See examples below.

Value

An ANSI string (class cli_ansi_string), that contains ANSI sequences, if the current platform supports them. You can simply use cat() to print them to the terminal.

See Also

Other ANSI styling: combine_ansi_styles(), make_ansi_style(), num_ansi_colors()

Examples

col_blue("Hello ", "world!")
cat(col_blue("Hello ", "world!"))

cat("... to highlight the", col_red("search term"),
    "in a block of text\n")

## Style stack properly
cat(col_green(
 "I am a green line ",
 col_blue(style_underline(style_bold("with a blue substring"))),
 " that becomes green again!"
))

error <- combine_ansi_styles("red", "bold")
warn <- combine_ansi_styles("magenta", "underline")
note <- col_cyan
cat(error("Error: subscript out of bounds!\n"))
cat(warn("Warning: shorter argument was recycled.\n"))
cat(note("Note: no such directory.\n"))

# style_no_* functions, note that the color is not removed
style_italic(col_green(paste0(
  "italic before, ",
  style_no_italic("normal here, "),
  "italic after"
)))

# avoiding  color for substring
style_italic(col_red(paste(
  "red before",
  col_none("not red between"),
  "red after"
)))

Description

This theme is always active, and it is at the bottom of the theme stack. See themes.

Usage

builtin_theme(dark = getOption("cli.theme_dark", "auto"))

Arguments

Value

A named list, a CLI theme.

Showcase

cli_h1("Heading 1")
cli_h2("Heading 2")
cli_h3("Heading 3")

cli_par()
cli_alert_danger("Danger alert")
cli_alert_warning("Warning alert")
cli_alert_info("Info alert")
cli_alert_success("Success alert")
cli_alert("Alert for starting a process or computation",
  class = "alert-start")
cli_end()

cli_text("Packages and versions: {.pkg cli} {.version 1.0.0}.")
cli_text("Time intervals: {.timestamp 3.4s}")

cli_text("{.emph Emphasis} and  {.strong strong emphasis}")

cli_text("This is a piece of code: {.code sum(x) / length(x)}")
cli_text("Function names: {.fn cli::simple_theme}")

cli_text("Files: {.file /usr/bin/env}")
cli_text("URLs: {.url https://r-project.org}")

cli_h2("Longer code chunk")
cli_par(class = "code R")
cli_verbatim(
  '# window functions are useful for grouped mutates',
  'mtcars %>%',
  '  group_by(cyl) %>%',
  '  mutate(rank = min_rank(desc(mpg)))')

#> ── Heading 1 ─────────────────────────────────────────────────────────          
#>                                                                                 
#> ── Heading 2 ──                                                                 
#>                                                                                 
#> ── Heading 3                                                                    
#> ✖ Danger alert                                                                  
#> ! Warning alert                                                                 
#> ℹ Info alert                                                                    
#> ✔ Success alert                                                                 
#> → Alert for starting a process or computation                                   
#>                                                                                 
#> Packages and versions: cli 1.0.0.                                               
#> Time intervals: [3.4s]                                                          
#> Emphasis and strong emphasis                                                    
#> This is a piece of code: `sum(x) / length(x)`                                   
#> Function names: `cli::simple_theme()`                                           
#> Files: /usr/bin/env                                                             
#> URLs: <https://r-project.org>                                                   
#>                                                                                 
#> ── Longer code chunk ──                                                         
#>                                                                                 
#> # window functions are useful for grouped mutates                               
#> mtcars %>%                                                                      
#>   group_by(cyl) %>%                                                             
#>   mutate(rank = min_rank(desc(mpg)))                                            

See Also

themes, simple_theme().

Description

These helpers provide useful wrappers around cat(): most importantly they all set sep = "", and cat_line() automatically adds a newline.

Usage

cat_line(..., col = NULL, background_col = NULL, file = stdout())

cat_bullet(
  ...,
  col = NULL,
  background_col = NULL,
  bullet = "bullet",
  bullet_col = NULL,
  file = stdout()
)

cat_boxx(..., file = stdout())

cat_rule(..., file = stdout())

cat_print(x, file = "")

Arguments

Examples

cat_line("This is ", "a ", "line of text.", col = "red")
cat_bullet(letters[1:5])
cat_bullet(letters[1:5], bullet = "tick", bullet_col = "green")
cat_rule()

Description

cli() will record all ⁠cli_*⁠ calls in expr, and emit them together in a single message. This is useful if you want to built a larger piece of output from multiple ⁠cli_*⁠ calls.

Usage

cli(expr)

Arguments

Details

Use this function to build a more complex piece of CLI that would not make sense to show in pieces.

cli({
  cli_h1("Title")
  cli_h2("Subtitle")
  cli_ul(c("this", "that", "end"))
})

#>                                                                                 
#> ── Title ─────────────────────────────────────────────────────────────          
#>                                                                                 
#> ── Subtitle ──                                                                  
#>                                                                                 
#> • this                                                                          
#> • that                                                                          
#> • end                                                                           

Value

Nothing.

Description

These functions let you create error, warning or diagnostic messages with cli formatting, including inline styling, pluralization and glue substitutions.

Usage

cli_abort(
  message,
  ...,
  call = .envir,
  .envir = parent.frame(),
  .frame = .envir
)

cli_warn(message, ..., .envir = parent.frame())

cli_inform(message, ..., .envir = parent.frame())

Arguments

Details

n <- "boo"
cli_abort(c(
        "{.var n} must be a numeric vector",
  "x" = "You've supplied a {.cls {class(n)}} vector."
))

#> Error:                                                                          
#> ! `n` must be a numeric vector                                                  
#> ✖ You've supplied a <character> vector.                                         
#> Run `rlang::last_error()` to see where the error occurred.                      

len <- 26
idx <- 100
cli_abort(c(
        "Must index an existing element:",
  "i" = "There {?is/are} {len} element{?s}.",
  "x" = "You've tried to subset element {idx}."
))

#> Error:                                                                          
#> ! Must index an existing element:                                               
#> ℹ There are 26 elements.                                                        
#> ✖ You've tried to subset element 100.                                           
#> Run `rlang::last_error()` to see where the error occurred.                      

See Also

These functions support inline markup.

Other functions supporting inline markup: cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Alerts are typically short status messages.

Usage

cli_alert(text, id = NULL, class = NULL, wrap = FALSE, .envir = parent.frame())

cli_alert_success(
  text,
  id = NULL,
  class = NULL,
  wrap = FALSE,
  .envir = parent.frame()
)

cli_alert_danger(
  text,
  id = NULL,
  class = NULL,
  wrap = FALSE,
  .envir = parent.frame()
)

cli_alert_warning(
  text,
  id = NULL,
  class = NULL,
  wrap = FALSE,
  .envir = parent.frame()
)

cli_alert_info(
  text,
  id = NULL,
  class = NULL,
  wrap = FALSE,
  .envir = parent.frame()
)

Arguments

Details

Success

nbld <- 11
tbld <- prettyunits::pretty_sec(5.6)
cli_alert_success("Built {.emph {nbld}} status report{?s} in {tbld}.")

#> ✔ Built 11 status reports in 5.6s.                                              

Info

cfl <- "~/.cache/files/latest.cache"
cli_alert_info("Updating cache file {.path {cfl}}.")

#> ℹ Updating cache file ~/.cache/files/latest.cache.                              

Warning

cfl <- "~/.cache/files/latest.cache"
cli_alert_warning("Failed to update cache file {.path {cfl}}.")

#> ! Failed to update cache file ~/.cache/files/latest.cache.                      

Danger

cfl <- "~/.config/report.yaml"
cli_alert_danger("Cannot validate config file at {.path {cfl}}.")

#> ✖ Cannot validate config file at ~/.config/report.yaml.                         

Text wrapping

Alerts are printed without wrapping, unless you set wrap = TRUE:

cli_alert_info("Data columns: {.val {names(mtcars)}}.")
cli_alert_info("Data columns: {.val {names(mtcars)}}.", wrap = TRUE)

#> ℹ Data columns: "mpg", "cyl", "disp", "hp", "drat", "wt", "qsec", "vs", "am", "g
#> ear", and "carb".                                                               
#> ℹ Data columns: "mpg", "cyl", "disp", "hp", "drat", "wt", "qsec",               
#> "vs", "am", "gear", and "carb".                                                 

See Also

These functions supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

A section that is quoted from another source. It is typically indented.

Usage

cli_blockquote(
  quote,
  citation = NULL,
  id = NULL,
  class = NULL,
  .envir = parent.frame()
)

Arguments

Details

evil <- paste(
  "The real problem is that programmers have spent far too much time",
  "worrying about efficiency in the wrong places and at the wrong",
  "times; premature optimization is the root of all evil (or at least",
  "most of it) in programming.")
cli_blockquote(evil, citation = "Donald Ervin Knuth")

#>                                                                                 
#>     “The real problem is that programmers have spent far                        
#>     too much time worrying about efficiency in the wrong                        
#>     places and at the wrong times; premature optimization                       
#>     is the root of all evil (or at least most of it) in                         
#>     programming.”                                                               
#>     — Donald Ervin Knuth                                                        
#>                                                                                 

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

It is often useful to print out a list of items, tasks a function or package performs, or a list of notes.

Usage

cli_bullets(text, id = NULL, class = NULL, .envir = parent.frame())

Arguments

Details

Items may be formatted differently, e.g. they can have a prefix symbol. Formatting is specified by the names of text, and can be themed. cli creates a div element of class bullets for the whole bullet list. Each item is another div element of class ⁠bullet-<name>⁠, where ⁠<name>⁠ is the name of the entry in text. Entries in text without a name create a div element of class bullet-empty, and if the name is a single space character, the class is bullet-space.

The built-in theme defines the following item types:

• No name: Item without a prefix.

• ⁠ ⁠: Indented item.

• *: Item with a bullet.

• >: Item with an arrow or pointer.

• v: Item with a green "tick" symbol, like cli_alert_success().

• x: Item with a ref cross, like cli_alert_danger().

• !: Item with a yellow exclamation mark, like cli_alert_warning().

• i: Info item, like cli_alert_info().

You can define new item type by simply defining theming for the corresponding ⁠bullet-<name>⁠ classes.

cli_bullets(c(
        "noindent",
  " " = "indent",
  "*" = "bullet",
  ">" = "arrow",
  "v" = "success",
  "x" = "danger",
  "!" = "warning",
  "i" = "info"
))

#> noindent                                                                        
#>   indent                                                                        
#> • bullet                                                                        
#> → arrow                                                                         
#> ✔ success                                                                       
#> ✖ danger                                                                        
#> ! warning                                                                       
#> ℹ info                                                                          

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

cli_format_bullets_raw() is similar to cli_bullets(), but it does not perform any inline styling or glue substitutions in the input.

Usage

cli_bullets_raw(text, id = NULL, class = NULL)

format_bullets_raw(text, id = NULL, class = NULL)

Arguments

Details

format_bullets_raw() returns the output instead of printing it.

See Also

These functions support inline markup.

See cli_bullets() for examples.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

A helper function that creates a div with class code and then calls cli_verbatim() to output code lines. The builtin theme formats these containers specially. In particular, it adds syntax highlighting to valid R code.

Usage

cli_code(
  lines = NULL,
  ...,
  language = "R",
  .auto_close = TRUE,
  .envir = environment()
)

Arguments

Details

myfun <- function() {
  message("Just an example function")
  graphics::pairs(iris, col = 1:4)
}
cli_code(format(myfun))

#> function ()                                                                     
#> {                                                                               
#>     message("Just an example function")                                         
#>     graphics::pairs(iris, col = 1:4)                                            
#> }                                                                               

Value

The id of the container that contains the code.

Description

Return the current state of a cli app. It includes the currently open tags, their ids, classes and their computed styles.

Usage

cli_debug_doc(app = default_app() %||% start_app())

Arguments

Details

The returned data frame has a print method, and if you want to create a plain data frame from it, index it with an empty bracket: cli_debug_doc()[].

To see all currently active themes, use app$themes, e.g. for the default app: default_app()$themes.

Value

Data frame with columns: tag, id, class (space separated), theme (id of the theme the element added), styles (computed styles for the element).

See Also

cli_sitrep(). To debug containers, you can set the CLI-DEBUG_BAD_END environment variable to true, and then cli will warn when it cannot find the specified container to close (or any contained at all).

Examples

## Not run: 
cli_debug_doc()

olid <- cli_ol()
cli_li()
cli_debug_doc()
cli_debug_doc()[]

cli_end(olid)
cli_debug_doc()

## End(Not run)

Description

See containers. A cli_div container is special, because it may add new themes, that are valid within the container.

Usage

cli_div(
  id = NULL,
  class = NULL,
  theme = NULL,
  .auto_close = TRUE,
  .envir = parent.frame()
)

Arguments

Details

Custom themes

d <- cli_div(theme = list(h1 = list(color = "cyan",
                                    "font-weight" = "bold")))
cli_h1("Custom title")
cli_end(d)

#>                                                                                 
#> Custom title                                                                    

Auto-closing

By default a cli_div() is closed automatically when the calling frame exits.

div <- function() {
  cli_div(class = "tmp", theme = list(.tmp = list(color = "yellow")))
  cli_text("This is yellow")
}
div()
cli_text("This is not yellow any more")

#> This is yellow                                                                  
#> This is not yellow any more                                                     

Value

The id of the new container element, invisibly.

Description

A definition list is a container, see containers.

Usage

cli_dl(
  items = NULL,
  labels = names(items),
  id = NULL,
  class = NULL,
  .close = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame()
)

Arguments

Details

All items at once

fun <- function() {
  cli_dl(c(foo = "one", bar = "two", baz = "three"))
}
fun()

#> foo: one                                                                        
#> bar: two                                                                        
#> baz: three                                                                      

Items one by one

fun <- function() {
  cli_dl()
  cli_li(c(foo = "{.emph one}"))
  cli_li(c(bar = "two"))
  cli_li(c(baz = "three"))
}
fun()

#> foo: one                                                                        
#> bar: two                                                                        
#> baz: three                                                                      

Value

The id of the new container element, invisibly.

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Containers aut0-close by default, but sometimes you need to explicitly close them. Closing a container also closes all of its nested containers.

Usage

cli_end(id = NULL)

Arguments

Details

Explicit closing

cnt <- cli_par()
cli_text("First paragraph.")
cli_end(cnt)
cnt <- cli_par()
cli_text("Second paragraph.")
cli_end(cnt)

#> First paragraph.                                                                
#>                                                                                 
#> Second paragraph.                                                               
#>                                                                                 

Closing a stack of containers

list <- cli_ul()
cli_li("Item one:")
cli_li("Item two:")
cli_par()
cli_text("Still item two.")
cli_end(list)
cli_text("Not in the list any more")

#> • Item one:                                                                     
#> • Item two:                                                                     
#> Still item two.                                                                 
#>                                                                                 
#> Not in the list any more                                                        

Omitting id

If id is omitted, the container that was opened last will be closed.

cli_par()
cli_text("First paragraph")
cli_end()
cli_par()
cli_text("Second paragraph")
cli_end()

#> First paragraph                                                                 
#>                                                                                 
#> Second paragraph                                                                
#>                                                                                 

Debugging containers

You can use the internal cli:::cli_debug_doc() function to see the currently open containers.

fun <- function() {
  cli_div(id = "mydiv")
  cli_par(class = "myclass")
  cli:::cli_debug_doc()
}
fun()

#> <cli document>                                                                  
#> <body id="body">                                                                
#> <div id="mydiv"> +theme                                                         
#> <par id="cli-82040-64" class="myclass">                                         

Description

Capture the output of cli functions instead of printing it

Usage

cli_fmt(expr, collapse = FALSE, strip_newline = FALSE)

Arguments

Examples

cli_fmt({
  cli_alert_info("Loading data file")
  cli_alert_success("Loaded data file")
})

Description

This function can be used directly, or via the ⁠{.val ...}⁠ inline style. ⁠{.val {expr}}⁠ calls cli_format() automatically on the value of expr, before styling and collapsing it.

Usage

cli_format(x, style = NULL, ...)

## Default S3 method:
cli_format(x, style = NULL, ...)

## S3 method for class 'character'
cli_format(x, style = NULL, ...)

## S3 method for class 'numeric'
cli_format(x, style = NULL, ...)

Arguments

Details

Default style

months <- month.name[1:3]
cli_text("{.val {months}}")

#> "January", "February", and "March"                                              

nums <- 1:5 / 7
cli_text("{.val {nums}}")

#> 0.142857142857143, 0.285714285714286, 0.428571428571429,                        
#> 0.571428571428571, and 0.714285714285714                                        

Styling with themes

nums <- 1:5 / 7
divid <- cli_div(theme = list(.val = list(digits = 3)))
cli_text("{.val {nums}}")
cli_end(divid)

#> 0.143, 0.286, 0.429, 0.571, and 0.714                                           

It is possible to define new S3 methods for cli_format and then these will be used automatically for ⁠{.val ...}⁠ expressions.

cli_format.month <- function(x, style = NULL, ...) {
  x <- encodeString(substr(x, 1, 3), quote = "\"")
  NextMethod("cli_format")
}
registerS3method("cli_format", "month", cli_format.month)
months <- structure(month.name[1:3], class = "month")
cli_text("{.val {months}}")

#> "Jan", "Feb", and "Mar"                                                         

See Also

cli_vec()

Description

This method can be typically used in format() S3 methods. Then the print() method of the class can be easily defined in terms of such a format() method. See examples below.

Usage

cli_format_method(expr, theme = getOption("cli.theme"))

Arguments

Value

Character vector, one element for each line of the printout.

Examples

# Let's create format and print methods for a new S3 class that
# represents the an installed R package: `r_package`

# An `r_package` will contain the DESCRIPTION metadata of the package
# and also its installation path.
new_r_package <- function(pkg) {
  tryCatch(
    desc <- packageDescription(pkg),
    warning = function(e) stop("Cannot find R package `", pkg, "`")
  )
  file <- dirname(attr(desc, "file"))
  if (basename(file) != pkg) file <- dirname(file)
  structure(
    list(desc = unclass(desc), lib = dirname(file)),
    class = "r_package"
  )
}

format.r_package <- function(x, ...) {
  cli_format_method({
    cli_h1("{.pkg {x$desc$Package}} {cli::symbol$line} {x$desc$Title}")
    cli_text("{x$desc$Description}")
    cli_ul(c(
      "Version: {x$desc$Version}",
      if (!is.null(x$desc$Maintainer)) "Maintainer: {x$desc$Maintainer}",
      "License: {x$desc$License}"
    ))
    if (!is.na(x$desc$URL)) cli_text("See more at {.url {x$desc$URL}}")
  })
}

# Now the print method is easy:
print.r_package <- function(x, ...) {
  cat(format(x, ...), sep = "\n")
}

# Try it out
new_r_package("cli")

# The formatting of the output depends on the current theme:
opt <- options(cli.theme = simple_theme())
print(new_r_package("cli"))
options(opt)  # <- restore theme

Description

cli has three levels of headings.

Usage

cli_h1(text, id = NULL, class = NULL, .envir = parent.frame())

cli_h2(text, id = NULL, class = NULL, .envir = parent.frame())

cli_h3(text, id = NULL, class = NULL, .envir = parent.frame())

Arguments

Details

This is how the headings look with the default builtin theme.

cli_h1("Header {.emph 1}")
cli_h2("Header {.emph 2}")
cli_h3("Header {.emph 3}")

#>                                                                                 
#> ── Header 1 ──────────────────────────────────────────────────────────          
#>                                                                                 
#> ── Header 2 ──                                                                  
#>                                                                                 
#> ── Header 3                                                                     

See Also

These functions supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

A list item is a container, see containers.

Usage

cli_li(
  items = NULL,
  labels = names(items),
  id = NULL,
  class = NULL,
  .auto_close = TRUE,
  .envir = parent.frame()
)

Arguments

Details

Nested lists

fun <- function() {
  ul <- cli_ul()
  cli_li("one:")
  cli_ol(letters[1:3])
  cli_li("two:")
  cli_li("three")
  cli_end(ul)
}
fun()

#> • one:                                                                          
#>   1. a                                                                          
#>   2. b                                                                          
#>   3. c                                                                          
#> • two:                                                                          
#> • three                                                                         

Value

The id of the new container element, invisibly.

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

If there is no active app, then it calls start_app().

Usage

cli_list_themes()

Value

A list of data frames with the active themes. Each data frame row is a style that applies to selected CLI tree nodes. Each data frame has columns:

• selector: The original CSS-like selector string. See themes.

• parsed: The parsed selector, as used by cli for matching to nodes.

• style: The original style.

• cnt: The id of the container the style is currently applied to, or NA if the style is not used.

See Also

themes

Description

An ordered list is a container, see containers.

Usage

cli_ol(
  items = NULL,
  id = NULL,
  class = NULL,
  .close = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame()
)

Arguments

Details

Adding all items at once

fun <- function() {
  cli_ol(c("one", "two", "three"))
}
fun()

#> 1. one                                                                          
#> 2. two                                                                          
#> 3. three                                                                        

Adding items one by one

## Adding items one by one
fun <- function() {
  cli_ol()
  cli_li("{.emph one}")
  cli_li("{.emph two}")
  cli_li("{.emph three}")
  cli_end()
}
fun()

#> 1. one                                                                          
#> 2. two                                                                          
#> 3. three                                                                        

Nested lists

fun <- function() {
  cli_div(theme = list(ol = list("margin-left" = 2)))
  cli_ul()
  cli_li("one")
  cli_ol(c("foo", "bar", "foobar"))
  cli_li("two")
  cli_end()
  cli_end()
}
fun()

#> • one                                                                           
#>     1. foo                                                                      
#>     2. bar                                                                      
#>     3. foobar                                                                   
#> • two                                                                           

Value

The id of the new container element, invisibly.

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Note that this only refers to the current R process. If the output is produced in another process, then it is not relevant.

Usage

cli_output_connection()

Details

In interactive sessions the standard output is chosen, otherwise the standard error is used. This is to avoid painting output messages red in the R GUIs.

Value

Connection object.

Description

The builtin theme leaves an empty line between paragraphs. See also containers.

Usage

cli_par(id = NULL, class = NULL, .auto_close = TRUE, .envir = parent.frame())

Arguments

Details

clifun <- function() {
  cli_par()
  cli_text(cli:::lorem_ipsum())
}
clifun()
clifun()

#> Sunt anim ullamco Lorem qui mollit anim est in deserunt adipisicing.            
#> Enim deserunt laborum ad qui qui. Anim esse non anim magna Lorem                
#> consequat dolore labore cupidatat magna et. Esse nulla eiusmod Lorem            
#> exercitation cupidatat velit enim exercitation excepteur non officia            
#> incididunt. Id laborum dolore commodo Lorem esse ea sint proident.              
#>                                                                                 
#> Fugiat mollit in Lorem velit qui exercitation ipsum consectetur ad              
#> nisi ut eu do ullamco. Mollit officia reprehenderit culpa Lorem est             
#> reprehenderit excepteur enim magna incididunt ea. Irure nisi ad                 
#> exercitation deserunt enim anim excepteur quis minim laboris veniam             
#> nulla pariatur. Enim irure aute nulla irure qui non. Minim velit                
#> proident sunt sint. Proident sit occaecat ex aute.                              
#>                                                                                 

Value

The id of the new container element, invisibly.

Description

The ⁠cli_process_*()⁠ functions are superseded by the cli_progress_message() and cli_progress_step() functions, because they have a better default behavior.

Typically you call cli_process_start() to start the process, and then cli_process_done() when it is done. If an error happens before cli_process_done() is called, then cli automatically shows the message for unsuccessful termination.

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

Details

If you handle the errors of the process or computation, then you can do the opposite: call cli_process_start() with on_exit = "done", and in the error handler call cli_process_failed(). cli will automatically call cli_process_done() on successful termination, when the calling function finishes.

See examples below.

Value

Id of the status bar container.

See Also

This function supports inline markup.

The cli_progress_message() and cli_progress_step() functions, for a superior API.

Other status bar: cli_status(), cli_status_clear(), cli_status_update()

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

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()

Description

Note that this function is currently experimental!

Use cli_progress_along() in a mapping function or in a for loop, to add a progress bar. It uses cli_progress_bar() internally.

Usage

cli_progress_along(
  x,
  name = NULL,
  total = length(x),
  ...,
  .envir = parent.frame()
)

Arguments

Details

for loop

A for loop with cli_progress_along() looks like this:

for (i in cli_progress_along(seq)) {
  ...
}

A complete example:

clifun <- function() {
  for (i in cli_progress_along(1:100, "Downloading")) {
     Sys.sleep(4/100)
  }
}
clifun()

lapply() and other mapping functions

They will look like this:

lapply(cli_progress_along(X), function(i) ...)

A complete example:

res <- lapply(cli_progress_along(1:100, "Downloading"), function(i) {
  Sys.sleep(4/100)
})

Custom format string

clifun <- function() {
  for (i in cli_progress_along(1:100,
      format = "Downloading data file {cli::pb_current}")) {
     Sys.sleep(4/100)
  }
}
clifun()

Breaking out of loops

Note that if you use break in the for loop, you probably want to terminate the progress bar explicitly when breaking out of the loop, or right after the loop:

for (i in cli_progress_along(seq)) {
  ...
  if (cond) cli_progress_done() && break
  ...
}

Value

An index vector from 1 to length(x) that triggers progress updates as you iterate over it.

See Also

This function supports inline markup.

cli_progress_bar() and the traditional progress bar API.

Other progress bar functions: cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

This is the reference manual of the three functions that create, update and terminate progress bars. For a tutorial see the cli progress bars.

cli_progress_bar() creates a new progress bar.

cli_progress_update() updates the state of a progress bar, and potentially the display as well.

cli_progress_done() terminates a progress bar.

Usage

cli_progress_bar(
  name = NULL,
  status = NULL,
  type = c("iterator", "tasks", "download", "custom"),
  total = NA,
  format = NULL,
  format_done = NULL,
  format_failed = NULL,
  clear = getOption("cli.progress_clear", TRUE),
  current = TRUE,
  auto_terminate = type != "download",
  extra = NULL,
  .auto_close = TRUE,
  .envir = parent.frame()
)

cli_progress_update(
  inc = NULL,
  set = NULL,
  total = NULL,
  status = NULL,
  extra = NULL,
  id = NULL,
  force = FALSE,
  .envir = parent.frame()
)

cli_progress_done(id = NULL, .envir = parent.frame(), result = "done")

Arguments

Details

Basic usage

cli_progress_bar() creates a progress bar, cli_progress_update() updates an existing progress bar, and cli_progress_done() terminates it.

It is good practice to always set the name argument, to make the progress bar more informative.

clean <- function() {
  cli_progress_bar("Cleaning data", total = 100)
  for (i in 1:100) {
    Sys.sleep(5/100)
    cli_progress_update()
  }
  cli_progress_done()
}
clean()

Progress bar types

There are three builtin types of progress bars, and a custom type.

tasks <- function() {
  cli_progress_bar("Tasks", total = 3, type = "tasks")
  for (i in 1:3) {
    Sys.sleep(1)
    cli_progress_update()
  }
  cli_progress_done()
}
tasks()

Unknown total

If total is not known, then cli shows a different progress bar. Note that you can also set total in cli_progress_update(), if it not known when the progress bar is created, but you learn it later.

nototal <- function() {
  cli_progress_bar("Parameter tuning")
  for (i in 1:100) {
    Sys.sleep(3/100)
    cli_progress_update()
  }
  cli_progress_done()
}
nototal()

Clearing the progress bar

By default cli removes terminated progress bars from the screen, if the terminal supports this. If you want to change this, use the clear argument of cli_progress_bar(), or the cli.progress_clear global option (see cli-config) to change this.

(In the cli documentation we usually set cli.progress_clear to FALSE, so users can see how finished progress bars look.)

In this example the first progress bar is cleared, the second is not.

fun <- function() {
  cli_progress_bar("Data cleaning", total = 100, clear = TRUE)
  for (i in 1:100) {
    Sys.sleep(3/100)
    cli_progress_update()
  }
  cli_progress_bar("Parameter tuning", total = 100, clear = FALSE)
  for (i in 1:100) {
    Sys.sleep(3/100)
    cli_progress_update()
  }
}
fun()

Initial delay

Updating a progress bar on the screen is costly, so cli tries to avoid it for quick loops. By default a progress bar is only shown after two seconds, or after half of that if less than 50% of the iterations are complete. You can change the two second default with the cli.progress_show_after global option (see cli-config).

(In the cli documentation we usually set cli.progress_show_after to 0 (zero seconds), so progress bars are shown immediately.)

In this example we only show the progress bar after one second, because more than 50% of the iterations remain after one second.

fun <- function() {
  cli_alert("Starting now, at {Sys.time()}")
  cli_progress_bar(
    total = 100,
    format = "{cli::pb_bar} {pb_percent} @ {Sys.time()}"
  )
  for (i in 1:100) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
}
options(cli.progress_show_after = 2)
fun()

The current progress bar

By default cli sets the new progress bar as the current progress bar of the calling function. The current progress bar is the default one in cli progress bar operations. E.g. if no progress bar id is supplied in cli_progress_update(), then the current progress bar is updated.

Every function can only have a single current progress bar, and if a new one is created, then the previous one (if any) is automatically terminated. The current progress bar is also terminated when the function that created it exits. Thanks to these rules, most often you don't need to explicitly deal with progress bar ids, and you don't need to explicitly call cli_progress_done():

fun <- function() {
  cli_progress_bar("First step ", total = 100)
  for (i in 1:100) {
    Sys.sleep(2/100)
    cli_progress_update()
  }
  cli_progress_bar("Second step", total = 100)
  for (i in 1:100) {
    Sys.sleep(2/100)
    cli_progress_update()
  }
}
fun()

cli output while the progress bar is active

cli allows emitting regular cli output (alerts, headers, lists, etc.) while a progress bar is active. On terminals that support this, cli will remove the progress bar temporarily, emit the output, and then restores the progress bar.

fun <- function() {
  cli_alert_info("Before the progress bar")
  cli_progress_bar("Calculating", total = 100)
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_alert_info("Already half way!")
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_alert_info("All done")
}
fun()

See also cli_progress_output(), which sends text for the current progress handler. E.g. in a Shiny app it will send the output to the Shiny progress bar, as opposed to the cli_alert() etc. cli functions which will print the text to the console.

Custom formats

In addition to the builtin types, you can also specify a custom format string. In this case progress variables are probably useful to avoid calculating some progress bar quantities like the elapsed time, of the ETA manually. You can also use your own variables in the calling function:

fun <- function(urls) {
  cli_progress_bar(
    format = paste0(
      "{pb_spin} Downloading {.path {basename(url)}} ",
      "[{pb_current}/{pb_total}]   ETA:{pb_eta}"
    ),
    format_done = paste0(
      "{col_green(symbol$tick)} Downloaded {pb_total} files ",
      "in {pb_elapsed}."
    ),,
    total = length(urls)
  )
  for (url in urls) {
    cli_progress_update()
    Sys.sleep(5/10)
  }
}
fun(paste0("https://acme.com/data-", 1:10, ".zip"))

Value

cli_progress_bar() returns the id of the new progress bar. The id is a string constant.

cli_progress_update() returns the id of the progress bar, invisibly.

cli_progress_done() returns TRUE, invisibly, always.

See Also

These functions support inline markup.

cli_progress_message() and cli_progress_step() for simpler progress messages.

Other progress bar functions: cli_progress_along(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

The progress handler(s) to use can be selected with global options.

Usage

cli_progress_builtin_handlers()

Details

There are three options that specify which handlers will be selected, but most of the time you only need to use one of them. You can set these options to a character vector, the names of the built-in cli handlers you want to use:

• If cli.progress_handlers_only is set, then these handlers are used, without considering others and without checking if they are able to handle a progress bar. This option is mainly intended for testing purposes.

• The handlers named in cli.progress_handlers are checked if they are able to handle the progress bar, and from the ones that are, the first one is selected. This is usually the option that the end use would want to set.

• The handlers named in cli.progress_handlers_force are always appended to the ones selected via cli.progress_handlers. This option is useful to add an additional handler, e.g. a logger that writes to a file.

Value

cli_progress_builtin_handlers() returns the names of the currently supported progress handlers.

The built-in progress handlers

cli

Use cli's internal status bar, the last line of the screen, to show the progress bar. This handler is always able to handle all progress bars.

logger

Log progress updates to the screen, with one line for each update and with time stamps. This handler is always able to handle all progress bars.

progressr

Use the progressr package to create progress bars. This handler is always able to handle all progress bars. (The progressr package needs to be installed.)

rstudio

Use RStudio's job panel to show the progress bars. This handler is available at the RStudio console, in recent versions of RStudio.

say

Use the macOS say command to announce progress events in speech (type ⁠man say⁠ on a terminal for more info). Set the cli.progress_say_frequency option to set the minimum delay between say invocations, the default is three seconds. This handler is available on macOS, if the say command is on the path.

The external command and its arguments can be configured with options:

• cli_progress_say_args: command line arguments, e.g. you can use this to select a voice on macOS,

• cli_progress_say_command: external command to run,

• cli_progress_say_frequency: wait at least this many seconds between calling the external command.

shiny

Use shiny's progress bars. This handler is available if a shiny app is running.

See Also

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

Description

Useful for experimenting with format strings and for documentation. It creates a progress bar, iterates it until it terminates and saves the progress updates.

Usage

cli_progress_demo(
  name = NULL,
  status = NULL,
  type = c("iterator", "tasks", "download", "custom"),
  total = NA,
  .envir = parent.frame(),
  ...,
  at = if (is_interactive()) NULL else 50,
  show_after = 0,
  live = NULL,
  delay = 0,
  start = as.difftime(5, units = "secs")
)

Arguments

Value

List with class cli_progress_demo, which has a print and a format method for pretty printing. The lines entry contains the output lines, each corresponding to one update.

Description

This is a simplified progress bar, a single (dynamic) message, without progress units.

Usage

cli_progress_message(
  msg,
  current = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame(),
  ...
)

Arguments

Details

cli_progress_message() always shows the message, even if no update is due. When the progress message is terminated, it is removed from the screen by default.

Note that the message can be dynamic: if you update it with cli_progress_update(), then cli uses the current values in the string substitutions.

fun <- function() {
  cli_progress_message("Task one is running...")
  Sys.sleep(2)

  cli_progress_message("Task two is running...")
  Sys.sleep(2)

  step <- 1L
  cli_progress_message("Task three is underway: step {step}")
  for (step in 1:5) {
    Sys.sleep(0.5)
    cli_progress_update()
  }
}
fun()

Value

The id of the new progress bar.

See Also

This function supports inline markup.

cli_progress_bar() for the complete progress bar API. cli_progress_step() for a similar display that is styled by default.

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_num(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Progress bar utility functions.

Usage

cli_progress_num()

cli_progress_cleanup()

Details

cli_progress_num() returns the number of currently active progress bars. (These do not currently include the progress bars created in C/C++ code.)

cli_progress_cleanup() terminates all active progress bars. (It currently ignores progress bars created in the C/C++ code.)

Value

cli_progress_num() returns an integer scalar.

'cli_progress_cleanup() does not return anything.

See Also

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

Description

The text is calculated via cli_text(), so all cli features can be used here, including progress variables.

Usage

cli_progress_output(text, id = NULL, .envir = parent.frame())

Arguments

Details

The text is passed to the progress handler(s), that may or may not be able to print it.

fun <- function() {
  cli_alert_info("Before the progress bar")
  cli_progress_bar("Calculating", total = 100)
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_progress_output("Already half way!")
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_alert_info("All done")
}
fun()

Value

TRUE, always.

See Also

This function supports inline markup.

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_step(), cli_progress_styles(), progress-variables

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

This is a simplified progress bar, a single (dynamic) message, without progress units.

Usage

cli_progress_step(
  msg,
  msg_done = msg,
  msg_failed = msg,
  spinner = FALSE,
  class = if (!spinner) ".alert-info",
  current = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame(),
  ...
)

Arguments

Details

cli_progress_step() always shows the progress message, even if no update is due.

Basic use

f <- function() {
  cli_progress_step("Downloading data")
  Sys.sleep(2)
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model")
  Sys.sleep(3)
}
f()

Spinner

You can add a spinner to some or all steps with spinner = TRUE, but note that this will only work if you call cli_progress_update() regularly.

f <- function() {
  cli_progress_step("Downloading data", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(2/100); cli_progress_update() }
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(3/100); cli_progress_update() }
}
f()

Dynamic messages

You can make the step messages dynamic, using glue templates. Since cli_progress_step() show that message immediately, we need to initialize msg first.

f <- function() {
  msg <- ""
  cli_progress_step("Downloading data{msg}", spinner = TRUE)
  for (i in 1:100) {
    Sys.sleep(2/100)
    msg <- glue::glue(", got file {i}/100")
    cli_progress_update()
  }
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(3/100); cli_progress_update() }
}
f()

Termination messages

You can specify a different message for successful and/or unsuccessful termination:

f <- function() {
  size <- 0L
  cli_progress_step(
    "Downloading data.",
    msg_done = "Downloaded {prettyunits::pretty_bytes(size)}.",
    spinner = TRUE
  )
  for (i in 1:100) {
    Sys.sleep(3/100)
    size <- size + 8192
    cli_progress_update()
  }
}
f()

See Also

This function supports inline markup.

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_styles(), progress-variables

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

The following options are used to select a style:

• cli_progress_bar_style

• cli_progress_bar_style_ascii

• cli_progress_bar_style_unicode

Usage

cli_progress_styles()

Details

On Unicode terminals (if is_utf8_output() is TRUE), the cli_progress_bar_style_unicode and cli_progress_bar_style options are used.

On ASCII terminals (if is_utf8_output() is FALSE), the cli_pgoress_bar_style_ascii and cli_progress_bar_style options are are used.

for (style in names(cli_progress_styles())) {
  options(cli.progress_bar_style = style)
  label <- ansi_align(paste0("Style '", style, "'"), 20)
  print(cli_progress_demo(label, live = FALSE, at = 66, total = 100))
}
options(cli.progress_var_style = NULL)

#> Style 'classic'      #####################             66% | ETA:  3s           
#> Style 'squares'      ■■■■■■■■■■■■■■■■■■■■■             66% | ETA:  3s           
#> Style 'dot'          ────────────────────●──────────   66% | ETA:  3s           
#> Style 'fillsquares'  ■■■■■■■■■■■■■■■■■■■■■□□□□□□□□□□   66% | ETA:  3s           
#> Style 'bar'          ███████████████████████████████   66% | ETA:  3s           

Value

A named list with sublists containing elements complete, incomplete and potentially current.

See Also

Other progress bar functions: cli_progress_along(), cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_step(), progress-variables

Description

It can be used to separate parts of the output.

Usage

cli_rule(
  left = "",
  center = "",
  right = "",
  id = NULL,
  .envir = parent.frame()
)

Arguments

Details

Inline styling and interpolation

pkg <- "mypackage"
cli_rule(left = "{.pkg {pkg}} results")

#> ── mypackage results ─────────────────────────────────────────────────          

Theming

The line style of the rule can be changed via the the line-type property. Possible values are:

• "single": (same as 1), a single line,

• "double": (same as 2), a double line,

• "bar1", "bar2", "bar3", etc., "bar8" uses varying height bars.

Colors and background colors can similarly changed via a theme.

d <- cli_div(theme = list(rule = list(
  color = "cyan",
  "line-type" = "double")))
cli_rule("Summary", right = "{.pkg mypackage}")
cli_end(d)

#> ══ Summary ══════════════════════════════════════════════ mypackage ══          

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Contains currently:

• cli_unicode_option: whether the cli.unicode option is set and its value. See is_utf8_output().

• symbol_charset: the selected character set for symbol, UTF-8, Windows, or ASCII.

• console_utf8: whether the console supports UTF-8. See base::l10n_info().

• latex_active: whether we are inside knitr, creating a LaTeX document.

• num_colors: number of ANSI colors. See num_ansi_colors().

• console_with: detected console width.

Usage

cli_sitrep()

Value

Named list with entries listed above. It has a cli_sitrep class, with a print() and format() method.

Examples

cli_sitrep()

Description

The ⁠cli_status_*()⁠ functions are superseded by the cli_progress_message() and cli_progress_step() functions, because they have a better default behavior.

The status bar is the last line of the terminal. cli apps can use this to show status information, progress bars, etc. The status bar is kept intact by all semantic cli output.

Usage

cli_status(
  msg,
  msg_done = paste(msg, "... done"),
  msg_failed = paste(msg, "... failed"),
  .keep = FALSE,
  .auto_close = TRUE,
  .envir = parent.frame(),
  .auto_result = c("clear", "done", "failed", "auto")
)

Arguments

Details

Use cli_status_clear() to clear the status bar.

Often status messages are associated with processes. E.g. the app starts downloading a large file, so it sets the status bar accordingly. Once the download is done (or has failed), the app typically updates the status bar again. cli automates much of this, via the msg_done, msg_failed, and .auto_result arguments. See examples below.

Value

The id of the new status bar container element, invisibly.

See Also

Status bars support inline markup.

The cli_progress_message() and cli_progress_step() functions, for a superior API.

Other status bar: cli_process_start(), cli_status_clear(), cli_status_update()

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

Description

The ⁠cli_status_*()⁠ functions are superseded by the cli_progress_message() and cli_progress_step() functions, because they have a better default behavior.

Clear the status bar

Usage

cli_status_clear(
  id = NULL,
  result = c("clear", "done", "failed"),
  msg_done = NULL,
  msg_failed = NULL,
  .envir = parent.frame()
)

Arguments

See Also

The cli_progress_message() and cli_progress_step() functions, for a superior API.

Other status bar: cli_process_start(), cli_status(), cli_status_update()

Description

The ⁠cli_status_*()⁠ functions are superseded by the cli_progress_message() and cli_progress_step() functions, because they have a better default behavior.

Update the status bar

Usage

cli_status_update(
  id = NULL,
  msg = NULL,
  msg_done = NULL,
  msg_failed = NULL,
  .envir = parent.frame()
)

Arguments

Value

Id of the status bar container.

See Also

This function supports inline markup.

The cli_progress_message() and cli_progress_step() functions, for a superior API.

Other status bar: cli_process_start(), cli_status(), cli_status_clear()

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_text(), cli_ul(), format_error(), format_inline()

Description

Write some text to the screen. This function is most appropriate for longer paragraphs. See cli_alert() for shorter status messages.

Usage

cli_text(..., .envir = parent.frame())

Arguments

Details

Text wrapping

Text is wrapped to the console width, see console_width().

cli_text(cli:::lorem_ipsum())

#> Lorem ad ipsum veniam esse nisi deserunt duis. Qui incididunt elit              
#> elit mollit sint nulla consectetur aute commodo do elit laboris minim           
#> et. Laboris ipsum mollit voluptate et non do incididunt eiusmod. Anim           
#> consectetur mollit laborum occaecat eiusmod excepteur. Ullamco non              
#> tempor esse anim tempor magna non.                                              

New lines

A cli_text() call always appends a newline character to the end.

cli_text("First line.")
cli_text("Second line.")

#> First line.                                                                     
#> Second line.                                                                    

Styling

You can use inline markup, as usual.

cli_text("The {.fn cli_text} function in the {.pkg cli} package.")

#> The `cli_text()` function in the cli package.                                   

Interpolation

String interpolation via glue works as usual. Interpolated vectors are collapsed.

pos <- c(5, 14, 25, 26)
cli_text("We have {length(pos)} missing measurements: {pos}.")

#> We have 4 missing measurements: 5, 14, 25, and 26.                              

Styling and interpolation

Use double braces to combine styling and string interpolation.

fun <- "cli-text"
pkg <- "cli"
cli_text("The {.fn {fun}} function in the {.pkg {pkg}} package.")

#> The `cli-text()` function in the cli package.                                   

Multiple arguments

Arguments are concatenated.

cli_text(c("This ", "will ", "all "), "be ", "one ", "sentence.")

#> This will all be one sentence.                                                  

Containers

You can use cli_text() within cli containers.

ul <- cli_ul()
cli_li("First item.")
cli_text("Still the {.emph first} item")
cli_li("Second item.")
cli_text("Still the {.emph second} item")
cli_end(ul)

#> • First item.                                                                   
#> Still the first item                                                            
#> • Second item.                                                                  
#> Still the second item                                                           

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_ul(), format_error(), format_inline()

Description

An unordered list is a container, see containers.

Usage

cli_ul(
  items = NULL,
  id = NULL,
  class = NULL,
  .close = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame()
)

Arguments

Details

Adding all items at once

fun <- function() {
  cli_ul(c("one", "two", "three"))
}
fun()

#> • one                                                                           
#> • two                                                                           
#> • three                                                                         

Adding items one by one

fun <- function() {
  cli_ul()
  cli_li("{.emph one}")
  cli_li("{.emph two}")
  cli_li("{.emph three}")
  cli_end()
}
fun()

#> • one                                                                           
#> • two                                                                           
#> • three                                                                         

Value

The id of the new container element, invisibly.

See Also

This function supports inline markup.

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), format_error(), format_inline()

Description

Add custom cli style to a vector

Usage

cli_vec(x, style = list())

Arguments

Details

You can use this function to change the default parameters of collapsing the vector into a string, see an example below.

The style is added as an attribute, so operations that remove attributes will remove the style as well.

Custom collapsing separator

v <- cli_vec(
  c("foo", "bar", "foobar"),
  style = list("vec-sep" = " & ", "vec-last" = " & ")
)
cli_text("My list: {v}.")

#> My list: foo & bar & foobar.                                                    

Custom truncation

x <- cli_vec(names(mtcars), list("vec-trunc" = 3))
cli_text("Column names: {x}.")

#> Column names: mpg, cyl, disp, …, gear, and carb.                                

See Also

cli_format()

Description

It is not wrapped, but printed as is. Long lines will overflow. No glue substitution is performed on verbatim text.

Usage

cli_verbatim(..., .envir = parent.frame())

Arguments

Details

Line breaks

cli_verbatim("This has\nthree\nlines,")

#> This has                                                                        
#> three                                                                           
#> lines,                                                                          

Special characters

No glue substitution happens here.

cli_verbatim("No string {interpolation} or {.emph styling} here")

#> No string {interpolation} or {.emph styling} here                               

See Also

cli_code() for printing R or other source code.

Description

cli environment variables and options

User facing configuration

These are environment variables and options that uses may set, to modify the behavior of cli.

User facing environment variables

R_CLI_HYPERLINK_MODE

Set to posix to force generating POSIX compatible ANSI hyperlinks. If not set, then RStudio compatible links are generated. This is a temporary crutch until RStudio handles POSIX hyperlinks correctly, and after that it will be removed.

NO_COLOR

Set to a nonempty value to turn off ANSI colors. See num_ansi_colors().

ESS_BACKGROUND_MODE

Set this environment variable to light or dark to indicate dark mode in Emacs. Once https://github.com/emacs-ess/ESS/pull/1178 is merged, ESS will set this automatically.

R_CLI_DYNAMIC

Set to true, TRUE or True to assume a dynamic terminal, that supports ⁠\r⁠. Set to anything else to assume a non-dynamic terminal. See is_dynamic_tty().

R_CLI_NUM_COLORS

Set to a positive integer to assume a given number of colors. See num_ansi_colors().

R_CLI_HYPERLINKS

Set to true, TRUE or True to tell cli that the terminal supports ANSI hyperlinks. Set to anything else to assume no hyperlink support. See style_hyperlink().

User facing options

cli.ansi

Set to true, TRUE or True to assume a terminal that supports ANSI control sequences. Set to anything else to assume a non-ANSI terminal. See is_ansi_tty().

cli.condition_unicode_bullets

TRUE or FALSE to force turn on or off the Unicode symbols when printing conditions. E.g. in format_error(), format_warning(), format_message() and also in cli_abort(), cli_warn() and cli_inform().

cli.condition_width

Integer scalar (or Inf) to set the console width when cli is formatting errors, warnings or messages in format_error(), format_warning() and format_message(). When formatting conditions this option takes precedence over cli.width.

cli.default_handler

General handler function for all cli conditions. See https://cli.r-lib.org/articles/semantic-cli.html#cli-messages-1

cli.default_num_colors

Default number of ANSI colors. This value is used if the number of colors is not already set by

• the cli.num_colors option,

• the R_CLI_NUM_COLORS environment variable,

• the crayon.enabled and crayon.colors options,

• the NO_COLOR environment variable,

• the knitr.in.progress option,

• a sink() call for the stream.

You can also use this option if color support is detected correctly, but you want to adjust the number of colors. E.g.

• if crayon.enabled is TRUE, but crayon.colors is not,

• in Emacs on Windows,

• in terminals.

See num_ansi_colors(). See also the cli.num_colors option.

cli.dynamic

Set to TRUE to assume a dynamic terminal, that supports ⁠\r⁠. Set to anything else to assume a non-dynamic terminal. See is_dynamic_tty().

cli.hide_cursor

Whether the cli status bar should try to hide the cursor on terminals. Set the FALSE if the hidden cursor causes issues.

cli.hyperlink

Set to true, TRUE or True to tell cli that the terminal supports ANSI hyperlinks. Set to anything else to assume no hyperlink support. See style_hyperlink().

cli.ignore_unknown_rstudio_theme

Set to TRUE to omit a warning for an unknown RStudio theme in code_highlight().

cli.num_colors

Number of ANSI colors. See num_ansi_colors(). See also the cli.default_num_colors option.

cli.message_class

Character vector of classes to add to cli's conditions.

cli.progress_bar_style

Progress bar style. See cli_progress_styles().

cli.progress_bar_style_ascii

Progress bar style on ASCII consoles. See cli_progress_styles().

cli.progress_bar_style_unicode

Progress bar style on Unicode (UTF-8) consoles; See cli_progress_styles().

cli.progress_clear

Whether to clear terminated progress bar from the screen on dynamic terminals. See cli_progress_bar().

cli.progress_demo_live

Whether cli_progress_demo() should show a live demo, or just record the progress bar frames.

cli.progress_format_download

Default format string for download progress bars.

cli.progress_format_download_nototal

Default format string for download progress bars with unknown totals.

cli.progress_format_iterator

Default format string for iterator progress bars.

cli.progress_format_iterator_nototal

Default format string for iterator progress bars with unknown total number of progress units.

cli.progress_format_tasks

Default format string for tasks progress bars.

cli.progress_format_tasks_nototal

Default format string for tasks progress bars with unknown totals.

cli.progress_handlers

Progress handlers to try. See cli_progress_builtin_handlers().

cli.progress_handlers_force

Progress handlers that will always be used, even if another handler was already selected. See cli_progress_builtin_handlers().

cli.progress_handlers_only

Progress handlers to force, ignoring handlers set in cli.progress_handlers and cli.progress_handlers_force. See cli_progress_builtin_handlers().

cli.progress_say_args

Command line arguments for the say progress handlers. See cli_progress_builtin_handlers().

cli.progress_say_command

External command to use in the say progress handler. See cli_progress_builtin_handlers().

cli.progress_say_frequency

Minimum delay between say calls in the say progress handler. say ignores very frequent updates, to keep the speech comprehensible. See cli_progress_builtin_handlers().

cli.progress_show_after

Delay before showing a progress bar, in seconds. Progress bars that finish before this delay are not shown at all. cli also shows progress bars that have more than 50% to go after half of this delay has passed.

cli.spinner

Default spinner to use, see get_spinner().

cli.spinner_ascii

Default spinner to use on ASCII terminals, see get_spinner().

cli.spinner_unicode

Default spinner to use on Unicode terminals, see get_spinner().

cli.theme

Default cli theme, in addition to the built-in theme. This option in intended for the package developers. See themes and start_app().

cli.theme_dark

Whether cli should assume a dark theme for the builtin theme. See builtin_theme().

cli.unicode

Whether to assume a Unicode terminal. If not set, then it is auto-detected. See is_utf8_output().

cli.user_theme

cli user theme. This option is intended for end users. See themes.

cli.warn_inline_newlines

Whether to emit a warning when cli replaces newline characters with spaces within a {.class } inline style. Defaults to FALSE.

cli.width

Terminal width to assume. If not set, then it is auto-detected. See console_width().

rlib_interactive

Whether to assume an interactive R session. If not set, then it is auto-detected.

width

Terminal width. This is used on some platforms, if cli.width is not set.

Internal configuration

These are environment variables and options are for cli developers, users should not rely on them as they may change between cli releases.

Internal environment variables

ASCIICAST

Used to detect an asciicast sub-process in RStudio.

ANSICON

Used to detect ANSICON when detecting the number of ANSI colors.

CI

Used to detect if the code is running on a CI. If yes, we avoid ANSI hyperlinks.

CLI_DEBUG_BAD_END

Whether to warn about cli_end() calls when there is no container to close.

CLI_NO_BUILTIN_THEME

Set it to true to omit the builtin theme.

CLI_SPEED_TIME

Can be used to speed up cli's timer. It is a factor, e.g. setting it to 2 makes cli's time go twice as fast.

CLI_TICK_TIME

How often the cli timer should alert, in milliseconds.

CMDER_ROOT

Used to detect cmder when detecting the number of ANSI colors.

COLORTERM

Used when detecting ANSI color support.

ConEmuANSI

Used to detect ConEmu when detecting the number of ANSI colors.

EMACS

Used to detect Emacs.

INSIDE_EMACS

Used to detect Emacs.

NOT_CRAN

Set to true to run tests / examples / checks, that do not run on CRAN.

⁠_R_CHECK_PACKAGE_NAME_⁠

Used to detect ⁠R CMD check⁠.

R_BROWSER

Used to detect the RStudio build pane.

R_GUI_APP_VERSION

Used to detect R.app on macOS, to decide if the console has ANSI control sequences.

R_PACKAGE_DIR

Used to detect if the code is running under ⁠R CMD INSTALL⁠.

R_PDFVIEWER

Used to detect the RStudio build pane.

R_PROGRESS_NO_EXAMPLES

Set to true to avoid running examples, outside of ⁠R CMD check⁠.