編劇

ffx 子工具介面具有管理輸出內容的 Writer 概念 具體呈現這些資訊不同類型的 Writer 用於區分要供互動使用者閱讀的輸出內容,以及要供其他程式和指令碼使用的結構化輸出內容。

在大多數情況下,您可以使用寫入器,就像使用 std::io::Write 的任何實作一樣,只要針對任何非結構化字串輸出,使用 writeln!() 或類似的內建巨集即可。

所有寫入者也實作了一些便利的功能,來滿足基本的寫作需求 例如 printline。不過,只有在指令未以機器模式執行時,這些方便函式才會產生輸出內容。

例如:

writer.line("This is a human friendly message")?;
writer.machine(&theMessageObject)?;

視 指令在機器模式下執行如果指令不在機器模式中,系統會列印「This is a human friendly message」這行。如果指令 在機器模式中,系統會列印 &theMessageObject 參照的訊息。

所有寫入者也會實作 item,來列印物件 或透過其 Display 實作來輸出 非機器模式文字

不同的導入方式會實作 ToolIO 特徵。 子工具作者應該根據子工具的使用方式 請使用適當的實作方式

SimpleWriter

SimpleWriter 結構是 Writer 最基本的一種。 當無需支援結構化輸出內容,且有 沒有使用限製或使用方式規範相較於直接使用 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

VerifiedMachineWriter 結構體以 MachineWriter 行為為基礎,並新增 JSON 結構定義支援。這個結構定義旨在說明輸出的結構,以便進行反序列化。結構定義也用於 隨時偵測變更,提高與整合功能的回溯相容性 不會因為 更新 ffx 工具,或至少已知且可以因應

如要使用 VerifiedMachineWriter,FfxMain 中 Writer 屬性的宣告必須使用實作 serde::Serialize 特徵和 schemars::JsonSchema 的物件類型。

如何指定 Writer 類型

在這個子工具介面中,您可以將此類型指定為工具 FfxMain 特徵的關聯類型,而機器類型是 MachineWriter 類型的一般引數。如果工具未實作機器輸出內容,則應使用 SimpleWriter,而非 MachineWriter<String> 之類的內容,以免使用者依賴非結構化輸出內容。