ansiterm-rs

这是对未维护的 ansi-term 的延续，该库用于控制颜色和格式，如红色粗体文本或蓝色下划线文本，在 ANSI 终端上。向其创建者 Benjamin Sago 表示敬意。

安装

免责声明：此包仍在开发中，尚未在 crates.io 上提供

我们承诺将保持 API 稳定，不会破坏原始包中已经工作的任何内容。

基本用法

在此包中，您需要关注三个主要类型：ANSIString、Style 和 Colour。

Style 包含样式信息：前景色和背景色，文本是否应该加粗、闪烁或其他属性。枚举 Colour 表示可用的颜色。而 ANSIString 是一个与 Style 配对的字符串。

Color 也可用作 Colour 的别名。

要格式化字符串，请在 Style 或 Colour 上调用 paint 方法，将您想要格式化的字符串作为参数传入。例如，以下是如何获取一些红色文本：

use ansiterm::Colour::Red;

println!("This is in red: {}", Red.paint("a red string"));

需要注意的是，paint 方法实际上并不会返回一个带有 ANSI 控制字符的字符串。相反，它返回一个具有 Display 实现的 ANSIString 值，当格式化时返回字符。这允许字符串以最少的 String 分配在幕后执行打印操作。

如果您 确实 想获取转义码，那么您可以像其他 Display 值一样将 ANSIString 转换为字符串

use ansiterm::Colour::Red;

let red_string = Red.paint("a red string").to_string();

针对 Windows 10 用户注意：在 Windows 10 上，应用程序必须首先启用 ANSI 支持

let enabled = ansiterm::enable_ansi_support();

粗体、下划线、背景和其他样式

对于比纯前景色更改更复杂的情况，您需要自己构造 Style 值，而不是从 Colour 开始。您可以通过基于新创建的 Style（使用 Style::new() 创建）的链式方法来实现。每个方法都会创建一个新的样式，该样式具有特定的属性集。例如

use ansiterm::Style;

println!("How about some {} and {}?",
         Style::new().bold().paint("bold"),
         Style::new().underline().paint("underline"));

为了简洁起见，这些方法也已为 Colour 值实现，因此您可以在不需要从空 Style 值开始的情况下为您的样式指定前景色

use ansiterm::Colour::{Blue, Yellow};

println!("Demonstrating {} and {}!",
         Blue.bold().paint("blue bold"),
         Yellow.underline().paint("yellow underline"));

println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));

您可以使用以下完整样式列表：bold、dimmed、italic、underline、blink、reverse、hidden 和用于背景颜色的 on。

在某些情况下，您可能发现更改现有 Style 中的前景比从适当的 Colour 开始更容易。您可以使用 fg 方法来这样做

use ansiterm::Style;
use ansiterm::Colour::{Blue, Cyan, Yellow};

println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));

您可以使用 normal 方法将 Colour 转换为 Style。这将产生与直接在 Colour 上使用 paint 方法完全相同的 ANSIString，但在某些情况下很有用：例如，您可能有一个返回 Styles 的方法，并且需要用相同类型的值来表示“红色粗体”和“红色但不粗体”的样式。《Style 结构》还有一个 Default 实现，如果您想有一个没有任何设置的样式。

use ansiterm::Style;
use ansiterm::Colour::Red;

Red.normal().paint("yet another red string");
Style::default().paint("a completely regular string");

扩展颜色

您可以通过使用 Colour::Fixed 变体来访问 256 色的扩展范围，该变体接受要使用的颜色数字作为参数。这可以在您使用 Colour 的任何地方使用

use ansiterm::Colour::Fixed;

Fixed(134).paint("A sort of light purple");
Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");

这些值的前十六个与正常和粗体标准颜色变体相同。您可以使用这些作为 Fixed 颜色，但这样做也没有任何好处。

您还可以使用 Colour::RGB 变体来访问完整的 24 位颜色，该变体接受分别用于红色、绿色和蓝色的 u8 参数

use ansiterm::Colour::RGB;

RGB(70, 130, 180).paint("Steel blue");

组合连续的彩色字符串

将 ANSI 转义码写入终端的好处是它们可以 堆叠：如果跟在彩色字符串后面的文本具有类似样式，则不需要在每个彩色字符串的末尾使用重置代码。例如，如果您想要一些蓝色文本后跟一些蓝色粗体文本，可以发送蓝色 ANSI 代码，然后是粗体 ANSI 代码，最后发送重置代码，而无需在这两个字符串之间添加额外的代码。

在这种情况下，该软件包可以优化打印的 ANSI 代码，使终端渲染器更容易使用。`ANSIStrings 结构接受多个 `ANSIString 值的切片，并将迭代每个值，在格式化过程中仅打印需要更新的样式代码。

以下代码示例使用此功能将红色加粗的十进制数放在红色但非加粗的括号内显示。

use ansiterm::Colour::Red;
use ansiterm::{ANSIString, ANSIStrings};

let some_value = format!("{:b}", 42);
let strings: &[ANSIString<'static>] = &[
    Red.paint("["),
    Red.bold().paint(some_value),
    Red.paint("]"),
];

println!("Value: {}", ANSIStrings(strings));

以下几点需要注意。首先，paint 方法可以接受一个所有权的 String 或者一个借用 &str。内部，一个 ANSIString 使用写时复制（Cow）的字符串值来同时处理所有权和借用字符串。这里使用它来显示一个 String，即 format! 调用的结果，使用与一些静态可用的 &str 切片相同的机制。其次，ANSIStrings 值与其单数对应物以相同的方式工作，具有仅在需要时执行格式化的 Display 实现。

字节字符串

此库还支持格式化 [u8] 字节字符串；这支持处理未知编码文本的应用程序。 Style 和 Colour 支持绘制 [u8] 值，结果生成一个 ANSIByteString。此类型不实现 Display，因为它可能不包含 UTF-8，但它提供了一个 write_to 方法，可以将结果写入实现了 Write 的任何值。

use ansiterm::Colour::Green;

Green.paint("user data".as_bytes()).write_to(&mut std::io::stdout()).unwrap();

类似地，类型 ANSIByteStrings 支持以最小转义序列写入一系列 ANSIByteString 值。

use ansiterm::Colour::Green;
use ansiterm::ANSIByteStrings;

ANSIByteStrings(&[
    Green.paint("user data 1\n".as_bytes()),
    Green.bold().paint("user data 2\n".as_bytes()),
]).write_to(&mut std::io::stdout()).unwrap();