ffx
子工具介面採用 Writer
的概念,用於管理工具和使用者的輸出內容。不同類型的寫入器可區分要由互動式使用者讀取的輸出內容,以及供其他程式和指令碼使用的結構化輸出內容。
在大部分情況下,您可以使用寫入器,就像實作 std::io::Write
一樣,並且可以只針對非結構化字串輸出使用 writeln!()
或類似的內建巨集。
所有寫入者也會實作一些便利函式,滿足基本寫入需求 (例如 print
和 line
)。只有在該指令不是在機器模式下執行時,這些函式才會產生輸出內容。否則將遭到忽略。
所有寫入者也會實作 item
,進而列印在機器模式中指定的物件,或是使用其 Display
實作,以非機器模式將其輸出為文字。
不同的實作方式會實作 ToolIO 特徵。根據子工具的使用方式,子工具作者應使用適當的實作。
SimpleWriter
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,FfxMain 中的 Writer 屬性宣告需要實作 serde::Serialize 特徵和 schemars::JsonSchema 的物件類型。
如何指定 Writer
類型
在這個子工具介面中,您可以將其指定為工具的 FfxMain
特徵的相關類型,而機器類型是 MachineWriter
類型的通用引數。如果工具沒有實作機器輸出內容,則應使用 SimpleWriter
而非 MachineWriter<String>
這類項目,以免讓使用者仰賴非結構化的輸出內容。