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()中内置定义了许多标记主题类型,只需要使用定义的主题名称:
| | 没有任何前缀 |
| | 缩进前缀 |
| | 圆点前缀 |
| | 箭头前缀 |
| ? success | 对号前缀 |
| ? danger | 错号前缀 |
| ! warning | 惊叹号前缀 |
| ? 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}}.")
arg | 用于函数的参数 |
cls | 用于S3,S4,R6或其余类的名称 |
code | 用于一段代码 |
dt | 用于一个命名列表的元素,表格形式 |
dd | 用于一个命名列表的描述,表格形式 |
用于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就会生成一个可点击的链接。 |