ffx 子工具接口有一个概念称为 Writer,用于管理来自工具和用户的输出。不同类型的 Writer 用于区分旨在供交互式用户读取的输出和旨在供其他程序和脚本使用的结构化输出。
在大多数情况下,您可以像使用 std::io::Write 的任何实现一样使用 Writer,并且可以针对任何非结构化字符串输出使用 writeln!() 或类似的内置宏。
所有 Writer 还实现了一些便捷函数,以满足基本的写入需求,例如 print 和 line。不过,这些便捷函数仅在命令未以机器模式运行时才会生成输出。
例如:
writer.line("This is a human friendly message")?;
writer.machine(&theMessageObject)?;
系统只会写入其中一行,具体取决于命令是否以机器模式运行。如果命令未以机器模式运行,系统将输出“This is a human friendly message”这一行。如果命令以
机器模式运行,系统将输出 &theMessageObject 引用的消息。
所有 Writer 还实现了 item,该函数将以机器模式输出给定的对象,或者使用其 Display 实现以非机器模式将对象作为文本输出。
不同的实现实现了 ToolIO 特征。
子工具作者应根据子工具的使用方式使用适当的实现。
SimpleWriter
SimpleWriter 结构体是写入者中最基本的结构体。如果不需要支持结构化输出,并且对如何使用它没有任何限制或准则,则应使用此结构。与直接使用 stdio 相比,SimpleWriter 的优势在于可以使用缓冲区实例化 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 特征的对象类型。
VerifiedMachineWriter
The VerifiedMachineWriter 结构体基于 MachineWriter
行为,并添加了 JSON 架构支持。此架构旨在描述输出的结构,以便对其进行反序列化。该架构还用于检测随时间发生的变化,以促进与其他工具和脚本的集成向后兼容,这样一来,就不会因更新 ffx 工具而出现中断,或者至少可以了解并适应这些中断。
如需使用 VerifiedMachineWriter,FfxMain 中 Writer 属性的声明
需要实现
serde::Serialize特征和schemars::JsonSchema的对象类型。
如何指定 Writer 类型
在此子工具接口中,您可以将此指定为工具的 FfxMain 特征的关联类型,并且机器类型是 MachineWriter 类型的泛型实参。如果您的工具未实现机器
输出,则应使用 SimpleWriter,而不是
MachineWriter<String>之类的类型,以避免用户依赖您的非结构化
输出。