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