Movatterモバイル変換

Title:	Helpers for Developing Command Line Interfaces
Version:	3.6.5
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-04-22 12:00:18 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-04-23 13:50: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árdigabor@posit.co

Other contributors:

• Hadley Wickham [contributor]

• Kirill Müller [contributor]

• Salim Brüggemannsalim-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 athttps://github.com/r-lib/cli/issues

ANSI colored text

Description

cli has a number of functions to color and style text at the commandline. 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 ownsettings for how to show them.col_none() is the default color, thisis 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 thesame 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, canvary in appearance, depending on terminal settings.bg_none() thethe default background color, this is useful in a substring of abackground-colored string.

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

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

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

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

• style_dim() (orstyle_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 usingpaste0() before adding the style.

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

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

Value

An ANSI string (classcli_ansi_string), that contains ANSIsequences, if the current platform supports them. You can simplyusecat() 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 properlycat(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_cyancat(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 removedstyle_italic(col_green(paste0(  "italic before, ",  style_no_italic("normal here, "),  "italic after")))# avoiding  color for substringstyle_italic(col_red(paste(  "red before",  col_none("not red between"),  "red after")))

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", withstyle = "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 isNA_character_ if any elements inxareNA.

See Also

glue_collapse in the glue package inspired this function.

Examples

ansi_collapse(letters)# truncateansi_collapse(letters, trunc = 5)# head styleansi_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 withboxx(), 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 specifiedwidth, it will betruncated usingansi_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 1foo 2foo 3foo 4foo 5     │                          #> │foo 6foo 7foo 8foo 9foo 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()

Likebase::grep() andbase::grepl(), but for ANSI strings

Description

First ANSI sequences will be stripped withansi_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 ifuseBytes = TRUE), and not graphemes.

Unlikebase::grep() andbase::grepl() these functions do not specialcase factors.

Bothpattern andx are converted to UTF-8.

Value

The same asbase::grep() andbase::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 someANSI 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 supportedansi_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, itdoes 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 forevaluating 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 ofansi_html()

Description

CSS styles for the output ofansi_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 areCSS selectors. It has aformat() andprint() methods, which youcan 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 ofutf8_nchar(). By default itcounts 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 charactervector.

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

Likebase::nzchar(), but for ANSI strings

Description

Likebase::nzchar(), but for ANSI strings

Usage

ansi_nzchar(x, ...)

Arguments

Examples

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

Perl compatible regular expression that matches ANSI escapesequences

Description

Don't forget to useperl = TRUE when using this withgrepl() andfriends.

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, byremoving duplicate and empty tags.

Usage

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

Arguments

Value

Simplifiedcli_ansi_string vector.

Labels a character vector as containing ANSI control codes.

Description

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

Usage

ansi_string(x)

Arguments

Value

Acli_ansi_string object, a subclass ofcharacter, with the same length and contentsasx.

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 classcli_ansi_string class, this is also droppedfrom the result.

Usage

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

Arguments

Value

The cleaned up string. Note thatansi_strip() always dropsthecli_ansi_string class, even ifsgr 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 ofbase::strsplit().It works almost exactly like the original, but keeps the colors in thesubstrings.

Usage

ansi_strsplit(x, split, ...)

Arguments

Value

A list of the same length asx, thei-th element ofwhich contains the vector of splits ofx[i]. ANSI styles areretained.

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 colorcat(ansi_strsplit(str, "[-]+")[[1]], sep = "\n")strsplit(ansi_strip(str), "[-]+")# split to characters, keep colorcat(ansi_strsplit(str, "")[[1]], "\n", sep = " ")strsplit(ansi_strip(str), "")

Truncate an ANSI string

Description

This function is similar tobase::strtrim(), but works correctly withANSI styled strings. It also adds... (or the corresponding Unicodecharacter if Unicode characters are allowed) to the end of truncatedstrings.

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 tobase::strwrap(), but works on ANSIstyled strings, and leaves the styling intact.

Usage

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

Arguments

Value

Ifsimplify isFALSE, 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 ofbase::substr().It works exactly like the original, but keeps the colorsin the substrings. The ANSI escape sequences are ignored whencalculating the positions within the string.

Usage

ansi_substr(x, start, stop)

Arguments

Value

Character vector of the same length asx, containingthe 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 ofbase::substring().It works exactly like the original, but keeps the colors in thesubstrings. The ANSI escape sequences are ignored whencalculating the positions within the string.

Usage

ansi_substring(text, first, last = 1000000L)

Arguments

Value

Character vector of the same length asx, containingthe 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 totoupper(),tolower() andchartr(), 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 asx, containingthe 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 tobase::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   "))

The built-in CLI theme

Description

This theme is always active, and it is at the bottom of the themestack. Seethemes.

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 andstrong 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 aroundcat(): most importantlythey all setsep = "", andcat_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 inexpr, and emit them togetherin a single message. This is useful if you want to built a largerpiece of output from multiple⁠cli_*⁠ calls.

Usage

cli(expr)

Arguments

Details

Use this function to build a more complex piece of CLI that would notmake 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.

cli environment variables and options

Description

cli environment variables and options

User facing configuration

These are environment variables and options that users may set, to modifythe behavior of cli.

Hyperlinks

cli uses ANSI escape sequences to create hyperlinks.Specifically, cli createsOSC 8 hyperlinks that have this syntax:

OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST

Under the hood,style_hyperlink() is the helper that forms these links, but it is more common to request them indirectly via inline markup (documented inhelp("links")).

R_CLI_HYPERLINK_MODE

Set toposix to force generating POSIX compatible ANSI hyperlinks.This is about the specific operating system command (OSC) and string terminator (ST) used in hyperlinks.

If not set, then RStudio compatible links are generated. This is atemporary crutch until RStudio handles POSIX hyperlinks correctly, andafter that it will be removed.

cli.hyperlink option andR_CLI_HYPERLINKS env var

Set this option or env var totrue,TRUE orTrue to tell cli that the terminal supports ANSI hyperlinks.Leave this configuration unset (or set to anything else) when there is no hyperlink support.Specifically, this configuration indicates the support for URL and file hyperlinks, requested via markup like⁠{.href url}⁠ or⁠{.file path/file}⁠.(Below we describe the configuration that indicates support for even more specialized types of hyperlinks.)

The optioncli.hyperlink takes precedence over theR_CLI_HYPERLINKS env var.

⁠cli.hyperlink_*⁠ options and⁠R_CLI_HYPERLINK_*⁠ env vars

cli supports a few special types of hyperlink that go beyond pointing to, e.g., a webpage or a file.These specialized hyperlinks cause R-specific actions to happen, such as executing a bit of R code or opening specific documentation.

Set the relevant option or env var totrue,TRUE, orTrue to tell cli that the terminal is capable of implementing these specialized behaviours.Leave this configuration unset (or set to anything else) when there is no support for a specific type of hyperlink.

In all cases, the option takes priority over the corresponding env var.

⁠cli.hyperlink_*_url_format⁠ options and⁠R_CLI_HYPERLINK_*_URL_FORMAT⁠ env vars

Recall the overall structure of cli's hyperlinks:

OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST

TheURI part has a default format for each type of hyperlink, but it is possible to provide a custom format via an option or an env var.If defined, the option takes priority over the env var.

A format must be a glue-like template with the relevant placeholder in curly braces (code,topic orvignette).

Here's an example of a custom URI format for runnable code, which is useful in an integrated Positron terminal:

positron://positron.positron-r/cli?command=x-r-run:{code}

(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g.ide:run:{code}.)

The default handling for file hyperlinks is geared towards the expectations of RStudio and can't really be expressed as a URI format, but it's approximately⁠file://{path}⁠, plus possibly passingline andcol (yes, it really iscol, notcolumn) in the⁠OPTIONAL PARAMS⁠ part of the OSC 8 hyperlink.

A custom format can be provided for file hyperlinks and the relevant placeholders arepath,line, andcolumn.Examples of custom file hyperlink formats:

positron://file{path}:{line}:{column}vscode://file{path}:{line}:{column}txmt://open?url=file://{path}&line={line}&column={column}

It's OK if the format includes onlypath.

User facing environment variables

NO_COLOR

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

ESS_BACKGROUND_MODE

Set this environment variable tolight ordark to indicate dark modein Emacs. Once https://github.com/emacs-ess/ESS/pull/1178 is merged, ESSwill set this automatically.

R_CLI_DYNAMIC

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

R_CLI_NUM_COLORS

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

User facing options

cli.ansi

Set totrue,TRUE orTrue to assume a terminal that supports ANSIcontrol sequences.Set to anything else to assume a non-ANSI terminal.Seeis_ansi_tty().

cli.condition_unicode_bullets

TRUE orFALSE to force turn on or off the Unicode symbols when printingconditions. E.g. informat_error(),format_warning(),format_message() andalso incli_abort(),cli_warn() andcli_inform().

cli.condition_width

Integer scalar (orInf) to set the console width when cli is formattingerrors, warnings or messages informat_error(),format_warning() andformat_message(). When formatting conditions this option takes precedenceovercli.width.

cli.default_handler

General handler function for all cli conditions.Seehttps://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 colorsis not already set by

• thecli.num_colors option,

• theR_CLI_NUM_COLORS environment variable,

• thecrayon.enabled andcrayon.colors options,

• theNO_COLOR environment variable,

• theknitr.in.progress option,

• asink() call for the stream.

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

• ifcrayon.enabled isTRUE, butcrayon.colors is not,

• in Emacs on Windows,

• in terminals.

Seenum_ansi_colors(). See also thecli.num_colors option.

cli.dynamic

Set toTRUE to assume a dynamic terminal, that supports⁠\r⁠.Set to anything else to assume a non-dynamic terminal.Seeis_dynamic_tty().

cli.hide_cursor

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

cli.ignore_unknown_rstudio_theme

Set toTRUE to omit a warning for an unknown RStudio theme incode_highlight().

cli.num_colors

Number of ANSI colors. Seenum_ansi_colors(). See also thecli.default_num_colors option.

cli.message_class

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

cli.progress_bar_style

Progress bar style.Seecli_progress_styles().

cli.progress_bar_style_ascii

Progress bar style on ASCII consoles.Seecli_progress_styles().

cli.progress_bar_style_unicode

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

cli.progress_clear

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

cli.progress_demo_live

Whethercli_progress_demo() should show a live demo, or just record theprogress bar frames.

cli.progress_format_download

Default format string fordownload progress bars.

cli.progress_format_download_nototal

Default format string fordownload progress bars with unknown totals.

cli.progress_format_iterator

Default format string foriterator progress bars.

cli.progress_format_iterator_nototal

Default format string foriterator progress bars with unknown total numberof progress units.

cli.progress_format_tasks

Default format string fortasks progress bars.

cli.progress_format_tasks_nototal

Default format string fortasks progress bars with unknown totals.

cli.progress_handlers

Progress handlers to try.Seecli_progress_builtin_handlers().

cli.progress_handlers_force

Progress handlers that will always be used, even if another handlerwas already selected.Seecli_progress_builtin_handlers().

cli.progress_handlers_only

Progress handlers to force, ignoring handlers set incli.progress_handlers andcli.progress_handlers_force.Seecli_progress_builtin_handlers().

cli.progress_say_args

Command line arguments for thesay progress handlers.Seecli_progress_builtin_handlers().

cli.progress_say_command

External command to use in thesay progress handler.Seecli_progress_builtin_handlers().

cli.progress_say_frequency

Minimum delay betweensay calls in thesay progress handler.say ignores very frequent updates, to keep the speech comprehensible.Seecli_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 ofthis delay has passed.

cli.spinner

Default spinner to use, seeget_spinner().

cli.spinner_ascii

Default spinner to use on ASCII terminals, seeget_spinner().

cli.spinner_unicode

Default spinner to use on Unicode terminals, seeget_spinner().

cli.theme

Default cli theme, in addition to the built-in theme.This option in intended for the package developers.Seethemes andstart_app().

cli.theme_dark

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

cli.unicode

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

cli.user_theme

cli user theme.This option is intended for end users.Seethemes.

cli.warn_inline_newlines

Whether to emit a warning when cli replaces newline characters withspaces within a{.class } inline style.Defaults toFALSE.

cli.width

Terminal width to assume.If not set, then it is auto-detected.Seeconsole_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, ifcli.width is not set.

Internal configuration

These environment variables and options are for cli developers. Usersshould 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 aboutcli_end() calls when there is no container to close.

CLI_NO_BUILTIN_THEME

Set it totrue 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 totrue 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 controlsequences.

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 totrue 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.Seenum_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 hyperlinksupport 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, wheninterpolating 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 supportedby cli, when the new options are not set.Seenum_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.Seenum_ansi_colors().

crayon.hyperlink

Whether to assume ANSI hyperlink support.Seeansi_has_hyperlink_support().

knitr.in.progress

Used to detect knitr when detecting interactive sessions and ANSI colorsupport.

rstudio.notebook.executing

Used to detect knitr when detecting interactive sessions.

Signal an error, warning or message with a cli formattedmessage

Description

These functions let you create error, warning or diagnosticmessages 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_trace()` to see where the error occurred.

len <- 26idx <- 100cli_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_trace()` to see where the error occurred.

See Also

These functions supportinline 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 <- 11tbld <- prettyunits::pretty_sec(5.6)cli_alert_success("Built {.emph {nbld}} status report{?s} in {tbld}.")

#>✔ Built11 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 setwrap = 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 supportsinline 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 supportsinline 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 orpackage 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 oftext, and can be themed.cli creates adiv element of classbullets for the whole bullet list.Each item is anotherdiv element of class⁠bullet-<name>⁠, where⁠<name>⁠ is the name of the entry intext. Entries intext withouta name create adiv element of classbullet-empty, and if thename is a single space character, the class isbullet-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, likecli_alert_success().

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

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

• i: Info item, likecli_alert_info().

You can define new item type by simply defining theming for thecorresponding⁠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 supportsinline 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 tocli_bullets(), but it doesnot 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 supportinline markup.

Seecli_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 adiv with classcode and then callscli_verbatim() to output code lines. The builtin theme formats thesecontainers specially. In particular, it adds syntax highlighting tovalid 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 currentlyopen 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 createa plain data frame from it, index it with an empty bracket:cli_debug_doc()[].

To see all currently active themes, useapp$themes, e.g. for thedefault app:default_app()$themes.

Value

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

See Also

cli_sitrep(). To debug containers, you can set theCLI-DEBUG_BAD_END environment variable totrue, and then cli willwarn when it cannot find the specified container to close (or anycontained 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

Seecontainers. Acli_div container is special, because it mayadd 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 acli_div() is closed automatically when the callingframe 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, seecontainers.

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 supportsinline 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 explicitlyclose them. Closing a container also closes all of its nestedcontainers.

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

Omittingid

Ifid 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 internalcli:::cli_debug_doc() function to see thecurrently open containers.

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

#> <cli document>                                                                  #> <body>                                                                #> <div> +theme                                                         #> <par>

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 ...}⁠ inlinestyle.⁠{.val {expr}}⁠ callscli_format() automatically on the valueofexpr, 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 / 7cli_text("{.val {nums}}")

#>0.142857142857143,0.285714285714286,0.428571428571429,                        #>0.571428571428571, and0.714285714285714

Styling with themes

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

#>0.143,0.286,0.429,0.571, and0.714

It is possible to define new S3 methods forcli_format and thenthese 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 informat() S3 methods. Then theprint() method of the class can be easily defined in terms of such aformat() 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 outnew_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}")

#>                                                                                 #>──Header1──────────────────────────────────────────────────────────          #>                                                                                 #> ──Header2 ──                                                                  #>                                                                                 #> ── Header3

See Also

These functions supportsinline 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, seecontainers.

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 supportsinline 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 callsstart_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. Seethemes.

• 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, orNA if the style is not used.

See Also

themes

Ordered CLI list

Description

An ordered list is a container, seecontainers.

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 onefun <- 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 supportsinline 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 outputis produced in another process, then it is not relevant.

Usage

cli_output_connection()

Details

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

Value

Connection object.

CLI paragraph

Description

The builtin theme leaves an empty line between paragraphs.See alsocontainers.

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 bythecli_progress_message() andcli_progress_step() functions,because they have a better default behavior.

Typically you callcli_process_start() to start the process, and thencli_process_done() when it is done. If an error happens beforecli_process_done() is called, then cli automatically shows the messagefor 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 dothe opposite: callcli_process_start() withon_exit = "done", andin the error handler callcli_process_failed(). cli will automaticallycallcli_process_done() on successful termination, when the callingfunction finishes.

See examples below.

Value

Id of the status bar container.

See Also

This function supportsinline markup.

Thecli_progress_message() andcli_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 defaultfun <- 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 defaultfun2 <- 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!

Usecli_progress_along() in a mapping function or in a for loop, to add aprogress bar. It usescli_progress_bar() internally.

Usage

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

Arguments

Details

for loop

Afor loop withcli_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 usebreak in thefor loop, you probably want toterminate 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 tolength(x) that triggers progressupdates as you iterate over it.

See Also

This function supportsinline 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 thecli progress bars.

cli_progress_bar() creates a new progress bar.

cli_progress_update() updates the state of a progress bar, andpotentially 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, andcli_progress_done() terminatesit.

It is good practice to always set thename argument, to make theprogress 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()

Unknowntotal

Iftotal is not known, then cli shows a different progress bar.Note that you can also settotal incli_progress_update(), if itnot 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, ifthe terminal supports this. If you want to change this, use theclear argument ofcli_progress_bar(), or thecli.progress_clearglobal option (seecli-config) to change this.

(In the cli documentation we usually setcli.progress_clear toFALSE,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 avoidit for quick loops. By default a progress bar is only shown after twoseconds, or after half of that if less than 50% of the iterations arecomplete. You can change the two second default with thecli.progress_show_after global option (seecli-config).

(In the cli documentation we usually setcli.progress_show_after to0 (zero seconds), so progress bars are shown immediately.)

In this example we only show the progress bar after one second, becausemore 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()

Thecurrent progress bar

By default cli sets the new progress bar as thecurrent progress barof the calling function. The current progress bar is the default onein cli progress bar operations. E.g. if no progress bar id is suppliedincli_progress_update(), then the current progress bar is updated.

Every function can only have a singlecurrent progress bar, and if anew one is created, then the previous one (if any) is automaticallyterminated. The current progress bar is also terminated when the functionthat created it exits. Thanks to these rules, most often you don't needto explicitly deal with progress bar ids, and you don't need toexplicitly callcli_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, cliwill remove the progress bar temporarily, emit the output, and thenrestores 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 alsocli_progress_output(), which sends text for the currentprogress handler. E.g. in a Shiny app it will send the output to theShiny progress bar, as opposed to thecli_alert() etc. cli functionswhich will print the text to the console.

Custom formats

In addition to the builtin types, you can also specify a customformat string. In this caseprogress variablesare probably useful to avoid calculating some progress bar quantitieslike the elapsed time, of the ETA manually. You can also use your ownvariables 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() returnsTRUE, invisibly, always.

See Also

These functions supportinline markup.

cli_progress_message() andcli_progress_step() for simplerprogress 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 theseoptions to a character vector, the names of the built-in cli handlers youwant to use:

• Ifcli.progress_handlers_only is set, then these handlers are used,without considering others and without checking if they are able tohandle a progress bar. This option is mainly intended for testingpurposes.

• The handlers named incli.progress_handlers are checked if they areable to handle the progress bar, and from the ones that are, the firstone is selected. This is usually the option that the end use would wantto set.

• The handlers named incli.progress_handlers_force are always appendedto the ones selected viacli.progress_handlers. This option is usefulto add an additional handler, e.g. a logger that writes to a file.

Value

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

The built-in progress handlers

cli

Use cli's internal status bar, the last line of the screen, to show theprogress 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 withtime stamps. This handler is always able to handle all progress bars.

progressr

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

rstudio

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

say

Use the macOSsay command to announce progress events in speech (type⁠man say⁠ on a terminal for more info). Set thecli.progress_say_frequencyoption to set the minimum delay betweensay invocations, the default isthree seconds. This handler is available on macOS, if thesay command ison 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 thisto select a voice on macOS,

• cli_progress_say_command: external command to run,

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

shiny

Useshiny'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 theprogress 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 classcli_progress_demo, which has a print and aformat method for pretty printing. Thelines entry contains theoutput 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 noupdate is due. When the progress message is terminated, it is removedfrom the screen by default.

Note that the message can be dynamic: if you update it withcli_progress_update(), then cli uses the current values in the stringsubstitutions.

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 supportsinline 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 currentlyactive progress bars. (These do not currently include the progressbars 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 viacli_text(), so all cli features can beused 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 beable 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 supportsinline 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 withspinner = TRUE,but note that this will only work if you callcli_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.Sincecli_progress_step() show that message immediately, we needto initializemsg 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/orunsuccessful 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 supportsinline 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 (ifis_utf8_output() isTRUE), thecli_progress_bar_style_unicode andcli_progress_bar_styleoptions are used.

On ASCII terminals (ifis_utf8_output() isFALSE), thecli_pgoress_bar_style_ascii andcli_progress_bar_style optionsare 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 elementscomplete,incomplete and potentiallycurrent.

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 theline-typeproperty. Possible values are:

• "single": (same as1), a single line,

• "double": (same as2), 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 supportsinline 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 thecli.unicode option is set and itsvalue. Seeis_utf8_output().

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

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

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

• num_colors: number of ANSI colors. Seenum_ansi_colors().

• console_with: detected console width.

Usage

cli_sitrep()

Value

Named list with entries listed above. It has acli_sitrepclass, with aprint() andformat() method.

Examples

cli_sitrep()

Update the status bar (superseded)

Description

The⁠cli_status_*()⁠ functions are superseded bythecli_progress_message() andcli_progress_step() functions,because they have a better default behavior.

The status bar is the last line of the terminal. cli apps can use thisto show status information, progress bars, etc. The status bar is keptintact 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

Usecli_status_clear() to clear the status bar.

Often status messages are associated with processes. E.g. the app startsdownloading a large file, so it sets the status bar accordingly. Once thedownload is done (or has failed), the app typically updates the status baragain. cli automates much of this, via themsg_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 supportinline markup.

Thecli_progress_message() andcli_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 bythecli_progress_message() andcli_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

Thecli_progress_message() andcli_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 bythecli_progress_message() andcli_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 supportsinline markup.

Thecli_progress_message() andcli_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 forlonger paragraphs. Seecli_alert() for shorter status messages.

Usage

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

Arguments

Details

Text wrapping

Text is wrapped to the console width, seeconsole_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

Acli_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 useinline markup, as usual.

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

#> The `cli_text()` function in thecli package.

Interpolation

String interpolation via glue works as usual. Interpolated vectorsare 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 thecli package.

Multiple arguments

Arguments are concatenated.

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

#> This will all be one sentence.

Containers

You can usecli_text() within clicontainers.

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 thefirst item                                                            #> • Second item.                                                                  #> Still thesecond item

See Also

This function supportsinline 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, seecontainers.

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 supportsinline 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 ofcollapsing the vector into a string, see an example below.

The style is added as an attribute, so operations that removeattributes 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.

Syntax highlight R code

Description

Syntax highlight R code

Usage

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

Arguments

Details

Seecode_theme_list() for the default syntax highlighting theme andhow to change it.

Ifcode does not parse, then it is returned unchanged and acli_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 forbracket, 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: theNULL 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:

• Ifcli.code_theme is set, it is used.

• Otherwise if R is running in RStudio andcli.code_theme_rstudio isset, then it is used.

• Otherwise if T is not running in RStudio andcli.code_theme_terminalis set, then it is used.

You can set these options to the name of a built-in theme, or to listthat specifies a custom theme. Seecode_theme_list() for the listof 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 functionthat can be called on strings to style them.

Usage

combine_ansi_styles(...)

Arguments

Details

It does not usually make sense to combine two foregroundcolors (or two background colors), because only the first oneapplied 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 namesalert <- combine_ansi_styles("bold", "red4")cat(alert("Warning!"), "\n")## Or style functionsalert <- combine_ansi_styles(style_bold, col_red, bg_cyan)cat(alert("Warning!"), "\n")## Combine a composite stylealert <- combine_ansi_styles(  "bold",  combine_ansi_styles("red", bg_cyan))cat(alert("Warning!"), "\n")

Determine the width of the console

Description

It uses thecli.width option, if set. Otherwise it tries todetermine the size of the terminal or console window.

Usage

console_width()

Details

These are the exact rules:

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

• If thecli.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 thetty_size() function to query theterminal 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 theRSTUDIO_CONSOLE_WIDTHenvironment variable is used. If the build pane is resized, then thisenvironment variable is not accurate any more, and the output mightget garbled.

• We arenot using theRSTUDIO_CONSOLE_WIDTH environment variableif we are in the RStudio console.

If we cannot determine the size of the terminal or console window, thenwe use thewidth option. If thewidth option is not set, thenwe 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 followingcommands create container elements:cli_div(),cli_par(), the listelements:cli_ul(),cli_ol(),cli_dl(), and list items arecontainers as well:cli_li().

Details

Themes

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

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 withcli_end(). For convenience,by default they are closed automatically when the function that createdthem terminated (either regularly or with an error). The defaultbehavior 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 internalcli:::cli_debug_doc() function to see thecurrently open containers.

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

#>                                                                                 #> <cli document>                                                                  #> <body>                                                                #> <div> +theme                                                         #> <par>

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 callingdiff -u at the commandline.

Usage

diff_chr(old, new, max_dist = Inf)

Arguments

Value

A list that is acli_diff_chr object, with aformat() and aprint() method. You can also access its members:

• old andnew are the original inputs,

• lcs is a data frame of LCS edit that transformold intonew.

Thelcs data frame has the following columns:

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

• offset: offset inold for matches and deletions, offset innewfor insertions.

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

• old_offset: offset inoldafter the operation.

• new_offset: offset innewafter the operation.

See Also

The diffobj package for a much more comprehensive set ofdiff-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 acli_diff_str object and also acli_diff_chr object, seediff_str for the details about itsstructure.

See Also

The diffobj package for a much more comprehensive set ofdiff-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. Pleaseopen an issue athttps://github.com/r-lib/cli/issues and do not forgetto tell us the details of your platform and terminal or GUI.

How do I turn off ANSI colors and styles?

Set theNO_COLOR environment variable to a non-empty value. You can dothis in your.Renviron file (useusethis::edit_r_environ()).

If you want to do this for testthat tests, then consider using the 3rdedition on testthat, which does turn off ANSI styling automaticallyinsidetest_that().

cli does not show the output beforefile.choose()

Try callingflush.console() to flush the console, beforefile.choose(). If flushing does not work and you are in RStudio, thenit is probably this RStudio bug:https://github.com/rstudio/rstudio/issues/8040 See more details athttps://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 Unicodestandard. Some software treats them as narrow (one column on thescreen), other as wide (two columns). In some terminal emulators (forexample iTerm2), you can configure the preferred behavior.

Unfortunately the box drawing characters that cli uses also haveambiguous width.

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

If you do not want to change your font, you can also turn off Unicodeoutput, by setting thecli.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 previousquestion: Why are heading separators wider than my screen in RStudio?.

If some output is garbled, then cli probably misdetected Unicode supportfor your terminal or font. You can try choosing a different font. In ourexperience 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 athttps://github.com/r-lib/cli/issues

Format an error, warning or diagnostic message

Description

You can then throw this message withstop() orrlang::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 gluesubstitutions.

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 <- 26idx <- 100stop(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 supportinline 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 emittingit to the screen. It usescli_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 supportsinline 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 yourtaste.

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 updateinterval in milliseconds andframes: the character vector of thespinner's frames.

See Also

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

Check if the current platform/terminal supports readingsingle keys.

Description

Check if the current platform/terminal supports readingsingle 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 individualkeypressses.

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 MD5hash of the input, and converts them into an adjective-animal form tocreate a human readable hash.

Number of possible hash values

hash_animal() uses 1748 animal names and8946 different adjectives. The number ofdifferent hashes you can get for different values ofn_adj:

Source

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

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

hash_obj_animal() calculates the adjective-animal hash ofan 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 acharacter vector.

hash_raw_animal() andhash_obj_animal() return a listwith 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)$hashhash_animal("cli package", 1)$hashhash_animal("cli package", 2)$hashhash_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 MD5hash of the input, and converts them into an emoji representation.It uses a manually selected subset of all emojis, that tend to bedisplayed correctly.

Number of possible hash values

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

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

hash_obj_emoji() calculates the emoji hash of an Robject. 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 charactervectors. Note that an emoji might have multiple code points.

• text: text representation ofhash, comma separated.

• names: list column with the text representations ofemojis, incharacter vectors.

hash_raw_emoji() andhash_obj_emoji() return a list withentries:

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

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

• text: text representation ofhash, 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)$texthash_emoji("foobar", 2)$texthash_emoji("foobar", 3)$texthash_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 bytesof a raw vector.

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

hash_file_md5() calculates the MD5 hash of one or morefiles.

Value

hash_md5() returns a character vector of hexadecimal MD5hashes.

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

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 bytesof a raw vector.

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

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

Value

hash_sha1() returns a character vector of hexadecimalSHA-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-1hashes.

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 bytesof a raw vector.

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

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

Value

hash_sha256() returns a character vector of hexadecimalSHA-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-256hashes.

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 bytesof a raw vector.

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

hash_file_xxhash() calculates the xxHash hash of one ormore files.

The64 functions caculate the 64 bit variantof xxHash. Otherwise they work the same.

Value

hash_xxhash() returns a character vector of hexadecimalxxHash hashes.

hash_raw_xxhash() returns a character scalar.

hash_obj_xxhash() returns a character scalar.

hash_file_xxhash() returns a character vector of xxHashhashes.

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 ‘Buildinga semantic CLI’ article athttps://cli.r-lib.org.

Command substitution

All text emitted by cli supports glue interpolation. Expressionsenclosed by braces will be evaluated as R code. Seeglue::glue() fordetails.

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

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

#> This isimportant.

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

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

#> This isgreat.

An inline class will always create aspan element internally. So inthemes, you can use thespan.emph CSS selector to change how inlinetext is emphasized:

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

#> This isnice 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.Seelinks 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 opensthe file in RStudio or with the default app for the file type.Seelinks for more information about cli hyperlinks.

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

• fun same asfn.

• help is a help page of afunction.If the terminal supports ANSI hyperlinks to help pages (e.g. RStudio),then cli creates a clickable link. It supports link text.Seelinks 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.Seelinks for more information about cli hyperlinks.

• kbd for a keyboard key.

• key same askbd.

• 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 ofcollapsed vectors (see below) from "and" to "or".

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

• pkg for a package name.

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

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

• strong for strong importance.

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

• type formats the type of an R object in a readable way, and itshould 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.Seelinks 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.Seelinks 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 usingthem.

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. onethat starts or ends with space characters. The built-in theme does thisfor.file,.path and.email by default. You can highlightany 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 analphanumeric character, underscore, dot or forward slash.

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

Collapsing inline vectors

When cli performs inline text formatting, it automatically collapsesglue substitutions, after formatting. This is handy to create lists offiles, packages, etc.

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

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

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 defaulttwenty elements, but you can change it with thevec-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

Theval inline class formats values. By default (c.f. the built-intheme), it calls thecli_format() generic function, with the currentstyle as the argument. Seecli_format() for examples.

str is for formatting strings, it usesbase::encodeString() withdouble quotes.

Escaping⁠{⁠ and⁠}⁠

It might happen that you want to pass a string to⁠cli_*⁠ functions,and you donot want command substitution in that string, because itmight contain⁠{⁠ and⁠}⁠ characters. The simplest solution for this isto 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 doublethem:

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 <- 1nfiles <- 13pkgs <- 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, andpkg3

Seepluralization 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 spacecharacter:⁠\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 orFALSE.

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 thesame line. It is also supported by most R IDEs.⁠\\r⁠ is typicallyused 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 typicallyunwanted. This function detects if⁠\\r⁠ can be used for the givenstream or not.

The detection mechanism is as follows:

1. If thecli.dynamic option is set toTRUE,TRUE is returned.

2. If thecli.dynamic option is set to anything else,FALSE isreturned.

3. If theR_CLI_DYNAMIC environment variable is not empty and set tothe string"true","TRUE" or"True",TRUE is returned.

4. IfR_CLI_DYNAMIC is not empty and set to anything else,FALSE isreturned.

5. If the stream is a terminal, thenTRUE 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. OtherwiseFALSE 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 thecli.unicodeoption toTRUE. They can be turned off by setting if toFALSE.If this option is not set, thenbase::l10n_info() is used to detectUTF-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. seehas_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 readsNA 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 terminalsupports them.

Note: hyperlinks are currently experimental

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

About the links in this manual page

The hyperlinks that are included in this manual are demonstrativeonly, except for the⁠https:⁠ links. They look like a hyperlink, andyou can click on them, but they do nothing. I.e. a.run link willnot 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 useansi_has_hyperlink_support() to check if your terminal orIDE has hyperlink support in general, andansi_hyperlink_types() tocheck if various types of hyperlinks are supported.

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

Link text

Before we delve into the various types of hyperlinks, a general commentabout 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 customlink 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 thesestyles outputs both the link text and the URL in a (hopefully) helpfulway. See examples below.

URLs

There are two cli styles to link to generic URLs..url does notallow 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 thecli 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 callutils::URLencode() on it, especially, if it is substituted invia{}.

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 toconvert 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, thenyou can use.href with a⁠file:⁠ URL.

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

#> ... edit yourR profile.

Line and column numbers

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

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 filelink outside of RStudio, typically the operating system is consultedfor the application to open it.

Without hyperlink support

One issue with using.href file files is that it does not look greatif 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 thepackagename::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 attibble::tibble_options.

.topic support link text.

Vignettes

To link to a vignette, use.vignette:

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

#> ... see thetibble::types vignette.

Click to run code

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

You can create these links with.run:

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

#> Runtestthat::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 probablyneeds to qualify packages with::, but you might not want to show this:

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

#> Runsnapshot_review() to review

Security considerations

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

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

• ifargs 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 oftestthat, devtools, usethis, rlang, pkgload, or pkgdown which are explicitly allowed.

When RStudio does not run a.run hyperlink, then it shows the codeand the user can copy and paste it to the console, if they considerit 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$starlabel <- 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, dependingon the box style you use and the font the terminal uses. We found thatthe 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 classcli_ansi_style. This is returnedas is, without looking at the other arguments.

• An R color name, seegrDevices::colors().

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

• A one-column matrix with three rows for the red, greenand blue channels, as returned bygrDevices::col2rgb().

make_ansi_style() detects the number of colors to useautomatically (this can be overridden using thecolorsargument). 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 thatis 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

Acli_spinner object, which is a list of functions. Seeits methods below.

cli_spinner methods:

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

• ⁠$finish()⁠: terminate the spinner. Depending on terminal capabilitiesthis 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 controlsequences (ANSI sequences).

num_ansi_colors() detects if the current R session supports ANSIsequences, 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 workout of the box on most systems. If it does not work on your system,please report a bug. Setting options and environment variables to turnon ANSI support is error prone, because they are inherited in otherenvironments, e.g. knitr, that might not have ANSI support.

If you want toturn off ANSI colors, set theNO_COLOR environmentvariable to a non-empty value.

The exact detection mechanism is as follows:

1. If thecli.num_colors options is set, that is returned.

2. If theR_CLI_NUM_COLORS environment variable is set to anon-empty value, then it is used.

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

4. If thecrayon.enabled option is set toTRUE and thecrayon.colors option is not set, then the value of thecli.default_num_colors option, or if it is unset, then 8L isreturned.

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

6. If theNO_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. Ifstream is"auto" (the default) and there is an activesink (either for"output" or"message"), then we return 1L.(In theory we would only need to check the stream that will bebe actually used, but there is no easy way to tell that.)

9. Ifstream is not"auto", but it isstderr() and there is anactive sink for it, then 1L is returned.(If a sink is active for "output", then R changes thestdout()stream, so this check is not needed.)

10. If thecli.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 wereturn 1L.

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

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

14. Ifstream is not the standard output or standard error in aterminal, then 1L is returned.

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