SDCL 資料格式完全指南

核心語法規範

基本結構

# 鍵值對 (冒號周圍空白無限制)
key :  value
"特殊鍵名" :{ nested: object }
list :[ item1, item2 ]

# 等價的括號形式 ({} / [] / ())
data1: { a:1, b:2 }  # 緊湊格式
data2 : [ a : 1 , b :2 ]  # 寬鬆空白

空白字符規則

| 位置 | 規則 |
|---------------------|----------------------------------------------------------------------|
| 鍵名與冒號之間 | 允許零或多個空白字符 |
| 冒號與值之間 | 允許零或多個空白字符 |
| 值內部 | 連續非空白字符視為獨立值 (多行字串除外) |

類型系統

強制類型標籤 (嚴格閉合規則)

| 標籤 | 語法範例 | 合法值範圍 | 錯誤範例 |
|-----------------|----------------------------|-------------------------------------|--------------------------|
| <int></int> | <int>0xFF</int> → 255 | 整數 (支援二/八/十/十六進制) | <int>3.14</int> |
| <float></float> | <float>3.14e-5</float> | IEEE 754 浮點數 | <float>0b1010</float> |
| <bool></bool> | <bool>TRUE</bool> → true | true/TRUE/1 / false/FALSE/0 | <bool>yes</bool> |
| <date></date> | <date>2023-10-01</date> | ISO 8601 日期 (YYYY-MM-DD) | <date>20231001</date> |
| <datetime></datetime> | <datetime>2023-10-01T14:30:00Z</datetime> | ISO 8601 時間戳 | <datetime>2023-10-01 14:30</datetime> |
| <null> | <null> 或 <null/> | 空值標記 | <null> </null> |

預設類型推斷規則

| 輸入值 | 推斷類型 | 範例 |
|-------------|-----------|---------------------|
| 純數字 | int | 42 → <int> |
| 含小數點 | float | 3.14 → <float> |
| true/false | bool | TRUE → <bool> |
| 其他字串 | string | text → <str> |

多行字串處理

等效語法形式

# 形式 1：縮進塊 (自動去除首尾空行)
text1:
  Line 1
  Line 2

# 形式 2：引號包裹 (支援 "" 和 '')
text2: "
  Line 1
  Line 2
"
text3: '
  Line 1
  Line 2
'

# 形式 3：標籤包裹
text4: <str>
  Line 1
  Line 2
</str>

引號行為對照

| 引號類型 | 轉義處理 | 範例輸入 | 解析結果 |
|----------|-------------------------------|--------------------|-------------------|
| "" | 解析 \n \t \" \\ | "Line\nEnd" | 換行 + "End" |
| '' | 原始字面量 | 'Line\nEnd' | Line\nEnd |

資料結構與嵌套

複雜結構範例

server: {
  # 類型強制轉換
  ports: <int>[ 
    80, 
    "443",  # 自動轉換為 443
    0o12    # 八進制 → 10
  </int> ]

  # 日期時間處理
  maintenance: <datetime>
    2023-12-31T23:59:59+08:00
  </datetime>
  
  # 多層嵌套
  users: [
    { 
      name: "Alice", 
      join_date: <date>2020-01-15</date> 
    },
    { name: "Bob", join_date: <date>2021-03-22</date> }
  ]
}

錯誤代碼與除錯

完整錯誤代碼表

| 錯誤代碼 | 類型 | 觸發條件範例 | 解決方案 |
|----------|-----------------------|------------------------------|------------------------|
| S101 | 縮進不一致 | 多行縮進量不同 | 統一縮進空格數 |
| T001 | 類型轉換失敗 | <int>3.14</int> | 檢查輸入格式 |
| T002 | 標籤未閉合 | <str>unclosed | 補全閉合標籤 |
| S102 | 非法字符 | key: #value (無空格註解) | 添加註解前空格 |
| D001 | 日期格式錯誤 | <date>2023/10/01</date> | 改用 ISO 8601 格式 |
| D002 | 時間格式錯誤 | <datetime>2023-10-01</datetime> | 需包含時間部分 |
| T003 | 參數類型不匹配 | <int>abc</int> | 檢查輸入是否為數字 |
| S103 | 未轉義引號 | "Text with "" | 使用 \" 轉義 |
| T004 | 無效標籤名稱 | <invalid>text</invalid> | 使用標準類型標籤 |

除錯輸出範例

# 錯誤輸入
err_data: <date>20231001</date>

# 錯誤信息
[ERROR] Line 5, Column 12-28
Code: <date>20231001</date>
       ~~~~~~~~~~~~~~~~~
Error D001: 日期格式不符合 ISO 8601 (YYYY-MM-DD)

最佳實踐

類型安全建議

顯式聲明日期時間

   # ✅ 明確時區
   expire: <datetime>2025-12-31T23:59:59Z</datetime>
   
   # ❌ 隱含風險
   expire: "2025-12-31"  # 可能被誤認為字串

二進制數據標記

   # 使用 base64 標籤
   certificate: <base64>MIIE...AA==</base64>

多行結構格式化

   policy: <str>
     This is a multi-line
     security policy document
     Version: 2.1
   </str>

附錄

速查表

| 語法 | 等效形式 | 輸出範例 |
|---------------------------|------------------------------|-----------------------|
| key: "text" | key: <str>text</str> | "text" |
| num: 0b1010 | num: <int>10</int> | 10 |
| flag: <bool>1</bool> | flag: true | true |
| time: <datetime>2023-10-01T00:00:00Z</datetime> | ISO 時間戳 | Date 物件 |

工具命令參考

# 驗證文件語法
sdcl validate input.sdcl

# 格式化輸出
sdcl format input.sdcl --multiline

# 錯誤代碼查詢
sdcl explain-error D001