Title:	Helpers for Developing Command Line Interfaces
Version:	3.6.4
Description:	A suite of tools to build attractive command line interfaces ('CLIs'), from semantic elements: headings, lists, alerts, paragraphs, etc. Supports custom themes via a 'CSS'-like language. It also contains a number of lower level 'CLI' elements: rules, boxes, trees, and 'Unicode' symbols with 'ASCII' alternatives. It support ANSI colors and text styles as well.
License:	MIT + file LICENSE
URL:	https://cli.r-lib.org, https://github.com/r-lib/cli
BugReports:	https://github.com/r-lib/cli/issues
Depends:	R (≥ 3.4)
Imports:	utils
Suggests:	callr, covr, crayon, digest, glue (≥ 1.6.0), grDevices, htmltools, htmlwidgets, knitr, methods, processx, ps (≥ 1.3.4.9000), rlang (≥ 1.0.2.9003), rmarkdown, rprojroot, rstudioapi, testthat (≥ 3.2.0), tibble, whoami, withr
Config/Needs/website:	r-lib/asciicast, bench, brio, cpp11, decor, desc, fansi, prettyunits, sessioninfo, tidyverse/tidytemplate, usethis, vctrs
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	yes
Packaged:	2025-02-11 21:14:07 UTC; gaborcsardi
Author:	Gábor Csárdi [aut, cre], Hadley Wickham [ctb], Kirill Müller [ctb], Salim Brüggemann [ctb], Posit Software, PBC [cph, fnd]
Maintainer:	Gábor Csárdi <gabor@posit.co>
Repository:	CRAN
Date/Publication:	2025-02-13 05:20:02 UTC

cli: Helpers for Developing Command Line Interfaces

Description

A suite of tools to build attractive command line interfaces ('CLIs'), from semantic elements: headings, lists, alerts, paragraphs, etc. Supports custom themes via a 'CSS'-like language. It also contains a number of lower level 'CLI' elements: rules, boxes, trees, and 'Unicode' symbols with 'ASCII' alternatives. It support ANSI colors and text styles as well.

Author(s)

Maintainer: Gábor Csárdi gabor@posit.co

Other contributors:

• Hadley Wickham [contributor]

• Kirill Müller [contributor]

• Salim Brüggemann salim-b@pm.me (ORCID) [contributor]

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://cli.r-lib.org

• https://github.com/r-lib/cli

• Report bugs at https://github.com/r-lib/cli/issues

Align an ANSI colored string

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

Collapse a vector into a string scalar

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

Format a character vector in multiple columns

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)

Check if a string has some ANSI styling

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

Hide/show cursor in a terminal

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

Convert ANSI styled text to HTML

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)

CSS styles for the output of ansi_html()

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

Count number of characters in an ANSI colored string

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

Perl compatible regular expression that matches ANSI escape sequences

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

Simplify ANSI styling tags

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.

Labels a character vector as containing ANSI control codes.

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

Remove ANSI escape sequences from a string

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"

Split an ANSI colored string

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), "")

Truncate an ANSI string

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)

Wrap an ANSI styled string to a certain width

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

Substring(s) of an ANSI colored string

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

Substring(s) of an ANSI colored string

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

ANSI character translation and case folding

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)

Remove leading and/or trailing whitespace from an ANSI string

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

ANSI colored text

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

The built-in CLI theme

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

cat() helpers

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

Compose multiple cli functions

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.

Signal an error, warning or message with a cli formatted message

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

CLI alerts

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

CLI block quote

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

List of items

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

List of verbatim items

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

A block of code

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.

Debug cli internals

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)

Generic CLI container

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.

Definition list

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

Close a CLI container

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">                                         

Capture the output of cli functions instead of printing it

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")
})

Format a value for printing

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

Create a format method for an object using cli tools

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

CLI headings

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

CLI list item(s)

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

List the currently active themes

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

Ordered CLI list

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

The connection option that cli would use

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.

CLI paragraph

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.

Indicate the start and termination of some computation in the status bar (superseded)

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

Add a progress bar to a mapping function or for loop

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

cli progress bars

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

cli progress handlers

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

cli progress bar demo

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.

Simplified cli progress messages

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

Progress bar utility functions.

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

Add text output to a progress bar

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

Simplified cli progress messages, with styling

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

List of built-in cli progress styles

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

CLI horizontal rule

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

cli situation report

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

Update the status bar (superseded)

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

Clear the status bar (superseded)

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

Update the status bar (superseded)

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

CLI text

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

Unordered CLI list

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

Add custom cli style to a vector

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

CLI verbatim text

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.

cli environment variables and options

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⁠.

RSTUDIO

Used to detect RStudio, in various functions.

RSTUDIO_CONSOLE_COLOR

Used to detect the number of colors in RStudio. See num_ansi_colors().

RSTUDIO_CONSOLE_WIDTH

Used to auto-detect console width in RStudio.

RSTUDIO_TERM

Used to detect the RStudio build pane.

TEAMCITY_VERSION

Used to detect the TeamCity CI, to turn off ANSI hyperlinks.

TERM

Used to detect if the console has ANSI control sequences, in a terminal.

TERM_PROGRAM

Used to detect iTerm for the dark theme detection and the ANSI hyperlink support detection.

TERM_PROGRAM_VERSION

Used to detect a suitable iTerm version for ANSI hyperlink support.

TESTTHAT

Used to detect running in testthat tests.

VTE_VERSION

Used to detect a suitable VTE version for ANSI hyperlinks.

Internal options

cli__pb

This option is set to the progress bar that is being updated, when interpolating the format string.

cli.record

Internal option to mark the state that cli is recording messages.

crayon.colors

Deprecated option for the number of ANSI colors, that is still supported by cli, when the new options are not set. See num_ansi_colors().

crayon.enabled

Deprecated option to turn ANSI colors on/off. This is still supported by cli when the new options are not set. See num_ansi_colors().

crayon.hyperlink

Whether to assume ANSI hyperlink support. See ansi_has_hyperlink_support().

knitr.in.progress

Used to detect knitr when detecting interactive sessions and ANSI color support.

rstudio.notebook.executing

Used to detect knitr when detecting interactive sessions.

Syntax highlight R code

Description

Syntax highlight R code

Usage

code_highlight(code, code_theme = NULL, envir = NULL)

Arguments

Details

See code_theme_list() for the default syntax highlighting theme and how to change it.

If code does not parse, then it is returned unchanged and a cli_parse_failure condition is thrown. Note that this is not an error, and the condition is ignored, unless explicitly caught.

Value

Character vector, the highlighted code.

See Also

Other syntax highlighting: code_theme_list()

Examples

code_highlight(deparse(ls))
cat(code_highlight(deparse(ls)), sep = "\n")

Syntax highlighting themes

Description

code_theme_list() lists the built-in code themes.

Usage

code_theme_list()

Value

Character vector of the built-in code theme names.

Code themes

A theme is a list of character vectors, except for bracket, see below. Each character vector must contain RGB colors (e.g. "#a9a9a9"), and cli styles, e.g. "bold". Entries in the list:

• reserved: reserved words

• number: numeric literals

• null: the NULL constant

• operator: operators, including assignment

• call: function calls

• string: character literals

• comment: comments

• bracket: brackets: (){}[] This is a list of character vectors, to create "rainbow" brackets. It is recycled for deeply nested lists.

The default code theme

In RStudio, it matches the current theme of the IDE.

You can use three options to customize the code theme:

• If cli.code_theme is set, it is used.

• Otherwise if R is running in RStudio and cli.code_theme_rstudio is set, then it is used.

• Otherwise if T is not running in RStudio and cli.code_theme_terminal is set, then it is used.

You can set these options to the name of a built-in theme, or to list that specifies a custom theme. See code_theme_list() for the list of the built-in themes.

See Also

Other syntax highlighting: code_highlight()

Examples

code_theme_list()
code_highlight(deparse(get), code_theme = "Solarized Dark")

Combine two or more ANSI styles

Description

Combine two or more styles or style functions into a new style function that can be called on strings to style them.

Usage

combine_ansi_styles(...)

Arguments

Details

It does not usually make sense to combine two foreground colors (or two background colors), because only the first one applied will be used.

It does make sense to combine different kind of styles, e.g. background color, foreground color, bold font.

Value

The combined style function.

See Also

Other ANSI styling: ansi-styles, make_ansi_style(), num_ansi_colors()

Examples

## Use style names
alert <- combine_ansi_styles("bold", "red4")
cat(alert("Warning!"), "\n")

## Or style functions
alert <- combine_ansi_styles(style_bold, col_red, bg_cyan)
cat(alert("Warning!"), "\n")

## Combine a composite style
alert <- combine_ansi_styles(
  "bold",
  combine_ansi_styles("red", bg_cyan))
cat(alert("Warning!"), "\n")

Determine the width of the console

Description

It uses the cli.width option, if set. Otherwise it tries to determine the size of the terminal or console window.

Usage

console_width()

Details

These are the exact rules:

• If the cli.width option is set to a positive integer, it is used.

• If the cli.width option is set, but it is not a positive integer, and error is thrown.

Then we try to determine the size of the terminal or console window:

• If we are not in RStudio, or we are in an RStudio terminal, then we try to use the tty_size() function to query the terminal size. This might fail if R is not running in a terminal, but failures are ignored.

• If we are in the RStudio build pane, then the RSTUDIO_CONSOLE_WIDTH environment variable is used. If the build pane is resized, then this environment variable is not accurate any more, and the output might get garbled.

• We are not using the RSTUDIO_CONSOLE_WIDTH environment variable if we are in the RStudio console.

If we cannot determine the size of the terminal or console window, then we use the width option. If the width option is not set, then we return 80L.

Value

Integer scalar, the console with, in number of characters.

Examples

console_width()

About cli containers

Description

Container elements may contain other elements. Currently the following commands create container elements: cli_div(), cli_par(), the list elements: cli_ul(), cli_ol(), cli_dl(), and list items are containers as well: cli_li().

Details

Themes

A container can add a new theme, which is removed when the container exits.

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

#>                                                                                 
#> Custom title                                                                    

Auto-closing

Container elements are closed with cli_end(). For convenience, by default they are closed automatically when the function that created them terminated (either regularly or with an error). The default behavior can be changed with the .auto_close argument.

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                                                     

Debugging

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-226" class="myclass">                                        

Show a demo of some (by default all) spinners

Description

Each spinner is shown for about 2-3 seconds.

Usage

demo_spinners(which = NULL)

Arguments

Details

demo_spinners("clock")

See Also

Other spinners: get_spinner(), list_spinners(), make_spinner()

Compare two character vectors elementwise

Description

Its printed output is similar to calling diff -u at the command line.

Usage

diff_chr(old, new, max_dist = Inf)

Arguments

Value

A list that is a cli_diff_chr object, with a format() and a print() method. You can also access its members:

• old and new are the original inputs,

• lcs is a data frame of LCS edit that transform old into new.

The lcs data frame has the following columns:

• operation: one of "match", "delete" or "insert".

• offset: offset in old for matches and deletions, offset in new for insertions.

• length: length of the operation, i.e. number of matching, deleted or inserted elements.

• old_offset: offset in old after the operation.

• new_offset: offset in new after the operation.

See Also

The diffobj package for a much more comprehensive set of diff-like tools.

Other diff functions in cli: diff_str()

Examples

letters2 <- c("P", "R", "E", letters, "P", "O", "S", "T")
letters2[11:16] <- c("M", "I", "D", "D", "L", "E")
diff_chr(letters, letters2)

Compare two character strings, character by character

Description

Characters are defined by UTF-8 graphemes.

Usage

diff_str(old, new, max_dist = Inf)

Arguments

Value

A list that is a cli_diff_str object and also a cli_diff_chr object, see diff_str for the details about its structure.

See Also

The diffobj package for a much more comprehensive set of diff-like tools.

Other diff functions in cli: diff_chr()

Examples

str1 <- "abcdefghijklmnopqrstuvwxyz"
str2 <- "PREabcdefgMIDDLEnopqrstuvwxyzPOST"
diff_str(str1, str2)

Frequently Asked Questions

Description

Frequently Asked Questions

Details

My platform supports ANSI colors, why does cli not use them?

It is probably a mistake in the ANSI support detection algorithm. Please open an issue at https://github.com/r-lib/cli/issues and do not forget to tell us the details of your platform and terminal or GUI.

How do I turn off ANSI colors and styles?

Set the NO_COLOR environment variable to a non-empty value. You can do this in your .Renviron file (use usethis::edit_r_environ()).

If you want to do this for testthat tests, then consider using the 3rd edition on testthat, which does turn off ANSI styling automatically inside test_that().

cli does not show the output before file.choose()

Try calling flush.console() to flush the console, before file.choose(). If flushing does not work and you are in RStudio, then it is probably this RStudio bug: https://github.com/rstudio/rstudio/issues/8040 See more details at https://github.com/r-lib/cli/issues/151

Why are heading separators wider than my screen in RStudio?

The display width of some Unicode characters ambiguous in the Unicode standard. Some software treats them as narrow (one column on the screen), other as wide (two columns). In some terminal emulators (for example iTerm2), you can configure the preferred behavior.

Unfortunately the box drawing characters that cli uses also have ambiguous width.

In RStudio the behavior depends on the font. In particular, Consolas, Courier and Inconsolata treats them as wide characters, so cli output will not look great with these. Some good, modern fonts that look good include Menlo, Fira Code and Source Code Pro.

If you do not want to change your font, you can also turn off Unicode output, by setting the cli.unicode option:

options(cli.unicode = FALSE)

A related issue: https://github.com/r-lib/cli/issues/320

Is there a suggested font to use with cli?

In modern terminals, cli output usually looks good.

If you see too wide heading separators in RStudio, then see the previous question: Why are heading separators wider than my screen in RStudio?.

If some output is garbled, then cli probably misdetected Unicode support for your terminal or font. You can try choosing a different font. In our experience output looks good with Menlo, Fira Code and Source Code Pro. Alternatively you can turn off Unicode output:

options(cli.unicode = FALSE)

If you think this is our fault, then please also file an issue at https://github.com/r-lib/cli/issues

Format an error, warning or diagnostic message

Description

You can then throw this message with stop() or rlang::abort().

Usage

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

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

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

Arguments

Details

The messages can use inline styling, pluralization and glue substitutions.

n <- "boo"
stop(format_error(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.                                         

len <- 26
idx <- 100
stop(format_error(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.                                           

See Also

These functions support 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(), cli_ul(), format_inline()

Format and returns a line of text

Description

You can use this function to format a line of cli text, without emitting it to the screen. It uses cli_text() internally.

Usage

format_inline(
  ...,
  .envir = parent.frame(),
  collapse = TRUE,
  keep_whitespace = TRUE
)

Arguments

Details

format_inline() performs no width-wrapping.

Value

Character scalar, the formatted string.

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(), cli_ul(), format_error()

Examples

format_inline("A message for {.emph later}, thanks {.fn format_inline}.")

Character vector to put a spinner on the screen

Description

cli contains many different spinners, you choose one according to your taste.

Usage

get_spinner(which = NULL)

Arguments

Details

options(cli.spinner = "hearts")
fun <- function() {
  cli_progress_bar("Spinning")
  for (i in 1:100) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
}
fun()
options(cli.spinner = NULL)

Value

A list with entries: name, interval: the suggested update interval in milliseconds and frames: the character vector of the spinner's frames.

See Also

Other spinners: demo_spinners(), list_spinners(), make_spinner()

Check if the current platform/terminal supports reading single keys.

Description

Check if the current platform/terminal supports reading single keys.

Usage

has_keypress_support()

Details

Supported platforms:

• Terminals in Windows and Unix.

• RStudio terminal.

Not supported:

• RStudio (if not in the RStudio terminal).

• R.app on macOS.

• Rgui on Windows.

• Emacs ESS.

• Others.

Value

Whether there is support for waiting for individual keypressses.

See Also

Other keypress function: keypress()

Examples

has_keypress_support()

Adjective-animal hash

Description

Adjective-animal hash

Usage

hash_animal(x, n_adj = 2)

hash_raw_animal(x, n_adj = 2)

hash_obj_animal(x, n_adj = 2, serialize_version = 2)

Arguments

Details

It uses the first 13 hexadecimal characters (out of the 32) of the MD5 hash of the input, and converts them into an adjective-animal form to create a human readable hash.

Number of possible hash values

hash_animal() uses 1748 animal names and 8946 different adjectives. The number of different hashes you can get for different values of n_adj:

Source

The list of adjectives and animals comes from the ids package, and in turn from https://github.com/a-type/adjective-adjective-animal, and from ⁠https://gfycat.com⁠ (now gone).

hash_raw_animal() calculates the adjective-animal hash of the bytes of a raw vector.

hash_obj_animal() calculates the adjective-animal hash of an R object. The object is serialized into a binary vector first.

Value

A data frame with columns

• hash: the hash value, a string.

• words: list column with the adjectives and the animal name in a character vector.

hash_raw_animal() and hash_obj_animal() return a list with entries:

• hash: the hash value, a string,

• 'words: the adjectives and the animal name in a character vector.

See Also

the ids package for generating random adjective-animal ids

Other hash functions: hash_emoji(), hash_md5(), hash_sha1(), hash_sha256(), hash_xxhash()

Examples

hash_animal(c("foo", "bar"))

# if you increase `n_adj`, the shorter hash is a suffix of the longer:
hash_animal("cli package", 0)$hash
hash_animal("cli package", 1)$hash
hash_animal("cli package", 2)$hash
hash_animal("cli package", 3)$hash

Emoji hash

Description

Emoji hash

Usage

hash_emoji(x, size = 3)

hash_raw_emoji(x, size = 3)

hash_obj_emoji(x, size = 3, serialize_version = 2)

Arguments

Details

It uses the first 13 hexadecimal characters (out of the 32) of the MD5 hash of the input, and converts them into an emoji representation. It uses a manually selected subset of all emojis, that tend to be displayed correctly.

Number of possible hash values

cli uses 2280 possible emojis. This is the number of different hashes you can get for different values of size:

hash_raw_emoji() calculates the emoji hash of the bytes of a raw vector.

hash_obj_emoji() calculates the emoji hash of an R object. The object is serialized into a binary vector first.

Value

hash_emoji() returns a data frame with columns

• hash: the emoji hash, a string of the requested size.

• emojis: list column with the emoji characters in character vectors. Note that an emoji might have multiple code points.

• text: text representation of hash, comma separated.

• names: list column with the text representations of emojis, in character vectors.

hash_raw_emoji() and hash_obj_emoji() return a list with entries:

• hash: the emoji hash, a string of requested size,

• emojis: the individual emoji characters in a character vector,

• text: text representation of hash, comma separated,

• names: names of the emojis, in a character vector.

See Also

the emoji package for a comprehensive list of emojis

Other hash functions: hash_animal(), hash_md5(), hash_sha1(), hash_sha256(), hash_xxhash()

Examples

hash_emoji(c("foo", NA, "bar", ""))$text

# if you increase `size`, the shorter hash is a prefix of the longer:
hash_emoji("foobar", 1)$text
hash_emoji("foobar", 2)$text
hash_emoji("foobar", 3)$text
hash_emoji("foobar", 4)$text

MD5 hash

Description

Calculate the MD5 hash of each element of a character vector.

Usage

hash_md5(x)

hash_raw_md5(x)

hash_obj_md5(x, serialize_version = 2)

hash_file_md5(paths)

Arguments

Details

hash_raw_md5() calculates the MD5 hash of the bytes of a raw vector.

hash_obj_md5() calculates the MD5 hash of an R object. The object is serialized into a binary vector first.

hash_file_md5() calculates the MD5 hash of one or more files.

Value

hash_md5() returns a character vector of hexadecimal MD5 hashes.

hash_raw_md5() returns a character scalar.

hash_obj_md5() returns a character scalar.

See Also

tools::md5sum() for a base R MD5 function that works on files.

Other hash functions: hash_animal(), hash_emoji(), hash_sha1(), hash_sha256(), hash_xxhash()

Examples

hash_md5(c("foo", NA, "bar", ""))

SHA-1 hash

Description

Calculate the SHA-1 hash of each element of a character vector.

Usage

hash_sha1(x)

hash_raw_sha1(x)

hash_obj_sha1(x, serialize_version = 2)

hash_file_sha1(paths)

Arguments

Details

hash_raw_sha1() calculates the SHA-1 hash of the bytes of a raw vector.

hash_obj_sha1() calculates the SHA-1 hash of an R object. The object is serialized into a binary vector first.

hash_file_sha1() calculates the SHA-1 hash of one or more files.

Value

hash_sha1() returns a character vector of hexadecimal SHA-1 hashes.

hash_raw_sha1() returns a character scalar.

hash_obj_sha1() returns a character scalar.

hash_file_sha1() returns a character vector of SHA-1 hashes.

See Also

Other hash functions: hash_animal(), hash_emoji(), hash_md5(), hash_sha256(), hash_xxhash()

Examples

hash_sha1(c("foo", NA, "bar", ""))

SHA-256 hash

Description

Calculate the SHA-256 hash of each element of a character vector.

Usage

hash_sha256(x)

hash_raw_sha256(x)

hash_obj_sha256(x, serialize_version = 2)

hash_file_sha256(paths)

Arguments

Details

hash_raw_sha256() calculates the SHA-256 hash of the bytes of a raw vector.

hash_obj_sha256() calculates the SHA-256 hash of an R object. The object is serialized into a binary vector first.

hash_file_sha256() calculates the SHA-256 hash of one or more files.

Value

hash_sha256() returns a character vector of hexadecimal SHA-256 hashes.

hash_raw_sha256() returns a character scalar.

hash_obj_sha256() returns a character scalar.

hash_file_sha256() returns a character vector of SHA-256 hashes.

See Also

Other hash functions: hash_animal(), hash_emoji(), hash_md5(), hash_sha1(), hash_xxhash()

Examples

hash_sha256(c("foo", NA, "bar", ""))

xxHash

Description

Extremely fast hash algorithm.

Usage

hash_xxhash(x)

hash_raw_xxhash(x)

hash_obj_xxhash(x, serialize_version = 2)

hash_file_xxhash(paths)

hash_xxhash64(x)

hash_raw_xxhash64(x)

hash_obj_xxhash64(x, serialize_version = 2)

hash_file_xxhash64(paths)

Arguments

Details

hash_raw_xxhash() calculates the xxHash hash of the bytes of a raw vector.

hash_obj_xxhash() calculates the xxHash hash of an R object. The object is serialized into a binary vector first.

hash_file_xxhash() calculates the xxHash hash of one or more files.

The 64 functions caculate the 64 bit variant of xxHash. Otherwise they work the same.

Value

hash_xxhash() returns a character vector of hexadecimal xxHash hashes.

hash_raw_xxhash() returns a character scalar.

hash_obj_xxhash() returns a character scalar.

hash_file_xxhash() returns a character vector of xxHash hashes.

See Also

Other hash functions: hash_animal(), hash_emoji(), hash_md5(), hash_sha1(), hash_sha256()

Examples

hash_xxhash(c("foo", NA, "bar", ""))

About inline markup in the semantic cli

Description

To learn how to use cli’s semantic markup, start with the ‘Building a semantic CLI’ article at https://cli.r-lib.org.

Command substitution

All text emitted by cli supports glue interpolation. Expressions enclosed by braces will be evaluated as R code. See glue::glue() for details.

In addition to regular glue interpolation, cli can also add classes to parts of the text, and these classes can be used in themes. For example

cli_text("This is {.emph important}.")

#> This is important.                                                              

adds a class to the "important" word, class "emph". Note that in this case the string within the braces is usually not a valid R expression. If you want to mix classes with interpolation, add another pair of braces:

adjective <- "great"
cli_text("This is {.emph {adjective}}.")

#> This is great.                                                                  

An inline class will always create a span element internally. So in themes, you can use the span.emph CSS selector to change how inline text is emphasized:

cli_div(theme = list(span.emph = list(color = "red")))
adjective <- "nice and red"
cli_text("This is {.emph {adjective}}.")

#> This is nice and red.                                                           

Classes

The default theme defines the following inline classes:

• arg for a function argument.

• cls for an S3, S4, R6 or other class name.

• code for a piece of code.

• dt is used for the terms in a definition list (cli_dl()).

• dd is used for the descriptions in a definition list (cli_dl()).

• email for an email address. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See links for more information about cli hyperlinks.

• emph for emphasized text.

• envvar for the name of an environment variable.

• field for a generic field, e.g. in a named list.

• file for a file name. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link that opens the file in RStudio or with the default app for the file type. See links for more information about cli hyperlinks.

• fn for a function name. If it is in the package::function_name form, and the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See links for more information about cli hyperlinks.

• fun same as fn.

• help is a help page of a function. If the terminal supports ANSI hyperlinks to help pages (e.g. RStudio), then cli creates a clickable link. It supports link text. See links for more information about cli hyperlinks.

• href creates a hyperlink, potentially with a link text. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See links for more information about cli hyperlinks.

• kbd for a keyboard key.

• key same as kbd.

• obj_type_friendly formats the type of an R object in a readable way, and it should be used with {}, see an example below.

• or changes the string that separates the last two elements of collapsed vectors (see below) from "and" to "or".

• path for a path (the same as file in the default theme).

• pkg for a package name.

• run is an R expression, that is potentially clickable if the terminal supports ANSI hyperlinks to runnable code (e.g. RStudio). It supports link text. See links for more information about cli hyperlinks.

• str for a double quoted string escaped by base::encodeString().

• strong for strong importance.

• topic is a help page of a topic. If the terminal supports ANSI hyperlinks to help pages (e.g. RStudio), then cli creates a clickable link. It supports link text. See links for more information about cli hyperlinks.

• type formats the type of an R object in a readable way, and it should be used with {}, see an example below.

• url for a URL. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See links for more information about cli hyperlinks.

• var for a variable name.

• val for a generic "value".

• vignette is a vignette. If the terminal supports ANSI hyperlinks to help pages (e.g. RStudio), then cli creates a clickable link. It supports link text. See links for more information about cli hyperlinks.

ul <- cli_ul()
cli_li("{.emph Emphasized} text.")
cli_li("{.strong Strong} importance.")
cli_li("A piece of code: {.code sum(a) / length(a)}.")
cli_li("A package name: {.pkg cli}.")
cli_li("A function name: {.fn cli_text}.")
cli_li("A keyboard key: press {.kbd ENTER}.")
cli_li("A file name: {.file /usr/bin/env}.")
cli_li("An email address: {.email bugs.bunny@acme.com}.")
cli_li("A URL: {.url https://example.com}.")
cli_li("An environment variable: {.envvar R_LIBS}.")
cli_li("`mtcars` is {.obj_type_friendly {mtcars}}")
cli_end(ul)

#> • Emphasized text.                                                              
#> • Strong importance.                                                            
#> • A piece of code: `sum(a) / length(a)`.                                        
#> • A package name: cli.                                                          
#> • A function name: `cli_text()`.                                                
#> • A keyboard key: press [ENTER].                                                
#> • A file name: /usr/bin/env.                                                    
#> • An email address: bugs.bunny@acme.com.                                        
#> • A URL: <https://example.com>.                                                 
#> • An environment variable: `R_LIBS`.                                            
#> • `mtcars` is a data frame                                                      

You can add new classes by defining them in the theme, and then using them.

cli_div(theme = list(
  span.myclass = list(color = "lightgrey"),
  "span.myclass" = list(before = "<<"),
  "span.myclass" = list(after = ">>")))
cli_text("This is {.myclass in angle brackets}.")
cli_end()

#> This is <<in angle brackets>>.                                                  

Highlighting weird-looking values

Often it is useful to highlight a weird file or path name, e.g. one that starts or ends with space characters. The built-in theme does this for .file, .path and .email by default. You can highlight any string inline by adding the .q class to it.

The current highlighting algorithm

• adds single quotes to the string if it does not start or end with an alphanumeric character, underscore, dot or forward slash.

• Highlights the background colors of leading and trailing spaces on terminals that support ANSI colors.

Collapsing inline vectors

When cli performs inline text formatting, it automatically collapses glue substitutions, after formatting. This is handy to create lists of files, packages, etc.

pkgs <- c("pkg1", "pkg2", "pkg3")
cli_text("Packages: {pkgs}.")
cli_text("Packages: {.pkg {pkgs}}.")

#> Packages: pkg1, pkg2, and pkg3.                                                 
#> Packages: pkg1, pkg2, and pkg3.                                                 

Class names are collapsed differently by default

x <- Sys.time()
cli_text("Hey, {.var x} has class {.cls {class(x)}}.")

#> Hey, `x` has class <POSIXct/POSIXt>.                                            

By default cli truncates long vectors. The truncation limit is by default twenty elements, but you can change it with the vec-trunc style.

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

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

Formatting values

The val inline class formats values. By default (c.f. the built-in theme), it calls the cli_format() generic function, with the current style as the argument. See cli_format() for examples.

str is for formatting strings, it uses base::encodeString() with double quotes.

Escaping ⁠{⁠ and ⁠}⁠

It might happen that you want to pass a string to ⁠cli_*⁠ functions, and you do not want command substitution in that string, because it might contain ⁠{⁠ and ⁠}⁠ characters. The simplest solution for this is to refer to the string from a template:

msg <- "Error in if (ncol(dat$y)) {: argument is of length zero"
cli_alert_warning("{msg}")

#> ! Error in if (ncol(dat$y)) {: argument is of length zero                       

If you want to explicitly escape ⁠{⁠ and ⁠}⁠ characters, just double them:

cli_alert_warning("A warning with {{ braces }}.")

#> ! A warning with { braces }.                                                    

See also examples below.

Pluralization

All cli commands that emit text support pluralization. Some examples:

ndirs <- 1
nfiles <- 13
pkgs <- c("pkg1", "pkg2", "pkg3")
cli_alert_info("Found {ndirs} director{?y/ies} and {nfiles} file{?s}.")
cli_text("Will install {length(pkgs)} package{?s}: {.pkg {pkgs}}")

#> ℹ Found 1 directory and 13 files.                                               
#> Will install 3 packages: pkg1, pkg2, and pkg3                                   

See pluralization for details.

Wrapping

Most cli containers wrap the text to width the container's width, while observing margins requested by the theme.

To avoid a line break, you can use the UTF_8 non-breaking space character: ⁠\u00a0⁠. cli will not break a line here.

To force a line break, insert a form feed character: ⁠\f⁠ or ⁠\u000c⁠. cli will insert a line break there.

Detect if a stream support ANSI escape characters

Description

We check that all of the following hold:

• The stream is a terminal.

• The platform is Unix.

• R is not running inside R.app (the macOS GUI).

• R is not running inside RStudio.

• R is not running inside Emacs.

• The terminal is not "dumb".

• stream is either the standard output or the standard error stream.

Usage

is_ansi_tty(stream = "auto")

Arguments

Value

TRUE or FALSE.

See Also

Other terminal capabilities: ansi_hide_cursor(), is_dynamic_tty()

Examples

is_ansi_tty()

Detect whether a stream supports ⁠\\r⁠ (Carriage return)

Description

In a terminal, ⁠\\r⁠ moves the cursor to the first position of the same line. It is also supported by most R IDEs. ⁠\\r⁠ is typically used to achieve a more dynamic, less cluttered user interface, e.g. to create progress bars.

Usage

is_dynamic_tty(stream = "auto")

Arguments

Details

If the output is directed to a file, then ⁠\\r⁠ characters are typically unwanted. This function detects if ⁠\\r⁠ can be used for the given stream or not.

The detection mechanism is as follows:

1. If the cli.dynamic option is set to TRUE, TRUE is returned.

2. If the cli.dynamic option is set to anything else, FALSE is returned.

3. If the R_CLI_DYNAMIC environment variable is not empty and set to the string "true", "TRUE" or "True", TRUE is returned.

4. If R_CLI_DYNAMIC is not empty and set to anything else, FALSE is returned.

5. If the stream is a terminal, then TRUE is returned.

6. If the stream is the standard output or error within RStudio, the macOS R app, or RKWard IDE, TRUE is returned.

7. Otherwise FALSE is returned.

See Also

Other terminal capabilities: ansi_hide_cursor(), is_ansi_tty()

Examples

is_dynamic_tty()
is_dynamic_tty(stdout())

Whether cli is emitting UTF-8 characters

Description

UTF-8 cli characters can be turned on by setting the cli.unicode option to TRUE. They can be turned off by setting if to FALSE. If this option is not set, then base::l10n_info() is used to detect UTF-8 support.

Usage

is_utf8_output()

Value

Flag, whether cli uses UTF-8 characters.

Read a single keypress at the terminal

Description

It currently only works at Linux/Unix and OSX terminals, and at the Windows command line. see has_keypress_support.

Usage

keypress(block = TRUE)

Arguments

Details

The following special keys are supported:

• Arrow keys: 'up', 'down', 'right', 'left'.

• Function keys: from 'f1' to 'f12'.

• Others: 'home', 'end', 'insert', 'delete', 'pageup', 'pagedown', 'tab', 'enter', 'backspace' (same as 'delete' on OSX keyboards), 'escape'.

• Control with one of the following keys: 'a', 'b', 'c', 'd', 'e', 'f', 'h', 'k', 'l', 'n', 'p', 't', 'u', 'w'.

Value

The key pressed, a character scalar. For non-blocking reads NA is returned if no keys are available.

See Also

Other keypress function: has_keypress_support()

Examples

x <- keypress()
cat("You pressed key", x, "\n")

cli hyperlinks

Description

Certain cli styles create clickable links, if your IDE or terminal supports them.

Note: hyperlinks are currently experimental

The details of the styles that create hyperlinks will prrobably change in the near future, based on user feedback.

About the links in this manual page

The hyperlinks that are included in this manual are demonstrative only, except for the ⁠https:⁠ links. They look like a hyperlink, and you can click on them, but they do nothing. I.e. a .run link will not run the linked expression if you click on it.

Hyperlink Support

As of today, the latest release of RStudio (version v2022.07.0+548) supports all hyperlink types discussed here. Certain terminals, e.g. iTerm on macOS, Linux terminals based on VTE (GNOME terminal) support .href, .email and .file links.

You can use ansi_has_hyperlink_support() to check if your terminal or IDE has hyperlink support in general, and ansi_hyperlink_types() to check if various types of hyperlinks are supported.

If your hyperlink support is not detected properly in your IDE or terminal, please open a cli issue at https://github.com/r-lib/cli/issues.

Link text

Before we delve into the various types of hyperlinks, a general comment about link texts. Some link styles support a custom link text:

• .href

• .help

• .topic

• .vignette

• .run

Others, i.e. .email, .file, .fun and .url do not support custom link text.

The generic syntax for link text is the same as for Markdown hyperlinks:

{.style [link text](url)}

Vectorization

Note that it is not possible to add link text to a vector of URLs. E.g. this will create a list of three URLs, all clickable:

urls <- paste0("https://httpbin.org/status/", c(200, 403, 404))
cli::cli_text("Some httpbin URLs: {.url {urls}}.")

#> Some httpbin URLs: <https://httpbin.org/status/200>,                            
#> <https://httpbin.org/status/403>, and                                           
#> <https://httpbin.org/status/404>.                                               

What if hyperlinks are not available?

If ANSI hyperlinks are not available, then the link text for of these styles outputs both the link text and the URL in a (hopefully) helpful way. See examples below.

URLs

There are two cli styles to link to generic URLs. .url does not allow custom link text, but ⁠\href⁠ does.

cli_text(
  "See the cli homepage at {.url https://cli.r-lib.org} for details."
)

#> See the cli homepage at <https://cli.r-lib.org> for details.                    

cli_text(
  "See the {.href [cli homepage](https://cli.r-lib.org)} for details."
)

#> See the cli homepage for details.                                               

Without hyperlink support

This is how these links look without hyperlink support:

local({
  withr::local_options(cli.hyperlink = FALSE)
  cli_text(
    "See the cli homepage at {.url https://cli.r-lib.org} for details."
  )
  cli_text(
    "See the {.href [cli homepage](https://cli.r-lib.org)} for details."
  )
})

#> See the cli homepage at <https://cli.r-lib.org> for details.                    
#> See the cli homepage (<https://cli.r-lib.org>) for details.                     

URL encoding

Note that cli does not encode the url, so you might need to call utils::URLencode() on it, especially, if it is substituted in via {}.

weirdurl <- utils::URLencode("https://example.com/has some spaces")
cli_text("See more at {.url {weirdurl}}.")

#> See more at <https://example.com/has%20some%20spaces>.                          

Files

The .file style now automatically creates a ⁠file:⁠ hyperlink. Because ⁠file:⁠ hyperlinks must contain an absolute path, cli tries to convert relative paths, and paths starting with ~ to aboslute path.

cli_text("... edit your {.file ~/.Rprofile} file.}")

#> ... edit your ~/.Rprofile file.}                                                

Link text

.file cannot use a custom link text. If you custom link text, then you can use .href with a ⁠file:⁠ URL.

prof <- path.expand("~/.Rprofile")
cli_text("... edit your {.href [R profile](file://{prof})}.")

#> ... edit your R profile.                                                        

Line and column numbers

You may add a line number to a file name, separated by :. Handlers typically place the cursor at that line after opening the file. You may also add a column number, after the line number, separated by another :.

cli_text("... see line 5 in {.file ~/.Rprofile:5}.")

#> ... see line 5 in ~/.Rprofile:5.                                                

Default handler

In RStudio ⁠file:⁠ URLs open within RStudio. If you click on a file link outside of RStudio, typically the operating system is consulted for the application to open it.

Without hyperlink support

One issue with using .href file files is that it does not look great if hyperlinks are not available. This will be improved in the future:

local({
  withr::local_options(cli.hyperlink = FALSE)
  prof <- path.expand("~/.Rprofile")
  cli_text("... edit your {.href [R profile](file://{prof})}.")
})

#> ... edit your R profile (<file:///Users/gaborcsardi/.Rprofile>).                

Links to the manual

.fun automatically creates links to the manual page of the function, provided the function name is in the packagename::functionname form:

cli::cli_text("... see {.fun stats::lm} to learn more.")

#> ... see `stats::lm()` to learn more.                                            

Link text

For a custom link text, use .help instead of .fun.

cli::cli_text("... see {.help [{.fun lm}](stats::lm)} to learn more.")

#> ... see `lm()` to learn more.                                                   

Without hyperlink support

The same message without hyperlink support looks like this:

local({
  withr::local_options(cli.hyperlink = FALSE)
  cli::cli_text("... see {.help [{.fun lm}](stats::lm)} to learn more.")
})

#> ... see `lm()` (`?stats::lm()`) to learn more.                                  

Topics

To link to a help topic that is not a function, use .topic:

cli::cli_text("... the tibble options at {.topic tibble::tibble_options}.")

#> ... the tibble options at tibble::tibble_options.                               

.topic support link text.

Vignettes

To link to a vignette, use .vignette:

cli::cli_text("... see the {.vignette tibble::types} vignette.")

#> ... see the tibble::types vignette.                                             

Click to run code

RStudio also supports a special link type that runs R code in the current R session upon clicking.

You can create these links with .run:

cli::cli_text("Run {.run testthat::snapshot_review()} to review")

#> Run testthat::snapshot_review() to review                                       

Link text

Sometimes you want to show a slightly different expression in the link, than the one that is evaluated. E.g. the evaluated expression probably needs to qualify packages with ::, but you might not want to show this:

cli::cli_text(
  "Run {.run [snapshot_review()](testthat::snapshot_review())} to review"
)

#> Run snapshot_review() to review                                                 

Security considerations

To make .run hyperlinks more secure, RStudio will not run code

• that is not in the pkg::fun(args) form,

• if args contains (, ⁠)⁠ or ⁠;⁠,

• if it calls a core package (base, stats, etc.),

• if it calls a package that is not loaded, and it is not one of testthat, devtools, usethis, rlang, pkgload, or pkgdown which are explicitly allowed.

When RStudio does not run a .run hyperlink, then it shows the code and the user can copy and paste it to the console, if they consider it safe to run.

Note that depending on your version of RStudio, the behavior can change.

Draw a banner-like box in the console

Description

Draw a banner-like box in the console

Usage

list_border_styles()

boxx(
  label,
  header = "",
  footer = "",
  border_style = "single",
  padding = 1,
  margin = 0,
  float = c("left", "center", "right"),
  col = NULL,
  background_col = NULL,
  border_col = col,
  align = c("left", "center", "right"),
  width = console_width()
)

Arguments

Details

Defaults

boxx("Hello there!")

#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            

Change border style

boxx("Hello there!", border_style = "double")

#> ╔══════════════════╗                                                            
#> ║                  ║                                                            
#> ║   Hello there!   ║                                                            
#> ║                  ║                                                            
#> ╚══════════════════╝                                                            

Multiple lines

boxx(c("Hello", "there!"), padding = 1)

#> ┌────────────┐                                                                  
#> │            │                                                                  
#> │   Hello    │                                                                  
#> │   there!   │                                                                  
#> │            │                                                                  
#> └────────────┘                                                                  

Padding

boxx("Hello there!", padding = 1)
boxx("Hello there!", padding = c(1, 5, 1, 5))

#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            
#> ┌──────────────────────┐                                                        
#> │                      │                                                        
#> │     Hello there!     │                                                        
#> │                      │                                                        
#> └──────────────────────┘                                                        

Floating

boxx("Hello there!", padding = 1, float = "center")
boxx("Hello there!", padding = 1, float = "right")

#>                           ┌──────────────────┐                                  
#>                           │                  │                                  
#>                           │   Hello there!   │                                  
#>                           │                  │                                  
#>                           └──────────────────┘                                  
#>                                                   ┌──────────────────┐          
#>                                                   │                  │          
#>                                                   │   Hello there!   │          
#>                                                   │                  │          
#>                                                   └──────────────────┘          

Text color

boxx(col_cyan("Hello there!"), padding = 1, float = "center")

#>                           ┌──────────────────┐                                  
#>                           │                  │                                  
#>                           │   Hello there!   │                                  
#>                           │                  │                                  
#>                           └──────────────────┘                                  

Background color

boxx("Hello there!", padding = 1, background_col = "brown")
boxx("Hello there!", padding = 1, background_col = bg_red)

#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            
#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            

Border color

boxx("Hello there!", padding = 1, border_col = "green")
boxx("Hello there!", padding = 1, border_col = col_red)

#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            
#> ┌──────────────────┐                                                            
#> │                  │                                                            
#> │   Hello there!   │                                                            
#> │                  │                                                            
#> └──────────────────┘                                                            

Label alignment

boxx(c("Hi", "there", "you!"), padding = 1, align = "left")
boxx(c("Hi", "there", "you!"), padding = 1, align = "center")
boxx(c("Hi", "there", "you!"), padding = 1, align = "right")

#> ┌───────────┐                                                                   
#> │           │                                                                   
#> │   Hi      │                                                                   
#> │   there   │                                                                   
#> │   you!    │                                                                   
#> │           │                                                                   
#> └───────────┘                                                                   
#> ┌───────────┐                                                                   
#> │           │                                                                   
#> │     Hi    │                                                                   
#> │   there   │                                                                   
#> │    you!   │                                                                   
#> │           │                                                                   
#> └───────────┘                                                                   
#> ┌───────────┐                                                                   
#> │           │                                                                   
#> │      Hi   │                                                                   
#> │   there   │                                                                   
#> │    you!   │                                                                   
#> │           │                                                                   
#> └───────────┘                                                                   

A very customized box

star <- symbol$star
label <- c(paste(star, "Hello", star), "  there!")
boxx(
  col_white(label),
  border_style="round",
  padding = 1,
  float = "center",
  border_col = "tomato3",
  background_col="darkolivegreen"
)

#>                            ╭───────────────╮                                    
#>                            │               │                                    
#>                            │   ★ Hello ★   │                                    
#>                            │     there!    │                                    
#>                            │               │                                    
#>                            ╰───────────────╯                                    

About fonts and terminal settings

The boxes might or might not look great in your terminal, depending on the box style you use and the font the terminal uses. We found that the Menlo font looks nice in most terminals an also in Emacs.

RStudio currently has a line height greater than one for console output, which makes the boxes ugly.

List all available spinners

Description

List all available spinners

Usage

list_spinners()

Value

Character vector of all available spinner names.

See Also

Other spinners: demo_spinners(), get_spinner(), make_spinner()

Examples

list_spinners()
get_spinner(list_spinners()[1])

Create a new ANSI style

Description

Create a function that can be used to add ANSI styles to text.

Usage

make_ansi_style(..., bg = FALSE, grey = FALSE, colors = num_ansi_colors())

Arguments

Details

The ... style argument can be any of the following:

• A cli ANSI style function of class cli_ansi_style. This is returned as is, without looking at the other arguments.

• An R color name, see grDevices::colors().

• A 6- or 8-digit hexadecimal color string, e.g. ⁠#ff0000⁠ means red. Transparency (alpha channel) values are ignored.

• A one-column matrix with three rows for the red, green and blue channels, as returned by grDevices::col2rgb().

make_ansi_style() detects the number of colors to use automatically (this can be overridden using the colors argument). If the number of colors is less than 256 (detected or given), then it falls back to the color in the ANSI eight color mode that is closest to the specified (RGB or R) color.

Value

A function that can be used to color (style) strings.

See Also

Other ANSI styling: ansi-styles, combine_ansi_styles(), num_ansi_colors()

Examples

make_ansi_style("orange")
make_ansi_style("#123456")
make_ansi_style("orange", bg = TRUE)

orange <- make_ansi_style("orange")
orange("foobar")
cat(orange("foobar"))

Create a spinner

Description

Create a spinner

Usage

make_spinner(
  which = NULL,
  stream = "auto",
  template = "{spin}",
  static = c("dots", "print", "print_line", "silent")
)

Arguments

Value

A cli_spinner object, which is a list of functions. See its methods below.

cli_spinner methods:

• ⁠$spin()⁠: output the next frame of the spinner.

• ⁠$finish()⁠: terminate the spinner. Depending on terminal capabilities this removes the spinner from the screen. Spinners can be reused, you can start calling the ⁠$spin()⁠ method again.

All methods return the spinner object itself, invisibly.

The spinner is automatically throttled to its ideal update frequency.

Examples

Default spinner

sp1 <- make_spinner()
fun_with_spinner <- function() {
  lapply(1:100, function(x) { sp1$spin(); Sys.sleep(0.05) })
  sp1$finish()
}
ansi_with_hidden_cursor(fun_with_spinner())

Spinner with a template

sp2 <- make_spinner(template = "Computing {spin}")
fun_with_spinner2 <- function() {
  lapply(1:100, function(x) { sp2$spin(); Sys.sleep(0.05) })
  sp2$finish()
}
ansi_with_hidden_cursor(fun_with_spinner2())

Custom spinner

sp3 <- make_spinner("simpleDotsScrolling", template = "Downloading {spin}")
fun_with_spinner3 <- function() {
  lapply(1:100, function(x) { sp3$spin(); Sys.sleep(0.05) })
  sp3$finish()
}
ansi_with_hidden_cursor(fun_with_spinner3())

See Also

Other spinners: demo_spinners(), get_spinner(), list_spinners()

Match a selector to a container stack

Description

Match a selector to a container stack

Usage

match_selector(sels, cnts)

Arguments

Match a selector node to a container

Description

Match a selector node to a container

Usage

match_selector_node(node, cnt)

Arguments

Pluralization helper functions

Description

Pluralization helper functions

Usage

no(expr)

qty(expr)

Arguments

See Also

Other pluralization: pluralization, pluralize()

Examples

nfile <- 0; cli_text("Found {no(nfile)} file{?s}.")

#> Found no files.

nfile <- 1; cli_text("Found {no(nfile)} file{?s}.")

#> Found 1 file.

nfile <- 2; cli_text("Found {no(nfile)} file{?s}.")

#> Found 2 files.

Detect the number of ANSI colors to use

Description

Certain Unix and Windows terminals, and also certain R GUIs, e.g. RStudio, support styling terminal output using special control sequences (ANSI sequences).

num_ansi_colors() detects if the current R session supports ANSI sequences, and if it does how many colors are supported.

Usage

num_ansi_colors(stream = "auto")

detect_tty_colors()

Arguments

Details

The detection mechanism is quite involved and it is designed to work out of the box on most systems. If it does not work on your system, please report a bug. Setting options and environment variables to turn on ANSI support is error prone, because they are inherited in other environments, e.g. knitr, that might not have ANSI support.

If you want to turn off ANSI colors, set the NO_COLOR environment variable to a non-empty value.

The exact detection mechanism is as follows:

1. If the cli.num_colors options is set, that is returned.

2. If the R_CLI_NUM_COLORS environment variable is set to a non-empty value, then it is used.

3. If the crayon.enabled option is set to FALSE, 1L is returned. (This is for compatibility with code that uses the crayon package.)

4. If the crayon.enabled option is set to TRUE and the crayon.colors option is not set, then the value of the cli.default_num_colors option, or if it is unset, then 8L is returned.

5. If the crayon.enabled option is set to TRUE and the crayon.colors option is also set, then the latter is returned. (This is for compatibility with code that uses the crayon package.)

6. If the NO_COLOR environment variable is set, then 1L is returned.

7. If we are in knitr, then 1L is returned, to turn off colors in .Rmd chunks.

8. If stream is "auto" (the default) and there is an active sink (either for "output" or "message"), then we return 1L. (In theory we would only need to check the stream that will be be actually used, but there is no easy way to tell that.)

9. If stream is not "auto", but it is stderr() and there is an active sink for it, then 1L is returned. (If a sink is active for "output", then R changes the stdout() stream, so this check is not needed.)

10. If the cli.default_num_colors option is set, then we use that.

11. If R is running inside RGui on Windows, or R.app on macOS, then we return 1L.

12. If R is running inside RStudio, with color support, then the appropriate number of colors is returned, usually 256L.

13. If R is running on Windows, inside an Emacs version that is recent enough to support ANSI colors, then the value of the cli.default_num_colors option, or if unset 8L is returned. (On Windows, Emacs has isatty(stdout()) == FALSE, so we need to check for this here before dealing with terminals.)

14. If stream is not the standard output or standard error in a terminal, then 1L is returned.

15. Otherwise we use and cache the result of the terminal color detection (see below).

The terminal color detection algorithm:

1. If the COLORTERM environment variable is set to truecolor or ⁠24bit⁠, then we return 16 million colors.

2. If the COLORTERM environment variable is set to anything else, then we return the value of the cli.num_default_colors option, 8L if unset.

3. If R is running on Unix, inside an Emacs version that is recent enough to support ANSI colors, then the value of the cli.default_num_colors option is returned, or 8L if unset.

4. If we are on Windows in an RStudio terminal, then apparently we only have eight colors, but the cli.default_num_colors option can be used to override this.

5. If we are in a recent enough Windows 10 terminal, then there is either true color (from build 14931) or 256 color (from build 10586) support. You can also use the cli.default_num_colors option to override these.

6. If we are on Windows, under ConEmu or cmder, or ANSICON is loaded, then the value of cli.default_num_colors, or 8L if unset, is returned.

7. Otherwise if we are on Windows, return 1L.

8. Otherwise we are on Unix and try to run ⁠tput colors⁠ to determine the number of colors. If this succeeds, we return its return value. If the TERM environment variable is xterm and tput returned 8L, we return 256L, because xterm compatible terminals tend to support 256 colors (https://github.com/r-lib/crayon/issues/17) You can override this with the cli.default_num_colors option.

9. If TERM is set to dumb, we return 1L.

10. If TERM starts with screen, xterm, or vt100, we return 8L.

11. If TERM contains color, ansi, cygwin or linux, we return 8L.

12. Otherwise we return 1L.

Value

Integer, the number of ANSI colors the current R session supports for stream.

See Also

Other ANSI styling: ansi-styles, combine_ansi_styles(), make_ansi_style()

Examples

num_ansi_colors()

Parse a CSS3-like selector

Description

This is the rather small subset of CSS3 that is supported:

Usage

parse_selector(x)

Arguments

Details

Selectors:

• Type selectors, e.g. input selects all ⁠<input>⁠ elements.

• Class selectors, e.g. .index selects any element that has a class of "index".

• ID selector. ⁠#toc⁠ will match the element that has the ID "toc".

Combinators:

• Descendant combinator, i.e. the space, that combinator selects nodes that are descendants of the first element. E.g. ⁠div span⁠ will match all ⁠<span>⁠ elements that are inside a ⁠<div>⁠ element.

About cli pluralization

Description

About cli pluralization

Introduction

cli has tools to create messages that are printed correctly in singular and plural forms. This usually requires minimal extra work, and increases the quality of the messages greatly. In this document we first show some pluralization examples that you can use as guidelines. Hopefully these are intuitive enough, so that they can be used without knowing the exact cli pluralization rules.

If you need pluralization without the semantic cli functions, see the pluralize() function.

Examples

Pluralization markup

In the simplest case the message contains a single {} glue substitution, which specifies the quantity that is used to select between the singular and plural forms. Pluralization uses markup that is similar to glue, but uses the ⁠{?⁠ and ⁠}⁠ delimiters: