R语言【cli】——通过cli_abort用 cli 格式的内容显示错误、警告或信息，内部调用cli_bullets和inline-makeup

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

先从那些不需要下大力气理解的参数入手：

参数【.envir】：进行万能表达式编译的环境。

参数【.frame】：抛出上下文。默认用于参数【.trace_bottom】，当参数【.internal】为 TRUE 时，用于确定在内部错误中提及的内部软件包。

参数【call】：当前运行函数的执行环境，例如 call = caller_env()。相应的函数调用会被检索出来，并在错误信息中作为错误源被提及。您只需要在从辅助函数抛出条件时提供调用即可，而无需在信息中提及。

参数【...】：传递给 rlang::abort()，rlang::warn() 或 rlang::warn() 的参数。

---

以上都是不太需要进行修改的参数，所以本文的重点将放在参数【message】上。只需将希望输出的文本信息传递给参数【message】即可：

cli_abort(c("this is my error! Do not mess with R!"))

输出了警告信息：

Error:
! this is my error! Do not mess with R!
Run `rlang::last_trace()` to see where the error occurred.

---

参数【message】：它是通过调用 cli_bullets() 进行格式化的。进一步地，还需要调用 inline-makeup（内联标记）。

---

Package cli version 3.6.2

cli_bullets() 中内置定义了许多标记主题类型，只需要使用定义的主题名称：

cli_bullets()的内置标记

cli_bullets(c("noindent"))	noindent	没有任何前缀
cli_bullets(c(" " = "indent"))	indent	缩进前缀
cli_bullets(c("*" = "bullet"))	• bullet	圆点前缀
cli_bullets(c(">" = "arrow"))	→ arrow	箭头前缀
cli_bullets(c("v" = "success"))	✔ success	对号前缀
cli_bullets(c("x" = "danger"))	✖ danger	错号前缀
cli_bullets(c("!" = "warning"))	! warning	惊叹号前缀
cli_bullets(c("i" = "info"))	ℹ info	信息前缀

cli_bullets() 和 cli_abort()的标记对比

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

---

inline-markup 可以让输出的信息更加多元，更加清晰。由 R包cli 输出的文本都支持万能语法插值，详见 glue::glue()。cli 支持通过使用类型名称对部分文本内容添加格式。例如：

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

上述代码给文本 "important" 添加了一个格式 "emph"。注意本例中大括号内的字符串通常不会是一个可运行的R表达式。如果打算运用插值，可以再使用一个大括号 {} ：

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

每个inline类总会在内部创建一个span元素。所以使用主题时，可以通过span.emph 的CSS选择器来改变文本的强调显示格式：

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

cli默认提供的主题

arg	用于函数的参数
cls	用于S3，S4，R6或其余类的名称
code	用于一段代码
dt	用于一个命名列表的元素，表格形式
dd	用于一个命名列表的描述，表格形式
email	用于email地址。如果输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接。
emph	用于突出显示文本
envvar	用于环境变量的名称
field	用于通用字段，比如一个命名列表
file	用于文件名称。如果输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接，点击后就会在RStudio打开该文件或在该文件类型的默认软件中打开。
fn	用于函数名称。如果输入的是package::function_name形式，并且输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接。
fun	与fn相同
help	用于函数的帮助页面。如果输出终端支持ANSI超链接至帮助页面（比如RStudio），那么cli就会生成一个可点击的链接。
href	用于创建一个超链接，可能带有链接文本。如果输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接。
kbd	用于键盘键
key	与kbd相同
obj_type_friendly	用于以可读方式格式化 R 对象的类型，应与 {} 一起使用。
or	将分隔折叠矢量最后两个元素的字符串从 "和 "改为 "或"。
path	用于文件路径，与file相同。
pkg	用于包的名称。
run	用于R表达式，如果输出终端支持ANSI超链接至可运行的代码，那么该链接可能可以点击。
str	双引号引用字符串
topic	用于标题的帮助页面。
type	用于以可读方式格式化 R 对象的类型，应与 {} 一起使用。
url	用于网址。如果输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接。
var	用于变量名称。
val	用于通用值。
vignette	用于插件。如果输出终端支持ANSI超链接（比如RStudio，iTerm2等），那么cli就会生成一个可点击的链接。