编剧

ffx 子工具接口具有管理输出的 Writer 的概念 来自工具和用户的不同类型的写入者用于 区分供交互式用户阅读的输出和 供其他程序和脚本使用的结构化输出。

在大多数情况下,您可以像使用任何 std::io::Write,也可以只使用 writeln!() 或类似内置功能 宏用于任何非结构化字符串输出。

所有作者还会实现一些便捷功能,以满足基本写作需求 例如 printline。不过,这些便捷函数只会生成 输出。

例如:

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>,以避免让用户依赖于非结构化 输出。