SGR 宏

此包提供了宏，用于在编译时以 SGR ("选择图形表示") 参数将文本 ergonomically 包装在 ANSI 控制序列中。这些参数用于着色文本以及应用斜体和下划线等样式。有关特定序列的详细信息，请参阅维基百科页面 ANSI 转义代码。

更多代码示例可在包文档中找到。

模式

此包中的每个宏都有三种 "输出模式"：文字、格式和字符串。这些确定宏的输出类型，以及它是否可以在 const 上下文中调用。

此外，还有三种 "重置模式"：单个、全部和无。这些确定宏调用结束时将执行的操作——应 重置 的格式状态。

输出模式

最简单的输出模式是文字模式。必须提供字符串字面量，所有格式化都在编译时直接应用。文字模式宏调用的输出是 &str 字面量，适合作为 concat! 的输入。

第二种模式是格式模式。此模式下的调用将解析为对 format_args! 的调用。这将返回 Arguments，适合作为 format!、println! 和 write! 等格式化宏的输入参数。此模式通过在调用开始处放置一个 % 符号启用。在符号之后，可以提供模板字面量。

第三种模式是字符串模式。此模式下的调用将解析为对 format! 的调用，返回一个完全形成的堆分配的 String。此模式通过在调用开始处放置一个 @ 符号启用，并且也可以提供模板字面量。

如果启用了“const”货物功能，则可使用第四种模式：常量格式模式。在此模式下调用将解析为对 formatcp! 的调用，返回一个静态字符串切片。然而，此输出不是字符串字面量，也不适合作为 concat! 的输入。此模式通过调用开始处的 # 符号启用。

恢复模式

默认情况下，此包中每个宏的结果都将以另一个控制序列结尾，该序列会撤销在开始时设置的任何格式。例如，sgr_bold! 宏将发出一个控制序列来设置粗体强度，宏的输入参数，然后是一个控制序列来设置正常强度。同样，所有着色宏在结束时都会设置默认的文本颜色。

一些样式共享一个恢复序列，这意味着它们不能安全地嵌套；内部样式的结束也将恢复外部样式。以下宏组的此情况是真实的

• sgr_bold! 和 sgr_faint!
• sgr_blink! 和 sgr_blink2!
• sgr_super! 和 sgr_sub!
• 所有不以 *_bg 结尾的基本、索引和 RGB 着色宏。
• 所有以 *_bg 结尾的基本、索引和 RGB 着色宏。

要控制恢复序列的行为，还有两个额外的符号：! 用于阻止恢复 任何 格式，以及 * 用于恢复 所有 格式。与输出模式符号一样，这些符号放置在宏调用开始处。如果同时使用了输出符号和恢复符号，则输出符号必须放在第一个位置（例如，@* 或 %!）。

在符号后接受逗号，但不是必需的。这可能有助于清晰度，或者在取消引用或反转参数的情况下。

宏

基本颜色

SGR 支持 8 种基本颜色：黑色、红色、绿色、黄色、蓝色、品红色、青色和白色。这 8 种颜色中每一种都有一个“亮”变体，导致有 16 种命名颜色。此外，这 16 种命名颜色中的每一种都有两个宏：一个用于 前景 颜色，一个用于 背景 颜色。

这产生了 32 个基本颜色宏；每个基本颜色有四个宏。

索引颜色

提供了两个用于 8 位 SGR 颜色代码的宏：color_256! 和 color_256_bg!。这些宏使用上面详细说明的所有相同模式符号，但宏的第一个参数必须是 8 位整数，指定颜色索引，后跟一个分号。

RGB 颜色

提供了两个用于 24 位 SGR 颜色代码的宏：color_rgb! 和 color_rgb_bg!。这些宏使用上面详细说明的所有相同模式符号，但宏的第一个参数必须是 RGB 颜色值，后跟一个分号。

有关 RGB 颜色规范的更多信息，请参阅 color_rgb! 宏的文档。

样式

提供了 11 个宏用于各种“样式”的文本。这些通常不会改变文本颜色，但一些方面，如文本强度，可能通过改变颜色亮度或鲜艳度来实现。

Cargo 功能

如果这个库启用了 "const" Cargo 功能，将支持 const_format crate。此功能通过新的输出模式访问。使用带有 # 符号的 SGR 宏将也支持模板字符串。在撰写本文档时，这将解析为调用 formatcp! 宏。