prettytable-rs

一个用于 Rust 的格式化和对齐的表格打印库。

版权 © 2022 Pierre-Henri Symoneaux

本软件分发时不附带任何保证
请查阅 LICENSE.txt 文件以获取更多信息。

如何使用

• 包括
• 基本用法
• 使用宏
• 风格化处理
  • 样式指定符列表
  • 颜色指定符列表
• 切片
• 自定义表格的外观和感觉
• CSV 导入/导出
  • 导入
  • 导出
• 关于行结束符的说明
• Evcxr 集成

包括

通过在您的 Cargo.toml 文件中添加以下行将库作为依赖项包含到您的项目中：

[dependencies]
prettytable-rs = "^0.10"

该库需要至少 rust v1.56。

对 MSRV 的任何更改都将通过小版本号升级来完成。

SemVer 政策

• 1.0.0 之前的破坏性更改将遵循小版本号升级
• 1.0.0 之后 本库的所有默认功能都由 SemVer 覆盖
• 如上所述，MSRV 被视为不受 SemVer 的约束

基本用法

开始使用它

#[macro_use] extern crate prettytable;
use prettytable::{Table, Row, Cell};

fn main() {
    // Create the table
    let mut table = Table::new();

    // Add a row per time
    table.add_row(row!["ABC", "DEFG", "HIJKLMN"]);
    table.add_row(row!["foobar", "bar", "foo"]);
    // A more complicated way to add a row:
    table.add_row(Row::new(vec![
        Cell::new("foobar2"),
        Cell::new("bar2"),
        Cell::new("foo2")]));

    // Print the table to stdout
    table.printstd();
}

上面的代码将输出

+---------+------+---------+
| ABC     | DEFG | HIJKLMN |
+---------+------+---------+
| foobar  | bar  | foo     |
+---------+------+---------+
| foobar2 | bar2 | foo2    |
+---------+------+---------+

使用宏

对于日常使用，请考虑使用 table! 宏。此代码将产生与上面相同的输出

#[macro_use] extern crate prettytable;

fn main() {
    let table = table!(["ABC", "DEFG", "HIJKLMN"],
                       ["foobar", "bar", "foo"],
                       ["foobar2", "bar2", "foo2"]);

    table.printstd();
}

ptable! 宏结合创建和打印表格

#[macro_use] extern crate prettytable;

fn main() {
    let table = ptable!(["ABC", "DEFG", "HIJKLMN"],
                        ["foobar", "bar", "foo"],
                        ["foobar2", "bar2", "foo2"]);
}

表格也支持多行单元格内容。因此，您可以打印一个表格到另一个表格（yo dawg ;）。例如

let table1 = table!(["ABC", "DEFG", "HIJKLMN"],
                    ["foobar", "bar", "foo"],
                    ["foobar2", "bar2", "foo2"]);

let table2 = table!(["Title 1", "Title 2"],
                    ["This is\na multiline\ncell", "foo"],
                    ["Yo dawg ;) You can even\nprint tables\ninto tables", table1]);

table2.printstd();

将打印

+-------------------------+------------------------------+
| Title 1                 | Title 2                      |
+-------------------------+------------------------------+
| This is                 | foo                          |
| a multiline             |                              |
| cell                    |                              |
+-------------------------+------------------------------+
| Yo dawg ;) You can even | +---------+------+---------+ |
| print tables            | | ABC     | DEFG | HIJKLMN | |
| into tables             | +---------+------+---------+ |
|                         | | foobar  | bar  | foo     | |
|                         | +---------+------+---------+ |
|                         | | foobar2 | bar2 | foo2    | |
|                         | +---------+------+---------+ |
+-------------------------+------------------------------+

行可能包含不同数量的单元格。表格将自动适应最长的行，通过在较短的行中打印额外的空单元格来打印。

风格化处理！

表格可以通过配置设置（背景和前景颜色、粗体和斜体）以及通过 term crate 来具有样式化的输出。单元格中的对齐也可以设置（左、右、居中），并且单元格可以跨越多个列。

term 风格属性被直接重新导出

• 直接

  use prettytable::{Attr, color};
  
  /* ... */
  
  table.add_row(Row::new(vec![
      Cell::new("foobar")
          .with_style(Attr::Bold)
          .with_style(Attr::ForegroundColor(color::GREEN)),
      Cell::new("bar")
          .with_style(Attr::BackgroundColor(color::RED))
          .with_style(Attr::Italic(true))
          .with_hspan(2),
      Cell::new("foo")
      ]));
  

• 通过样式字符串

  table.add_row(Row::new(vec![
      Cell::new("foobar").style_spec("bFg"),
      Cell::new("bar").style_spec("BriH2"),
      Cell::new("foo")]));
  

• 使用 row! 宏

  table.add_row(row![bFg->"foobar", BriH2->"bar", "foo"]);
  

• 使用 table! 宏（此宏创建一个新的表格，与前面的例子不同）

  table!([bFg->"foobar", BriH2->"bar", "foo"]);
  

这里

• bFg 表示 粗体，Foreground: green,
• BriH2 表示 Background: red, italic, Horizontal span of 2。

另一个例子：FrBybc 表示 Foreground: red, Background: yellow, bold, center。

所有在宏中设置单元格样式的案例

• 使用 row!，对每个单元格单独设置

  row![FrByb->"ABC", FrByb->"DEFG", "HIJKLMN"];
  

• 使用 row!，对整个行设置

  row![FY => "styled", "bar", "foo"];
  

• 使用 table!，对每个单元格单独设置

  table!([FrBybl->"A", FrBybc->"B", FrBybr->"C"], [123, 234, 345, 456]);
  

• 使用 table!，对整个行设置

  table!([Frb => "A", "B", "C"], [Frb => 1, 2, 3, 4], [1, 2, 3]);
  

• 使用 table!，混合样式

  table!([Frb => "A", "B", "C"], [Frb->1, Fgi->2, 3, 4], [1, 2, 3]);
  

样式指定符列表

• F : Foreground（必须后跟颜色指定符）
• B : Background（必须后跟颜色指定符）
• H : Horizontal span（必须后跟数字）
• b : bold
• i : italic
• u : underline
• c : Align center
• l : Align left
• r : Align right
• d : default style

颜色指定符列表

小写字母代表 普通 颜色

• r : Red
• b : Blue
• g : Green
• y : Yellow
• c : Cyan
• m : Magenta
• w : White
• d : Black

大写字母代表上述颜色的 亮色 对应色

• R : Bright Red
• B : Bright Blue
• 等等...

切片

表格可以被分割成不可变的借用子表格。分割的类型为 prettytable::TableSlice<'a>。

例如，

use prettytable::Slice;
/* ... */
let slice = table.slice(2..5);
table.printstd();

将打印出从 table 中第 2、3 和 4 行的表格。

支持其他 Range 语法。例如

table.slice(..); // Returns a borrowed immutable table with all rows
table.slice(2..); // Returns a table with rows starting at index 2
table.slice(..3); // Returns a table with rows until the one at index 3

自定义表格的外观和感觉

可以使用 prettytable::format::TableFormat 来自定义表格的外观和感觉。

可配置的设置包括

• 边框（左侧和右侧）
• 接合点
• 列分隔符
• 行分隔符
• 标题（使用 table.set_titles()）

为此，可以

• 创建一个新的 TableFormat 对象，然后调用设置器直到获得所需的配置；
• 或者使用方便的 FormatBuilder 和构建器模式，如下所示

let mut table = Table::new();
let format = format::FormatBuilder::new()
    .column_separator('|')
    .borders('|')
    .separators(&[format::LinePosition::Top,
                  format::LinePosition::Bottom],
                format::LineSeparator::new('-', '+', '+', '+'))
    .padding(1, 1)
    .build();
table.set_format(format);

table.set_titles(row!["Title 1", "Title 2"]);
table.add_row(row!["Value 1", "Value 2"]);
table.add_row(row!["Value three", "Value four"]);

上面的代码将使表格看起来像

+-------------+------------+
| Title 1     | Title 2    |
| Value 1     | Value 2    |
| Value three | Value four |
+-------------+------------+

为了方便，在 prettytable::format::consts 模块中预定义了几个格式。

一些格式及其相应的输出

• use prettytable::format;
  
  table.set_format(*format::consts::FORMAT_NO_LINESEP_WITH_TITLE);
  

  +-------------+------------+
  | Title 1     | Title 2    |
  +-------------+------------+
  | Value 1     | Value 2    |
  | Value three | Value four |
  +-------------+------------+
  

• use prettytable::format;
  
  table.set_format(*format::consts::FORMAT_NO_BORDER_LINE_SEPARATOR);
  

  Title 1     | Title 2
  ------------+------------
  Value 1     | Value 2
  Value three | Value four
  

请检查 API 文档以获取可用的预定义格式的完整列表。

CSV 导入/导出

表格可以从和导出到 CSV。这得益于默认和可选功能 csv。

csv 功能可能在未来的主要版本中默认禁用。

导入

Table 可以从字符串导入

let table = Table::from_csv_string("ABC,DEFG,HIJKLMN\n\
                                    foobar,bar,foo\n\
                                    foobar2,bar2,foo2")?;

或从 CSV 文件导入

let table = Table::from_csv_file("input_csv.txt")?;

这两种导入 CSV 的方法假定 CSV 格式没有标题，并且由逗号分隔

还可以从 CSV 读取器导入，这允许对 CSV 格式进行更多定制

let reader = /* create a reader */;
/* do something with the reader */
let table = Table::from_csv(reader);

导出

导出为通用 Write

let out = File::create("output_csv.txt")?;
table.to_csv(out)?;

或导出到 csv::Writer<W: Write>

let writer = /* create a writer */;
/* do something with the writer */
table.to_csv_writer(writer)?;

:dep prettytable = { git = "https://github.com/phsym/prettytable-rs", package = "prettytable-rs", features = ["evcxr"] }