編劇

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

在大部分的情況下,您可以像任何實作 std::io::Write,而且只要使用 writeln!() 或類似的內建項目即可 巨集。

所有寫入者也實作了一些便利的功能,來滿足基本的寫作需求 例如 printline。然而,這些便利函式只會在 則為輸出顯示。

例如:

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

視 指令在機器模式下執行如果指令未處於機器模式, 「這是一則易懂的訊息」會先列印。如果指令 在機器模式中,系統會列印 &theMessageObject 參照的訊息。

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

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

SimpleWriter

SimpleWriter 結構是 Writer 最基本的一種。 當無需支援結構化輸出內容,且有 沒有使用限製或使用方式規範SimpleWriter 的優勢 而非直接使用 stdio,那就是 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,聲明 Writer 屬性 必須在 FfxMain 中需要實作 serde::Serialize 特徵和 schemars::JsonSchema

如何指定 Writer 類型

在這個子工具介面中,您將這個屬性指定為 適用於工具的 FfxMain 特徵,而機器類型為一般 MachineWriter 類型的引數。如果您的工具無法實作 輸出內容時,應使用 SimpleWriter,而不是 MachineWriter<String>,避免員工依賴非結構化資料 輸出內容