EVOLUTION-MANAGER
Edit File: inline-markup.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: About inline markup in the semantic cli</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for inline-markup {cli}"><tr><td>inline-markup {cli}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>About inline markup in the semantic cli</h2> <h3>Description</h3> <p>About inline markup in the semantic cli </p> <h3>Command substitution</h3> <p>All text emitted by cli supports glue interpolation. Expressions enclosed by braces will be evaluated as R code. See <code><a href="../../glue/html/glue.html">glue::glue()</a></code> for details. </p> <p>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 </p> <div class="sourceCode r"><pre>cli_text("This is {.emph important}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> This is <span style="font-style: italic;">important</span>. </pre></div> <p>adds a class to the "important" word, class <code>"emph"</code>. 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: </p> <div class="sourceCode r"><pre>adjective <- "great" cli_text("This is {.emph {adjective}}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> This is <span style="font-style: italic;">great</span>. </pre></div> <p>An inline class will always create a <code>span</code> element internally. So in themes, you can use the <code>span.emph</code> CSS selector to change how inline text is emphasized: </p> <div class="sourceCode r"><pre>cli_div(theme = list(span.emph = list(color = "red"))) adjective <- "nice and red" cli_text("This is {.emph {adjective}}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> This is <span style="font-style: italic;color: #DC322F;">nice and red</span>. </pre></div> <h3>Classes</h3> <p>The default theme defines the following inline classes: </p> <ul> <li> <p><code>arg</code> for a function argument. </p> </li> <li> <p><code>cls</code> for an S3, S4, R6 or other class name. </p> </li> <li> <p><code>code</code> for a piece of code. </p> </li> <li> <p><code>dt</code> is used for the terms in a definition list (<code><a href="cli_dl.html">cli_dl()</a></code>). </p> </li> <li> <p><code>dd</code> is used for the descriptions in a definition list (<code><a href="cli_dl.html">cli_dl()</a></code>). </p> </li> <li> <p><code>email</code> for an email address. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>emph</code> for emphasized text. </p> </li> <li> <p><code>envvar</code> for the name of an environment variable. </p> </li> <li> <p><code>field</code> for a generic field, e.g. in a named list. </p> </li> <li> <p><code>file</code> for a file name. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link that opens the file in RStudio or with the default app for the file type. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>fun</code> for a function name. If it is in the <code>package::function_name</code> form, and the the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>help</code> is a help page of a <em>function</em>. If the terminal supports ANSI hyperlinks to help paages (e.g. RStudio), then cli creates a clickable link. It supports link text. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>href</code> creates a hyperlink, potentially with a link text. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>key</code> for a keyboard key. </p> </li> <li> <p><code>obj_type_friendly</code> formats the type of an R object in a readable way, and it should be used with <code>{}</code>, see an example below. </p> </li> <li> <p><code>or</code> changes the string that separates the last two elements of collapsed vectors (see below) from "and" to "or". </p> </li> <li> <p><code>path</code> for a path (the same as <code>file</code> in the default theme). </p> </li> <li> <p><code>pkg</code> for a package name. </p> </li> <li> <p><code>run</code> is an R expression, that is potentially clickable if the terminal supports ANSI hyperlinks to runnable code (e.g. RStudio). It supports link text. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>strong</code> for strong importance. </p> </li> <li> <p><code>topic</code> is a help page of a <em>ropic</em>. If the terminal supports ANSI hyperlinks to help paages (e.g. RStudio), then cli creates a clickable link. It supports link text. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>url</code> for a URL. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li> <li> <p><code>type</code> formats the type of an R object in a readable way, and it should be used with <code>{}</code>, see an example below. </p> </li> <li> <p><code>url</code> for a URL. If the terminal supports ANSI hyperlinks (e.g. RStudio, iTerm2, etc.), then cli creates a clickable link. </p> </li> <li> <p><code>var</code> for a variable name. </p> </li> <li> <p><code>val</code> for a generic "value". </p> </li> <li> <p><code>vignette</code> is a vignette. If the terminal supports ANSI hyperlinks to help paages (e.g. RStudio), then cli creates a clickable link. It supports link text. See <a href="links.html">links</a> for more about cli hyperlinks. </p> </li></ul> <div class="sourceCode r"><pre>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) </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> • <span style="font-style: italic;">Emphasized</span> text. #> • <span style="font-weight: bold;">Strong</span> importance. #> • A piece of code: `sum(a) / length(a)`. #> • A package name: <span style="color: #268BD2;">cli</span>. #> • A function name: `cli_text()`. #> • A keyboard key: press <span style="color: #268BD2;">[ENTER]</span>. #> • A file name: <span style="color: #268BD2;">/usr/bin/env</span>. #> • An email address: <span style="color: #268BD2;">bugs.bunny@acme.com</span>. #> • A URL: <span style="font-style: italic;color: #268BD2;"><https://example.com></span>. #> • An environment variable: `R_LIBS`. #> • `mtcars` is a data frame </pre></div> <p>You can add new classes by defining them in the theme, and then using them. </p> <div class="sourceCode r"><pre>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() </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> This is <span style="color: #cccccc;"><<in angle brackets>></span>. </pre></div> <h4>Highlighting weird-looking values</h4> <p>Often it is useful to highlight a weird file or path name, e.g. one that starts or ends with space characters. The built-in theme does this for <code>.file</code>, <code>.path</code> and <code>.email</code> by default. You can highlight any string inline by adding the <code>.q</code> class to it. </p> <p>The current highlighting algorithm </p> <ul> <li><p> adds single quotes to the string if it does not start or end with an alphanumeric character, underscore, dot or forward slash. </p> </li> <li><p> Highlights the background colors of leading and trailing spaces on terminals that support ANSI colors. </p> </li></ul> <h3>Collapsing inline vectors</h3> <p>When cli performs inline text formatting, it automatically collapses glue substitutions, after formatting. This is handy to create lists of files, packages, etc. </p> <div class="sourceCode r"><pre>pkgs <- c("pkg1", "pkg2", "pkg3") cli_text("Packages: {pkgs}.") cli_text("Packages: {.pkg {pkgs}}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> Packages: pkg1, pkg2, and pkg3. #> Packages: <span style="color: #268BD2;">pkg1</span>, <span style="color: #268BD2;">pkg2</span>, and <span style="color: #268BD2;">pkg3</span>. </pre></div> <p>Class names are collapsed differently by default </p> <div class="sourceCode r"><pre>x <- Sys.time() cli_text("Hey, {.var x} has class {.cls {class(x)}}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> Hey, `x` has class <span style="color: #268BD2;"><POSIXct/POSIXt></span>. </pre></div> <p>By default cli truncates long vectors. The truncation limit is by default twenty elements, but you can change it with the <code>vec-trunc</code> style. </p> <div class="sourceCode r"><pre>nms <- cli_vec(names(mtcars), list("vec-trunc" = 5)) cli_text("Column names: {nms}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> Column names: mpg, cyl, disp, …, gear, and carb. </pre></div> <h3>Formatting values</h3> <p>The <code>val</code> inline class formats values. By default (c.f. the built-in theme), it calls the <code><a href="cli_format.html">cli_format()</a></code> generic function, with the current style as the argument. See <code><a href="cli_format.html">cli_format()</a></code> for examples. </p> <p><code>str</code> is for formatting strings, it uses <code><a href="../../base/html/encodeString.html">base::encodeString()</a></code> with double quotes. </p> <h3>Escaping <code style="white-space: pre;">{</code> and <code style="white-space: pre;">}</code></h3> <p>It might happen that you want to pass a string to <code style="white-space: pre;">cli_*</code> functions, and you do <em>not</em> want command substitution in that string, because it might contain <code style="white-space: pre;">{</code> and <code style="white-space: pre;">}</code> characters. The simplest solution for this is to refer to the string from a template: </p> <div class="sourceCode r"><pre>msg <- "Error in if (ncol(dat$y)) {: argument is of length zero" cli_alert_warning("{msg}") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> <span style="color: #B58900;">!</span> Error in if (ncol(dat$y)) {: argument is of length zero </pre></div> <p>If you want to explicitly escape <code style="white-space: pre;">{</code> and <code style="white-space: pre;">}</code> characters, just double them: </p> <div class="sourceCode r"><pre>cli_alert_warning("A warning with {{ braces }}.") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> <span style="color: #B58900;">!</span> A warning with { braces }. </pre></div> <p>See also examples below. </p> <h3>Pluralization</h3> <p>All cli commands that emit text support pluralization. Some examples: </p> <div class="sourceCode r"><pre>ndirs <- 1 nfiles <- 13 cli_alert_info("Found {ndirs} diretor{?y/ies} and {nfiles} file{?s}.") cli_text("Will install {length(pkgs)} package{?s}: {.pkg {pkgs}}") </pre></div> <div class="asciicast" style="color: #172431;font-family: 'Fira Code',Monaco,Consolas,Menlo,'Bitstream Vera Sans Mono','Powerline Symbols',monospace;line-height: 1.300000"><pre> #> <span style="color: #2AA198;">ℹ</span> Found 1 diretory and 13 files. #> Will install 3 packages: <span style="color: #268BD2;">pkg1</span>, <span style="color: #268BD2;">pkg2</span>, and <span style="color: #268BD2;">pkg3</span> </pre></div> <p>See <a href="pluralization.html">pluralization</a> for details. </p> <h3>Wrapping</h3> <p>Most cli containers wrap the text to width the container's width, while observing margins requested by the theme. </p> <p>To avoid a line break, you can use the UTF_8 non-breaking space character: <code style="white-space: pre;">\u00a0</code>. cli will not break a line here. </p> <p>To force a line break, insert a form feed character: <code style="white-space: pre;">\f</code> or <code style="white-space: pre;">\u000c</code>. cli will insert a line break there. </p> <hr /><div style="text-align: center;">[Package <em>cli</em> version 3.4.1 <a href="00Index.html">Index</a>]</div> </body></html>