跳至主要內容

XTL 穩定性政策

目前狀態

XTL 目前版本為 0.1。參考實作以 @jinyoung4478/xl3@0.1.0 發布於 npm。1.0 的切版被刻意延後, 直到累積足夠的外部驗證為止——至少要有第二個語言移植版通過 符合性語料庫,並且有一位實際採用的生產用戶。在這之前, 0.x 各次要版本之間可能會出現破壞性變更,並 SHOULD) 在受影響的 ADR 內加以記載。

1.0 將凍結的契約其實已經草擬完成(見下方「邁向 1.0 的路徑」); 之所以延後,是因為對外部訊號的要求,而不是規格還沒寫好。

0.x 期間

  • 規格的破壞性變更會在受影響的 ADR 中記錄,並在下一次次要版本釋出前反映到符合性語料庫。
  • 參考實作(npm 上的 xl3)的 API 自身遵循 SemVer;規格層級的破壞性變更會使規格次要版本遞增。
  • 實作應宣告自己對齊的規格版本(例如 XTL 0.2 partialXTL 0.3 full)。

1.0 之後

  • 規格凍結,僅接受向下相容的演進。
  • 規格上的破壞性變更需要走 XTL 2.0 流程,含公開討論與遷移指南。
  • 參考實作嚴格遵循 SemVer。

邁向 1.0 的路徑

1.0 切版會封存 XTL 的第一份可移植性契約。意圖是:在凍結後的 fixture 語料庫上,任何符合規格的實作,不論在何種主機時區、地區設定 或位元順序下,都應產出完全相同的輸出(Stage 1)與完全相同的 正規 OOXML(Stage 2)。

公開 API 介面(xl3 參考實作)

TypeScript 參考實作會在 1.0 時凍結下列 13 個執行階段 匯出。新增匯出屬向下相容;移除或重新命名其中任何一個都 只能在 2.0 進行。

轉換的進入點

  • convert(template, source, options?) → Promise<OutputFile[]>
  • preview(template, source, options?) → Promise<PreviewResult>
  • readTemplateInputs(template) → Promise<InputSpec[]>
  • analyze(template) → Promise<ParsedTemplate>
  • analyzeModel(template) → Promise<TemplateModel>
  • packageZip(files) → Promise<Blob>

較低階的輔助函式

  • readConfigSheet(workbook) → ConfigResult
  • writeConfigSheet(workbook, meta) → void
  • readInputsSheet(workbook, configVars?) → InputSpec[](依 ADR-0050,在 0.6.0 新增了可選的 configVars 參數;以單一 參數呼叫仍然有效)
  • batchMatch(...)——檔案模式比對輔助函式
  • toTemplateModel(parsed) → TemplateModel

錯誤輔助函式(ADR-0015)

  • xtlError(code, message) → XtlError
  • isXtlError(value) → boolean

穩定的型別重新匯出——在 1.0 時凍結: TemplateMetaTemplateModelOutputFilePreviewResultPreviewSourcePreviewFilePreviewSheetConvertOptionsInputSpecInputTypeSourceSpecXtlErrorXtlErrorCodeXtlWarningXtlWarningCode

實驗性的型別重新匯出(ROADMAP G22)——為工具鏈而匯出, 但其外觀 可能MAY)在次要版本之間變動: ParsedTemplateSheetTemplateTemplateVariableDataBlockDirectiveFilterDirectiveFilterOpSortDirectiveTopDirectiveRepeatDirectiveSourceDirectiveJoinDirective

每個實驗性型別都帶有 @experimental JSDoc 標籤。持有上述任一 物件的宿主 SHOULD)以 kind 進行分派(針對指令), 或把整個外觀視為不透明;若依賴特定欄位組合,則 SHOULD) 釘住特定的 xl3 次要版本。對多數工具鏈需求而言,可序列化、變動較慢 的替代方案是 TemplateModel(由 analyzeModel 回傳)。

src/__tests__/api-surface.test.ts 的快照測試會釘住執行階段匯出 清單,並在未經宣告的變動時讓 CI 失敗。新增匯出必須刻意更新 快照,並同步寫入 CHANGELOG 條目。

1.0 凍結的內容

下列 ADR 所涵蓋的介面,屬於 1.0 契約的一部分。破壞性變更 需要切出 XTL 2.0。

  • ADR-0001 — TODAY() UTC 語意
  • ADR-0002 — 輸出檔名清理
  • ADR-0003 — 由 numFmt 驅動的強制轉型
  • ADR-0005 — 動態符合性斷言協定
  • ADR-0006 — Stage 2 正規 OOXML 比較(規則 1-8 加上列出落差項目的 修訂)
  • ADR-0007 — 空值判定式
  • ADR-0008 — 真假性規則
  • ADR-0009 + ADR-0017 — 比較演算法與來源值模型(兩者 合在一起視為單一契約)
  • ADR-0010 + ADR-0011 — 執行階段輸入與保留工作表命名
  • ADR-0012 — 多來源資料模型
  • ADR-0013 — XLOOKUP 跨來源查找
  • ADR-0014 — @join 區塊層級配對(單一內部合併、 決定性首筆相符)
  • ADR-0015 — 結構化錯誤回報(xl3/... 代碼 + 英文 符合性訊息)
  • ADR-0016 — 排序與排序穩定性
  • ADR-0033 — 合併儲存格的來源表頭
  • ADR-0035 — 資料列合併儲存格廣播
  • ADR-0036 — 範本特性保留矩陣
  • ADR-0038 — @group + @subtotal 指令(交錯排放小計)
  • ADR-0039 — HYPERLINK 儲存格輸出
  • ADR-0040 — 保留矩陣修訂(大綱層級已交付; CF/DV 範圍 PE 待 0.6.1 處理)
  • ADR-0041 — 多行儲存格文字契約
  • ADR-0044 — 函式批次(UPPER、LOWER、TRIM、IFERROR、IFS、DATE)
  • ADR-0046 — 儲存格公式保留(OOXML 元素契約)
  • ADR-0047 — ISBLANK 作為 IFEMPTY 別名
  • ADR-0050 — __inputs__defaultlabeldescriptionoptions 視為 XTL 範本
  • ADR-0051 — {{ ... }} 區塊分隔邊界 + 不成對字面值偵測
  • ADR-0052 — 單一運算式 vs. 混合文字儲存格的分類(先 trim 再做錨定 匹配;相鄰區塊一律視為混合文字)
  • ADR-0053 — 混合文字情境下 Excel 錯誤標記的傳播
  • ADR-0054 — 儲存格/檔案/工作表樣式中的裸名稱 (簡寫解析 + xl3/expression/unknown-name
  • ADR-0055 — @top@repeat right 的正整數語法
  • ADR-0056 — __config__[system-key] 讀取政策
  • ADR-0057 — @filter in/!in 以外場合拒絕使用 __lists__[name]
  • ADR-0058 — @subtotal 列組成(同列層級綁定)
  • ADR-0059 — 彙總函式引數形狀(僅接受欄參考)
  • ADR-0060 — XLOOKUP 值/後備引數規則(後備採延遲求值)
  • ADR-0061 — 來源名稱 vs. 函式名稱的詞法消歧 (保留 ADR-0024 擴充原樣透通)
  • ADR-0062 — __inputs__ default = "" 語意
  • ADR-0063 — __inputs__ options 以豎線分隔的規則
  • ADR-0064 — 字串→數字強制轉型的範圍(接受科學記號; hex/binary/octal 拒絕)
  • ADR-0065 — @source default 顯式形式 + 來源名稱大小寫 敏感性
  • ADR-0021(群組順序修訂)— 當 @sort 不相符時的 群組順序由實作自訂
  • ADR-0041(表頭修訂)— 表頭儲存格換行的正規化

ADR-0043 與 ADR-0048 為 流程規範性——它們約束未來 ADR 作者,但不約束執行階段契約。ADR-0034 與 ADR-0049 為 資訊性。ADR-0004 為資訊性(參考實作耦合度稽核)。ADR-0037、 ADR-0042、ADR-0045 為已駁回(駁回本身即契約)。

1.0 不包含的內容

下列項目刻意延後處理。加入它們屬向下相容, 不需要新的規格主要版本。

  • 單一區塊中多個 @join 指令、@join … left 語意、 多列相符合併(ADR-0014 明列的範圍外清單)。
  • XLOOKUP 萬用字元、近似比對與反向查找模式 (ADR-0013 明列的範圍外清單)。
  • 區域感知的字串排序。排序使用 Unicode 碼位 順序;需要區域排序的宿主請在上游先行排序。
  • 日期/日期時間運算函式(不含 EOMONTHEDATEDATEDIF 等)。
  • ADR-0006 修訂中落差項目的跨寫入器正規化(預設屬性等價、 色彩 hex 大小寫、命名空間前綴繫結)。
  • 一份規範性的 wire format,涵蓋 ADR-0010 / ADR-0012 中 宿主 API 介面以外的輸入、來源或輸出。

符合性基線

1.0 的符合性語料庫為標記 spec_version: "0.1" 之 fixture 與 1.0 切版前新增之 fixture 的聯集。整套語料庫 必須通過:

  1. Stage 1 儲存格值比較。
  2. 對於宣告 comparison_stage: 2 的 fixture,須進行 Stage 2 正規 OOXML 比較。
  3. 在至少三個時區(UTCAmerica/New_YorkAsia/Seoul)下執行 Stage 1——參考儲存庫的 CI workflow 會跑這組矩陣;移植版 SHOULD)也比照辦理。

宣稱符合 1.0 的實作 必須MUST)回報其在此語料庫上 的符合性執行結果,且 不得MUST NOT)跳過任何 fixture, 除非該 fixture 所宣告的比較階段高於該執行器所支援的階段。

核心 vs. 擴充

規格區分:

  • 核心——符合性所要求的語言特性。在 README.md 摘要,並由 language.mdevaluation.md 正式定義。此處的破壞性變更會觸發規格版本事件。
  • 擴充——實作特定或領域特定的擴充。各實作之間 可能MAY)不同。記錄於實作各自的 README,而非規格中。

實作 可以MAY)加入擴充,但 不得MUST NOT)默默改變核心語意。

例如,實作可以支援 XTL 0.1 核心表格以外的 TEXT() 格式。這類格式 屬於擴充:可移植的範本不應依賴它們,符合性 fixture 也不要求對它們 產出完全相同的輸出。

符合性語料庫版本控管

符合性語料庫版本與規格版本一同前進。於規格 0.3 新增的 fixture 會 被標示為對應版本;實作則宣告自己通過哪些 fixture,從而宣告自己 符合到哪一個規格版本。

棄用政策(1.0 之後)

當某項特性將在未來主要版本中移除時:

  1. 該特性 SHOULD)在規格內被標示為 deprecated, 並維持至少一個次要版本後才得移除。
  2. 使用該棄用特性的符合性 fixture 會加上 deprecated 標籤。
  3. 鼓勵實作在使用該棄用特性時發出警告。
  4. 移除動作會落在下一個主要版本(例如 1.3 棄用 → 2.0 移除)。