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