easy-sgr

一个易于使用库，用于向您的项目添加图形ANSI码或SGR转义序列。其主要优势是提供的多种方法以及无依赖性；编译时间应该相当不错。

此库不支持使用非SGR ANSI转义序列

安装

将以下内容添加到您的Cargo.toml中

[dependencies]
easy-sgr="0.1.1"

使用方法

宏

关于易用性，我推荐使用该库提供的宏，无论是通过库本身还是通过宏库它本身。

这样无需导入库的其他功能

[dependencies]
easy-sgr = { version = "0.1.1", features = ["macro-only"] }

或者如果您仍然想使用其他功能，将"macro-only"替换为"macros"。

其用法非常简单

use easy_sgr::println;

println!("{[italic red]}This should be italic & red!{[]}");

{[]在这里被解释为重置。

所有其他 fmt 函数也都已实现，请参阅easy-sgr-macros以获取更多信息。

Color 和 Style 枚举

使用这两个枚举对文本进行着色的最简单运行时方法，当使用如println!、writeln!或format!等宏时，允许您在字符串字面量中内联工作。

use easy_sgr::{Color::*, Style::*};

println!("{Italic}{RedFg}This should be italic & red!{Reset}");

Color 和 Style 都是实现了 Display 的枚举：当它们被打印时，会写入匹配的 SGR 代码。

这种方法在简单性方面是最佳的，但也有一些缺点；使用它将反复重写序列转义 \x1b[ 和序列结束 m。在这个例子中，这将是这样写的

\x1b[3m\x1b[31mThis should be italic & red!\x1b[0m

对于绝大多数用例来说，这不会是一个大问题。

EasySGR 特性

这与上面的方法类似，但它使用了 EasySGR 特性。这个特性由实现 IntoAnsiString> 的任何东西实现，包括样式和颜色。其主要目的是提供用于链接 SGR 代码的功能。

可以使用它实现上面的示例

use easy_sgr::{ Color::*, EasySGR, Style::*};

let sgr = Italic.color(RedFg);

println!("{sgr}This should be italic & red!{Reset}");

现在输出看起来会是这样

\x1b[31;3mThis should be italic & red!\x1b[0m

而不是重写整个序列，这里使用了分隔符字符 ;。

这样做避免了重写转义和结束序列的问题，但使用起来更昂贵，因为它分配了一个 SGRString。

SGRString 结构体

SGRString 是所有 EasySGR 函数返回的类型，它封装了所有可能的 SGR 序列。您可以使用它以如下方式重现之前的示例

use easy_sgr::{Color::*, EasySGR, Style::*};

let text = "This should be italic & red!"
    .to_sgr()
    .style(Italic)
    .color(RedFg);
println!("{text}");

您可以使用 .to_sgr() 作为 .style(..)，.color(..) 和所有其他 EasySGR 函数可以直接在字符串字面量和实现它的其他类型上调用。

上面的方法仍然使用了 EasySGR 特性，您也可以像这样不使用它

use easy_sgr::{ColorKind, SGRString, StyleKind};

let mut text = SGRString::from("This should be italic & red!");
text.italic = StyleKind::Place;
text.foreground = ColorKind::Red;

println!("{text}")

SGRWriter 结构体

可以直接使用 writer，而不是使用上述方法

use std::io::{stdout, Write};
use easy_sgr::{Color::*, EasySGR, SGRWriter, Style::*};

let mut writer = SGRWriter::from(stdout());
writer.sgr(&Italic.color(RedFg)).unwrap();
writer.write_inner("This should be italic & red!").unwrap();
writer.sgr(&Reset).unwrap();

或者，当写入 String 时

use easy_sgr::{Color::*, EasySGR, SGRWriter, Style::*};

let stylized_string = {
    let mut writer = SGRWriter::from(String::new());
    writer.sgr(&Italic.color(RedFg)).unwrap();
    writer.write_inner("This should be italic & red!").unwrap();
    writer.sgr(&Reset).unwrap();
    writer.internal()
};

特性

部分

此特性改变了 discrete 模块的工作方式，启用它会导致其类型不写入序列转义和结束。

这意味着为了达到与上述相同的效果，必须这样做

use easy_sgr::{Color::*, Seq::*, Style::*};

println!("{Esc}{Italic};{RedFg}{End}This should be italic & red!{Esc}{Reset}{End}");

结果得到的字符串

\x1b[3;31mThis should be italic & red!\x1b[0m

此特性以易用性换取详尽性，从而获得更多的控制。

结构

easy-sgr 被拆分为三个模块

• 离散
  • 包含可以用于字符串字面量内的类型
  • 这些类型，Seq，Color 和 Style 都可以独立工作
  • 它们都实现了 DiscreteSGR 类型以辅助此操作
  • DiscreteSGR 类型都可以与 SGRString 一起工作
• 图形
  • 核心是 SGRString 和 EasySGR
  • SGRString 是一个具有写入 SGR 代码能力的 String
  • EasySGR 是一个用于将 SGR 代码链接到创建 SGRString 的特剧行为
  • EasySGR 被所有实现 Into<SGRString>
  • 这包括
    • SGRString
    • 颜色
    • 样式
    • &str
    • 字符串
    • &字符串
• 书写
  • 实现了 SGRWriter 和 SGRBuilder
  • 被其他模块用于书写