# SDCL 資料格式完全指南 --- ## 目錄 1. [核心語法規範](#核心語法規範) 2. [類型系統](#類型系統) 3. [多行字串處理](#多行字串處理) 4. [資料結構與嵌套](#資料結構與嵌套) 5. [錯誤代碼與除錯](#錯誤代碼與除錯) 6. [最佳實踐](#最佳實踐) 7. [附錄](#附錄) --- ## 核心語法規範 ### 基本結構 ```sdcl # 鍵值對 (冒號周圍空白無限制) key : value "特殊鍵名" :{ nested: object } list :[ item1, item2 ] # 等價的括號形式 ({} / [] / ()) data1: { a:1, b:2 } # 緊湊格式 data2 : [ a : 1 , b :2 ] # 寬鬆空白 ``` ### 空白字符規則 | 位置 | 規則 | |---------------------|----------------------------------------------------------------------| | 鍵名與冒號之間 | 允許零或多個空白字符 | | 冒號與值之間 | 允許零或多個空白字符 | | 值內部 | 連續非空白字符視為獨立值 (多行字串除外) | --- ## 類型系統 ### 強制類型標籤 (嚴格閉合規則) | 標籤 | 語法範例 | 合法值範圍 | 錯誤範例 | |-----------------|----------------------------|-------------------------------------|--------------------------| | `` | `0xFF` → 255 | 整數 (支援二/八/十/十六進制) | `3.14` | | `` | `3.14e-5` | IEEE 754 浮點數 | `0b1010` | | `` | `TRUE` → true | true/TRUE/1 / false/FALSE/0 | `yes` | | `` | `2023-10-01` | ISO 8601 日期 (YYYY-MM-DD) | `20231001` | | `` | `2023-10-01T14:30:00Z` | ISO 8601 時間戳 | `2023-10-01 14:30` | | `` | `` 或 `` | 空值標記 | ` ` | ### 預設類型推斷規則 | 輸入值 | 推斷類型 | 範例 | |-------------|-----------|---------------------| | 純數字 | int | `42` → `` | | 含小數點 | float | `3.14` → `` | | true/false | bool | `TRUE` → `` | | 其他字串 | string | `text` → `` | --- ## 多行字串處理 ### 等效語法形式 ```sdcl # 形式 1：縮進塊 (自動去除首尾空行) text1: Line 1 Line 2 # 形式 2：引號包裹 (支援 "" 和 '') text2: " Line 1 Line 2 " text3: ' Line 1 Line 2 ' # 形式 3：標籤包裹 text4: Line 1 Line 2 ``` ### 引號行為對照 | 引號類型 | 轉義處理 | 範例輸入 | 解析結果 | |----------|-------------------------------|--------------------|-------------------| | `""` | 解析 `\n` `\t` `\"` `\\` | `"Line\nEnd"` | 換行 + "End" | | `''` | 原始字面量 | `'Line\nEnd'` | `Line\nEnd` | --- ## 資料結構與嵌套 ### 複雜結構範例 ```sdcl server: { # 類型強制轉換 ports: [ 80, "443", # 自動轉換為 443 0o12 # 八進制 → 10 ] # 日期時間處理 maintenance: 2023-12-31T23:59:59+08:00 # 多層嵌套 users: [ { name: "Alice", join_date: 2020-01-15 }, { name: "Bob", join_date: 2021-03-22 } ] } ``` --- ## 錯誤代碼與除錯 ### 完整錯誤代碼表 | 錯誤代碼 | 類型 | 觸發條件範例 | 解決方案 | |----------|-----------------------|------------------------------|------------------------| | **S101** | 縮進不一致 | 多行縮進量不同 | 統一縮進空格數 | | **T001** | 類型轉換失敗 | `3.14` | 檢查輸入格式 | | **T002** | 標籤未閉合 | `unclosed` | 補全閉合標籤 | | **S102** | 非法字符 | `key: #value` (無空格註解) | 添加註解前空格 | | **D001** | 日期格式錯誤 | `2023/10/01` | 改用 ISO 8601 格式 | | **D002** | 時間格式錯誤 | `2023-10-01` | 需包含時間部分 | | **T003** | 參數類型不匹配 | `abc` | 檢查輸入是否為數字 | | **S103** | 未轉義引號 | `"Text with ""` | 使用 `\"` 轉義 | | **T004** | 無效標籤名稱 | `text` | 使用標準類型標籤 | ### 除錯輸出範例 ```sdcl # 錯誤輸入 err_data: 20231001 # 錯誤信息 [ERROR] Line 5, Column 12-28 Code: 20231001 ~~~~~~~~~~~~~~~~~ Error D001: 日期格式不符合 ISO 8601 (YYYY-MM-DD) ``` --- ## 最佳實踐 ### 類型安全建議 1. **顯式聲明日期時間** ```sdcl # ✅ 明確時區 expire: 2025-12-31T23:59:59Z # ❌ 隱含風險 expire: "2025-12-31" # 可能被誤認為字串 ``` 2. **二進制數據標記** ```sdcl # 使用 base64 標籤 certificate: MIIE...AA== ``` 3. **多行結構格式化** ```sdcl policy: This is a multi-line security policy document Version: 2.1 ``` --- ## 附錄 ### 速查表 | 語法 | 等效形式 | 輸出範例 | |---------------------------|------------------------------|-----------------------| | `key: "text"` | `key: text` | `"text"` | | `num: 0b1010` | `num: 10` | `10` | | `flag: 1` | `flag: true` | `true` | | `time: 2023-10-01T00:00:00Z` | ISO 時間戳 | `Date 物件` | ### 工具命令參考 ```bash # 驗證文件語法 sdcl validate input.sdcl # 格式化輸出 sdcl format input.sdcl --multiline # 錯誤代碼查詢 sdcl explain-error D001 ```

OGATA 標準通用數據字符儲存格式語言

Ray

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

KEJILION

支持