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

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

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就会生成一个可点击的链接。