################################################################################
# Jacode4e 速查表 (ZH)
# Jacode4e - Converts Character Encodings for Enterprise in Japan
# https://metacpan.org/dist/Jacode4e
# Copyright (c) 2026 INABA Hitoshi <ina.cpan@gmail.com>
################################################################################

======================================================================
Jacode4e 快速参考手册（简体中文）
======================================================================

[基本用法]

  use FindBin;
  use lib "$FindBin::Bin/lib";
  use Jacode4e;

  $char_count = Jacode4e::convert(\$line, $OUTPUT_encoding, $INPUT_encoding);
  $char_count = Jacode4e::convert(\$line, $OUTPUT_encoding, $INPUT_encoding, { %option });

  $line             : 要转换的字符串（按引用传递，就地覆盖）
  $OUTPUT_encoding  : 输出编码名称
  $INPUT_encoding   : 输入编码名称
  $char_count       : 转换后的字符数

[编码名称一览]

  mnemonic    description
  ---------   ---------------------------------------------------
  cp932x      CP932X (Extended CP932 to JIS X 0213, single-shift 0x9C5A)
  cp932       Microsoft CP932 (Windows-31J / IANA registered name)
  cp932ibm    IBM CP932
  cp932nec    NEC CP932
  sjis        JISC Shift_JIS (JIS X 0201, JIS X 0208); year editions below
  sjis2004    JISC Shift_JIS-2004 (JIS X 0213:2004)
  euc         JISC EUC-JP (JIS X 0201, JIS X 0208, JIS X 0212); year editions below
  euc2004     JISC EUC-JIS-2004 (JIS X 0213 plane 1 and plane 2)
  jis         JISC ISO-2022-JP (JIS X 0201, JIS X 0208, JIS X 0212); year editions below
  jis2004     JISC ISO-2022-JP-2004 (JIS X 0213 plane 1 and plane 2)
  cp00930     IBM CP00930 (CP00290+CP00300, CCSID 5026 katakana)
  keis78      HITACHI KEIS78
  keis83      HITACHI KEIS83
  keis90      HITACHI KEIS90
  jef         FUJITSU JEF (12pt, use OUTPUT_SHIFTING option for shift codes)
  jef9p       FUJITSU JEF ( 9pt, use OUTPUT_SHIFTING option for shift codes)
  jipsj       NEC JIPS(J)
  jipse       NEC JIPS(E)
  letsj       UNISYS LetsJ
  utf8        UTF-8.0 (aka UTF-8)
  utf8.1      UTF-8.1 (conversion based on Shift_JIS-to-Unicode mapping, not CP932)
  utf8jp      UTF-8-SPUA-JP (JIS X 0213 on SPUA ordered by JIS level/plane/row/cell)

  sjis / euc / jis 的年代版本（无年份者为 1990 年版）：
    sjis1978  euc1978  jis1978   JIS C 6226-1978
    sjis1983  euc1983  jis1983   JIS X 0208-1983
    sjis1990  euc1990  jis1990   JIS X 0208-1990  (= sjis / euc / jis)
    sjis2000  euc2000  jis2000   JIS X 0213:2000
    sjis2004  euc2004  jis2004   JIS X 0213:2004

[JIS 标准各年代差异（面向初学者）]

  日文汉字是分阶段标准化的。不同版本中相同的字节可能表示不同的字符，因此请选择与数据相符的版本。若不确定，请使用无年份的 sjis / euc / jis。

  1978 (JIS C 6226-1978) : 最早的汉字标准（第 1 水准与第 2 水准）。
  1983 (JIS X 0208-1983) : 交换了 22 对汉字的编码位置并更改了部分字形；旧数据乱码的最常见原因。
  1990 (JIS X 0208-1990) : 仅新增 2 个汉字（U+51DC、U+7199）；无年份的 sjis / euc / jis 即此版本。
  2000 (JIS X 0213:2000) : 大幅扩充；在新的第 2 面新增第 3、第 4 水准汉字与符号。
  2004 (JIS X 0213:2004) : 新增 10 个汉字并更改 168 个汉字的示例字形（编码与 2000 年版相同，仅字形改变）。

[选项一览]

  选项作为第 4 个参数传入：{ 'KEY' => 值, ... }

  INPUT_LAYOUT
    用 'S'（1 字节 SBCS）和 'D'（2 字节 DBCS）指定固定记录布局；字母后可跟重复次数。默认：自动。
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'INPUT_LAYOUT'=>'S2D2SD'});

  OUTPUT_SHIFTING
    为真时在 DBCS 段前后输出移出/移入码。默认：假。
    e.g. Jacode4e::convert(\$line,'jef','cp932x',{'OUTPUT_SHIFTING'=>1});

  SPACE
    DBCS/MBCS 空格填充码（二进制字符串）。默认：该编码的空格。
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'SPACE'=>"\x81\xA1"});

  GETA
    用于无法映射字符的 DBCS/MBCS 填充（geta）码。
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'GETA'=>"\x81\xA2"});

  OVERRIDE_MAPPING
    逐字符 FROM => TO 覆盖的哈希引用（同时覆盖 SPACE）。
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'OVERRIDE_MAPPING'=>{"\x44\x5A"=>"\x81\x7C"}});

  JIS_SOSI
    为真：'jis' 输入时把 SO(0x0E)/SI(0x0F) 视为切换到 JIS X 0201 片假名（JIS7 习惯）。默认：假；输入为 'jis' 时有效。
    e.g. Jacode4e::convert(\$line,'utf8','jis',{'JIS_SOSI'=>1});

  JIS_X0212
    为真：'jis' 输出时，将属于 JIS X 0212 但不属于 JIS X 0208 的字符写为 ESC $ ( D。需要 OUTPUT_SHIFTING。默认：假。
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_X0212'=>1,'OUTPUT_SHIFTING'=>1});

  JIS_KANA
    'jis' 输出的片假名形式：'GR'(0xA1..0xDF)、'I'(ESC ( I，需 OUTPUT_SHIFTING)、'SO'(SO/GL/SI)。默认：'GR'。
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_KANA'=>'SO','OUTPUT_SHIFTING'=>1});

  JIS_DBCS
    'jis' 输出的 DBCS 转义：'B'(ESC $ B)、'@'(ESC $ @)、'&@B'、'(B'、'(@'。默认：'B'；输出为 'jis' 时有效。
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_DBCS'=>'@'});

  JIS_SBCS
    'jis' 输出的 SBCS 转义：'B'(ESC ( B ASCII)、'J'(ESC ( J 罗马字)、'H'(ESC ( H 旧式)。默认：'B'；输出为 'jis' 时有效。
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_SBCS'=>'J'});

  JIS2004_PLANE1
    'jis2004' 输出的第 1 面转义：'Q'(ESC $ ( Q，:2004)、'O'(ESC $ ( O，:2000)。默认：'Q'；输出为 'jis2004' 时有效。
    e.g. Jacode4e::convert(\$line,'jis2004','utf8',{'JIS2004_PLANE1'=>'O'});

  ROUND_TRIP
    为真：可逆转换；无本地编码的字符会分配到用户自定义（外字）区，使「A→B」与「B→A」还原原始数据。往返两个方向都须指定 ROUND_TRIP=>1 且使用相同版本的 Jacode4e。默认：假（无法映射者变为 GETA）。表在首次使用时惰性构建。
    e.g. Jacode4e::convert(\$line,'cp00930','utf8',{'ROUND_TRIP'=>1});

[移位码速查]

  encoding  shift-out (DBCS start)  shift-in (DBCS end)
  --------  ---------------------   -------------------
  cp00930   0x0E                    0x0F
  keis78    0x0A 0x42               0x0A 0x41
  keis83    0x0A 0x42               0x0A 0x41
  keis90    0x0A 0x42               0x0A 0x41
  jef       0x28                    0x29
  jef9p     0x38                    0x29
  jipsj     0x1A 0x70               0x1A 0x71
  jipse     0x3F 0x75               0x3F 0x76
  letsj     0x93 0x70               0x93 0xF1

[编程示例]

  # 1) UTF-8 转主机编码（含移位、空格、geta）
  use FindBin;
  use lib "$FindBin::Bin/lib";
  use Jacode4e;
  while (<>) {
      $char_count = Jacode4e::convert(\$_, 'cp00930', 'utf8', {
          'OUTPUT_SHIFTING' => 1,
          'SPACE'           => "\x40\x40",
          'GETA'            => "\x44\x4B",
      });
      print $_;
  }

  # 2) 旧的 1978 年版 Shift_JIS 转 UTF-8（指定年代）
  Jacode4e::convert(\$line, 'utf8', 'sjis1978');

  # 3) 往返：UTF-8 -> CP00930 -> UTF-8 还原原始数据
  Jacode4e::convert(\$line, 'cp00930', 'utf8', { 'ROUND_TRIP' => 1 });
  Jacode4e::convert(\$line, 'utf8', 'cp00930', { 'ROUND_TRIP' => 1 });

======================================================================
