TeXtr

TeXtr 是一个接口，用于从符合库兼容格式的 JSON 文档解析中生成 PDF 文档。此格式在 Document 结构体中指定，该结构体提供了一个名为 to_pdf 的方法，该方法将此高级表示转换为 PDF 文档。

在此包中，PDF 文档由结构体 PdfDocument 表示，它提供了一个直接操作 PDF 的高级接口。操作 PDF 文档的详细信息隐藏在此结构体的实现中，但无论如何，如果需要，它们在一定程度上对最终用户公开。

文档

文档可在 docs.rs 网站的以下 链接 上找到。

使用此库有两种方式：第一种是从头开始写入 PDF 文档，如 pdf_from_scratch 示例所示，通过调用 PdfDocument 结构体的函数，如 add_font、插入 add_page_with_layer 和 write_text_to_layer_in_page，然后调用 write_all 来最终完成文档，然后可以将其保存到文件（此方法需要由库的最终用户提供文档和实例 ID）。

此库可以使用的另一种方式（预期方式）是提供编码 Document 数据结构或数据结构的 JSON 文档，或者将其本身作为代码（可能通过某些布局算法生成）提供，然后调用函数 Document::to_pdf，这将自动生成可以保存到文件或进一步操作的 PdfDocument。

安装

在通过 rustup 安装 Rust 或以任何方式更新 Rust 到最新版本后，将以下内容添加到您项目中的 Cargo.toml 文件中，以使用此库。

textr = "0.2"

如果您想从提供的示例中尝试此库，请克隆此存储库并运行以下命令：

cargo run --example <example_name>

其中 example_name 可以是以下之一：要么是 document_to_pdf，要么是 pdf_from_scratch。示例 document_to_pdf 是一个命令行工具，允许您轻松地将任何符合该库特定格式的 JSON 文档（示例可以在 assets 文件夹中找到）转换为 PDF 文档，而 pdf_from_scratch 示例将直接生成 PDF 文档，无需将 JSON 文件反序列化为 Document 结构体。

测试

该库已进行伪模糊测试，以确保其在各种情况下输出的一致性以及按预期工作。如果您想亲自运行测试，那么您需要先通过运行测试函数 generate_fuzz_targets 生成模糊目标（内容随机但仍然符合正确格式的 JSON 文档），通过以下命令

cargo test generate_fuzz_targets -- --exact

此命令将在 fuzz/fuzz_targets 目录中填充 JSON 文件。下一步是通过以下命令执行测试函数 generate_target_references_from_fuzz_targets，这将生成参考 PDF 文档，保存它们，然后将它们转换为 fuzz/targets_references 目录中的 postscript 文档格式。

仅作参考，postscript 格式是 PDF 文档的文本等效物，由于 PDF 是字节格式，因此允许更容易的比较。

可以通过以下命令生成参考文档

cargo test generate_target_references_from_fuzz_targets -- --exact

一旦此命令执行完成，新生成的参考文档可以通过测试程序 compare_fuzz_targets_with_target_references 通过以下命令与动态生成的文档进行比较

cargo test compare_fuzz_targets_with_target_references -- --exact

这对于回归测试特别有用，因为可以验证在代码经过大量更改后，库仍然产生相同的输出。

免责声明

测试用例未包含在此库中，因为它们相当庞大，因此我已包括生成代码，并在生成参考文档后在个人机器上进行了测试。建议在开发此库之前，遵循测试程序生成参考文档，然后在代码修改过程中验证输出仍然是可预测的并且与之前完全相同。

与其他库的比较

在开发此库的过程中，我遇到了 pdf_writer，在 PDF 编写实现方面，从任何角度来看都优于此库。因此，虽然我的库（如文档中所述，受 printpdf 启发并改编）涵盖了某些需求，但我认为提供自己的 PDF 实现肯定是一种过度。

我可以做的是通过使用 pdf_writer 库来提供 PDF 编写核心，但由于我的库目前做得很好，因此我目前不会实现此更改。

用 Rust 爱心制作 🦀