ffx
子工具介面具有管理輸出內容的 Writer
概念
具體呈現這些資訊不同類型的 Writer 用於區分要供互動使用者閱讀的輸出內容,以及要供其他程式和指令碼使用的結構化輸出內容。
在大多數情況下,您可以使用寫入器,就像使用 std::io::Write
的任何實作一樣,只要針對任何非結構化字串輸出,使用 writeln!()
或類似的內建巨集即可。
所有寫入者也實作了一些便利的功能,來滿足基本的寫作需求
例如 print
和 line
。不過,只有在指令未以機器模式執行時,這些方便函式才會產生輸出內容。
例如:
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>
之類的內容,以免使用者依賴非結構化輸出內容。