• 韓國語 (國漢文)
    • Rust
    JSR

      辭典 形式

      이 文書는 gukhanmun-mkdict가 消費하는 正規化된 辭典 入力 形式과, 그 入力에서 産出되는 FST/CDB 辭典 파일 配置를 明細합니다. 이는 辭典 抽出器, 使用者가 維持하는 用語集, 백엔드 빌더 사이의 境界입니다.

      正準 TSV 入力

      主 入力 形式은 必須 헤더 行을 가진 UTF-8 TSV입니다. 各 파일은 적어도 다음 列을 包含해야 합니다:

      列必須意味
      hanja예찾기 키로 使用되는 出處 表記.
      hangul예그 키에 對해 내보내는 한글 讀音.

      다음 選擇的 列이 認識됩니다:

      列基本意味
      require_hanjafalse렌더러가 出處 漢字를 보이게 維持하도록 強制.
      require_hangulfalse렌더러가 한글 倂記를 包含하도록 強制.

      참거짓 값은 true, false, 1, 0입니다. 비어 있는 選擇的 참거짓 셀은 false로 다뤄집니다.

      category, source, note 같은 追加 列은 將來 擴張 餘地로 許容됩니다. 現在의 빌더는 그것들을 消費하지 않으며; 짧은 警告를 내고 그 값을 無視합니다.

      例示:

      hanja	hangul	require_hanja	require_hangul	category
天地	천지	false	false	basic
漢字	한자	true	false	basic
色깔論	색깔론	false	true	mixed

      CSV와 JSONL 入力

      gukhanmun-mkdict는 各 파일 擴張子로부터 入力 파서를 고릅니다. .tsv는 正準 TSV 파서를, .csv는 CSV 파서를, .jsonl은 JSON Lines 파서를 使用하며, 알 수 없는 擴張子는 互換性을 爲해 TSV로 다뤄집니다.

      CSV 파일은 TSV와 같은 헤더 이름을 使用합니다:

      hanja,hangul,require_hanja,require_hangul
天地,천지,true,false

      各 JSONL 줄은 하나의 客體입니다. 참거짓 필드는 snake_case나 camelCase 表記를 모두 받습니다:

      {"hanja":"漢字","hangul":"한자","requireHanja":false,"requireHangul":true}

      倂合 政策

      여러 入力 파일이 提供되거나 한 入力 파일이 hanja 키를 反復할 때, gukhanmun-mkdict는 設定된 倂合 政策을 適用합니다:

      • error: 첫 重複 키에서 失敗합니다. 이것이 基本입니다.
      • first-wins: 첫 項目을 維持하고 以後 重複을 無視합니다.
      • last-wins: 앞선 項目을 마지막 重複으로 置換합니다.

      倂合 後, 項目은 백엔드 인코딩 前에 UTF-8 키 바이트 順으로 整列됩니다. 이로써 같은 正規化 入力과 메타데이터에 對해 生成되는 FST와 CDB 産出物이 決定的이 됩니다.

      빌드 메타데이터

      生成되는 모든 백엔드 파일은 CBOR 메타데이터를 內藏합니다. 最小 키는 다음과 같습니다:

      키出處
      source--metadata source=..., 또는 빈 文字列.
      license--metadata license=..., 또는 빈 文字列.
      build_date--metadata build_date=..., SOURCE_DATE_EPOCH, 또는 1970-01-01T00:00:00Z.
      entry_count倂合된 辭典 項目 數.
      version辭典 파일 形式 版本.
      max_word_chars유니코드 스칼라 값 單位의 最大 키 길이.
      max_key_bytesUTF-8 바이트 單位의 最大 키 길이.
      prefix_countCDB 專用: 接頭 레코드 數.

      entry_count, version, max_word_chars, max_key_bytes, prefix_count은 豫約되어 있으며 --metadata로 提供할 수 없습니다. 다른 --metadata KEY=VAL 雙은 文字列 값으로 保存됩니다.

      再現 可能한 빌드를 爲해, 빌더는 基本的으로 現在 時刻을 使用하지 않습니다. build_date가 明示的으로 넘어오지 않고 SOURCE_DATE_EPOCH가 設定되어 있으면, 그 epoch이 UTC RFC 3339로 形式化됩니다. 두 값 모두 없으면 固定 날짜 1970-01-01T00:00:00Z가 使用됩니다.

      FST 백엔드 파일

      처음 具顯된 백엔드 形式은 fst입니다. 파일은 다음을 담습니다:

      1. 固定된 64바이트 리틀 엔디언 헤더.
      2. CBOR 메타데이터 맵.
      3. fst::Map 바이트.
      4. 連續된 UTF-8 讀音 文字列 테이블.

      固定 헤더 필드는 다음과 같습니다:

      필드크기意味
      magic8GUKHMFST.
      version4파일 形式 版本, 現在 1.
      header length4固定 헤더 길이, 現在 64.
      metadata offset8CBOR 메타데이터의 바이트 오프셋.
      metadata length8CBOR 메타데이터의 바이트 길이.
      FST offset8fst::Map 바이트의 바이트 오프셋.
      FST length8fst::Map 바이트의 바이트 길이.
      readings offset8讀音 文字列 테이블의 바이트 오프셋.
      readings length8讀音 文字列 테이블의 바이트 길이.

      各 FST 키는 hanja 列의 UTF-8 바이트입니다. 各 FST 값은 64비트 整數입니다:

      비트필드
      0-15UTF-8 바이트 單位의 讀音 길이.
      16-23標識 비트필드: 비트 0은 require_hanja, 비트 1은 require_hangul.
      24-63讀音 文字列 테이블 안의 오프셋.

      讀音 바이트는 FST 값이 아니라 讀音 文字列 테이블에 貯藏되는데, 이는 FST 값이 固定 幅 整數이기 때문입니다.

      런타임에 gukhanmun-fst는 固定 헤더와 CBOR 메타데이터를 卽時 디코딩합니다. 그러면 FST 맵 바이트와 連續된 讀音 테이블은 하나의 바이트 背後 貯藏所를 共有합니다: FstDictionary::open()과 FstDictionary::from_bytes()에는 所有된 힙 바이트, FstDictionary::from_static_bytes()에는 靜的 바이트입니다. 이 크레이트는 安全한 파일 基盤 mmap 로더를 일부러 露出하지 않는데, 이는 辭典이 살아 있는 동안 다른 파일 記述子나 프로세스가 寫像된 파일을 不變으로 維持할 것임을 Rust가 強制할 수 없기 때문입니다. entries()와 has_homophone()은 FST를 列擧하므로 全體 辭典 스캔으로 남습니다; 反復되는 同音異義 檢査가 必要한 呼出者는 core의 同音異義 미들웨어의 一括 인덱스를 使用해야 합니다.

      CDB 백엔드 파일

      CDB 백엔드 形式은 cdb입니다. 이는 CDB 키 空間에 內藏된 트라이를 使用합니다: 各 辭典 키의 各 接頭辭가 CDB 키로 쓰입니다. 完全한 辭典 項目인 接頭 레코드는 讀音과 標識 비트를 싣고; 더 긴 項目으로 이어지기만 하는 接頭 레코드는 讀音을 싣지 않습니다.

      오프셋크기필드
      01is_complete (이 接頭辭 自體가 項目이면 1).
      11標識 비트필드: 비트 0은 require_hanja, 비트 1은 require_hangul.
      22UTF-8 바이트 單位의 讀音 길이, 리틀 엔디언; 非完全이면 0.
      4reading_len讀音 바이트.

      메타데이터 CBOR 맵은 豫約 키 __gukhanmun_meta__ 아래에 貯藏됩니다.

      런타임 CDB 백엔드는 cdb 크레이트의 파일 基盤 리더를 使用하고 백엔드를 HanjaDictionary 뒤에 不透明하게 維持합니다. 이는 안전하지 않은 mmap 表面을 더하지 않고도 全體 CDB 파일을 Gukhanmun 所有 버퍼로 불러오는 것을 이미 避합니다.

      檢證

      --validate를 쓰면 gukhanmun-mkdict는 出力을 쓴 뒤 選擇된 백엔드로 다시 열어, 倂合된 모든 項目이 같은 讀音과 標識 비트로 復元될 수 있는지 檢査합니다. 檢證 失敗는 致命的입니다.