CLI inline markup
All text emitted by cli supports glue interpolation. Expressions
enclosed by braces will be evaluated as R code. See glue::glue()
for
details.
In addition to regular glue interpolation, cli can also add classes to parts of the text, and these classes can be used in themes. For example
cli_text("This is {.emph important}.")
adds a class to the "important" word, class "emph". Note that in this case the string within the braces is usually not a valid R expression. If you want to mix classes with interpolation, add another pair of braces:
adjective <- "great" cli_text("This is {.emph {adjective}}.")
An inline class will always create a span
element internally. So in
themes, you can use the span.emph
CSS selector to change how inline
text is emphasized:
cli_div(theme = list(span.emph = list(color = "red"))) adjective <- "nice and red" cli_text("This is {.emph {adjective}}.")
The default theme defines the following inline classes:
emph
for emphasized text.
strong
for strong importance.
code
for a piece of code.
pkg
for a package name.
fun
for a function name.
arg
for a function argument.
key
for a keyboard key.
file
for a file name.
path
for a path (essentially the same as file
).
email
for an email address.
url
for a URL.
var
for a variable name.
envvar
for the name of an environment variable.
val
for a "value".
See examples below.
You can simply add new classes by defining them in the theme, and then using them, see the example below.
Often it is useful to highlight a weird file or path name, e.g. one
that starts or ends with space characters. The buildin theme does this
for .file
, .path
and .email
by default. You can highlight
any string inline by adding the .q
class to it.
The current highlighting algorithm
adds single quotes to the string if it does not start or end with an alphanumeric character, underscore, dot or forward slash.
Highlights the background colors of leading and trailing spaces on terminals that support ANSI colors.
When cli performs inline text formatting, it automatically collapses glue substitutions, after formatting. This is handy to create lists of files, packages, etc. See examples below.
The val
inline class formats values. By default (c.f. the builtin
theme), it calls the cli_format()
generic function, with the current
style as the argument. See cli_format()
for examples.
{
and }
It might happen that you want to pass a string to cli_*
functions,
and you do not_ want command substitution in that string, because it
might contain }
and {
characters. The simplest solution for this is
referring to the string from a template:
msg <- "Error in if (ncol(dat$y)) {: argument is of length zero" cli_alert_warning("{msg}")
If you want to explicitly escape {
and }
characters, just double
them:
cli_alert_warning("A warning with {{ braces }}")
See also examples below.
All cli commands that emit text support pluralization. Some examples:
cli_alert_info("Found {ndirs} diretor{?y/ies} and {nfiles} file{?s}.") cli_text("Will install {length(pkgs)} package{?s}: {.pkg {pkgs}}")
See pluralization for details.
#>#> Strong importance#> `sum(a) / length(a)`#> cli#> `cli_text()`#> [ENTER]#> /usr/bin/env#> bugs.bunny@acme.com#> <https://acme.com>#> `R_LIBS`cli_end() ## Adding a new class cli_div(theme = list( span.myclass = list(color = "lightgrey"), "span.myclass" = list(before = "["), "span.myclass" = list(after = "]"))) cli_text("This is {.myclass in brackets}.")#> [in brackets].#>#> pkg1, pkg2, and pkg3## Escaping 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#> ! A warning with { braces }