ffx
子工具接口具有 Writer
的概念,用于管理工具和用户的输出。不同类型的 Writer 用于区分供交互式用户读取的输出和供其他程序和脚本使用的结构化输出。
在大多数情况下,您可以像使用 std::io::Write
的任何实现一样使用写入器,并且针对任何非结构化字符串输出只需对其使用 writeln!()
或类似的内置宏即可。
所有编写者还会实现一些便捷函数来满足基本的编写需求,例如 print
和 line
。只有在命令不是在机器模式下运行时,这些函数才会生成输出。否则,它们将被忽略。
所有写入者也都会实现 item
,它会输出机器模式下提供的对象,或使用其 Display
实现以文本形式将其输出到非机器模式下。
不同的实现实现了 ToolIO trait。 子工具作者应根据子工具的使用方式,使用适当的实现。
SimpleWriter
SimpleWriter 结构体是最基础的 Writer 结构。 当不需要支持结构化输出并且没有使用任何限制或指南时,应使用此类型。与直接使用 stdio 相比,SimpleWriter 的优势在于可以使用缓冲区对其进行实例化,从而更轻松地测试输出。如需创建受缓冲区支持的 SimpleWriter,请参阅 new_with_buffers()。
MachineWriter
MachineWriter 结构体在 SimpleWriter 的基础上添加方法实现以支持结构化输出:
machine
:在机器模式下仅输出给定对象。machine_many
:在机器模式下输出给定对象。machine_or
:如果是在机器模式下,则输出对象。否则,就输出另一个参数中的文本信息(实现Display
)。machine_or_else
:如果是在机器模式下,则输出对象。否则,输出另一个参数中的函数生成的文本信息。
MachineWriter
的输出格式由 ffx 的顶级命令行参数 --machine
控制。
当需要支持以程序化方式处理输出时,应使用 MachineWriter。由于 machine()
方法用于生成输出,因此该子工具应对所有可能的输出(包括错误)使用 machine()。这样,子工具的调用方就可以处理和呈现以结构化方式遇到的错误,而不是回退到 stderr 上的非结构化数据。
如需使用 MachineWriter,则在 FfxMain 中声明 Writer 属性需要一个实现 serde::Serialize trait 的对象类型。
VerifiedMachineWriter
VerifiedMachineWriter 结构体基于 MachineWriter 行为构建,并添加 JSON 架构支持。此架构旨在描述输出的结构,以便可以进行反序列化。该架构还用于检测随时间的变化,以促进与其他工具和脚本的集成的向后兼容性,以便最终不会因更新 ffx 工具而出现中断,或者至少是已知且可适应的。
如需使用 VerifiedMachineWriter,FfxMain 中的 Writer 属性声明需要实现 serde::Serialize 特征和 schemars::JsonSchema 的对象类型。
如何指定 Writer
类型
在此子工具接口中,您可以在工具的 FfxMain
trait 上将此类型指定为关联类型,并且机器类型是 MachineWriter
类型的通用参数。如果您的工具不实现机器输出,则应使用 SimpleWriter
而不是 MachineWriter<String>
之类的代码,以避免用户依赖于非结构化输出。