編劇

ffx 子工具介面採用 Writer 的概念,用於管理工具和使用者的輸出內容。不同類型的寫入器可區分要由互動式使用者讀取的輸出內容,以及供其他程式和指令碼使用的結構化輸出內容。

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

所有寫入者也會實作一些便利函式,滿足基本寫入需求 (例如 printline)。只有在該指令不是在機器模式下執行時,這些函式才會產生輸出內容。否則將遭到忽略。

所有寫入者也會實作 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> 這類項目,以免讓使用者仰賴非結構化的輸出內容。