################################################################################
# Cheat Sheet ng Jacode4e (TL)
# Jacode4e - Converts Character Encodings for Enterprise in Japan
# https://metacpan.org/dist/Jacode4e
# Copyright (c) 2026 INABA Hitoshi <ina.cpan@gmail.com>
################################################################################

======================================================================
Mabilis na Sanggunian ng Jacode4e (Filipino/Tagalog)
======================================================================

[PANGUNAHING PAGGAMIT]

  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             : string na iko-convert (ipinapasa sa pamamagitan ng reference, ino-overwrite sa lugar)
  $OUTPUT_encoding  : pangalan ng output encoding
  $INPUT_encoding   : pangalan ng input encoding
  $char_count       : bilang ng karakter pagkatapos ng conversion

[LISTAHAN NG MGA PANGALAN NG ENCODING]

  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)

  Mga edisyon ayon sa taon ng sjis / euc / jis (ang walang taon ay edisyong 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

[PAGKAKAIBA NG MGA EDISYON NG JIS AYON SA TAON (para sa baguhan)]

  Ang mga kanji ng Hapon ay isinapamantayan nang paunti-unti. Ang parehong mga byte ay maaaring ibang karakter sa iba't ibang edisyon, kaya piliin ang edisyong tugma sa iyong data. Kung hindi alam, gamitin ang sjis / euc / jis na walang taon.

  1978 (JIS C 6226-1978) : ang unang pamantayan ng kanji (Antas 1 at Antas 2).
  1983 (JIS X 0208-1983) : ipinagpalit ang code ng 22 pares ng kanji at binago ang ilang hugis; pinakakaraniwang sanhi ng sirang lumang datos.
  1990 (JIS X 0208-1990) : nagdagdag lang ng 2 kanji (U+51DC, U+7199); ang sjis / euc / jis na walang taon ay ang edisyong ito.
  2000 (JIS X 0213:2000) : malaking pagpapalawak; nagdagdag ng Antas 3 at 4 na kanji at simbolo sa bagong plane 2.
  2004 (JIS X 0213:2004) : nagdagdag ng 10 kanji at binago ang halimbawang hugis ng 168 kanji (parehong code sa 2000, bagong hugis).

[MGA OPSYON]

  Ipasa ang mga opsyon bilang ika-4 na argumento: { 'KEY' => halaga, ... }

  INPUT_LAYOUT
    Nakapirming record layout sa 'S' (1-byte SBCS) at 'D' (2-byte DBCS); ang bawat titik ay maaaring sundan ng bilang ng ulit. Default: awtomatiko.
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'INPUT_LAYOUT'=>'S2D2SD'});

  OUTPUT_SHIFTING
    True: naglalabas ng shift-out/shift-in code sa paligid ng mga DBCS na bahagi. Default: false.
    e.g. Jacode4e::convert(\$line,'jef','cp932x',{'OUTPUT_SHIFTING'=>1});

  SPACE
    DBCS/MBCS space fill code (binary string). Default: ang space ng encoding.
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'SPACE'=>"\x81\xA1"});

  GETA
    DBCS/MBCS geta code para sa mga karakter na hindi ma-map.
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'GETA'=>"\x81\xA2"});

  OVERRIDE_MAPPING
    Hashref ng per-character na FROM => TO override (ino-override din ang SPACE).
    e.g. Jacode4e::convert(\$line,'cp932x','cp00930',{'OVERRIDE_MAPPING'=>{"\x44\x5A"=>"\x81\x7C"}});

  JIS_SOSI
    True: sa input na 'jis', ang SO (0x0E)/SI (0x0F) ay lumilipat sa JIS X 0201 Katakana (ugali ng JIS7). Default: false; input na 'jis'.
    e.g. Jacode4e::convert(\$line,'utf8','jis',{'JIS_SOSI'=>1});

  JIS_X0212
    True: sa output na 'jis', ang karakter na nasa JIS X 0212 ngunit wala sa JIS X 0208 ay isinusulat bilang ESC $ ( D. Kailangan ng OUTPUT_SHIFTING. Default: false.
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_X0212'=>1,'OUTPUT_SHIFTING'=>1});

  JIS_KANA
    Estilo ng Katakana sa output na 'jis': 'GR' (0xA1..0xDF), 'I' (ESC ( I, kailangan ng OUTPUT_SHIFTING), 'SO' (SO/GL/SI). Default: 'GR'.
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_KANA'=>'SO','OUTPUT_SHIFTING'=>1});

  JIS_DBCS
    DBCS escape sa output na 'jis': 'B' (ESC $ B), '@' (ESC $ @), '&@B', '(B', '(@'. Default: 'B'; output na 'jis'.
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_DBCS'=>'@'});

  JIS_SBCS
    SBCS escape sa output na 'jis': 'B' (ESC ( B ASCII), 'J' (ESC ( J Roman), 'H' (ESC ( H luma). Default: 'B'; output na 'jis'.
    e.g. Jacode4e::convert(\$line,'jis','utf8',{'JIS_SBCS'=>'J'});

  JIS2004_PLANE1
    Plane-1 escape sa output na 'jis2004': 'Q' (ESC $ ( Q, :2004), 'O' (ESC $ ( O, :2000). Default: 'Q'; output na 'jis2004'.
    e.g. Jacode4e::convert(\$line,'jis2004','utf8',{'JIS2004_PLANE1'=>'O'});

  ROUND_TRIP
    True: nababaligtad na conversion; ang karakter na walang katutubong code ay inilalagay sa user-defined (GAIJI) na lugar upang ang "A to B" at "B to A" ay maibalik ang orihinal. Kailangan ng magkabilang direksyon ang ROUND_TRIP=>1 at ang PAREHONG bersyon ng Jacode4e. Default: false (nagiging GETA ang hindi ma-map). Ginagawa ang table nang lazy sa unang paggamit.
    e.g. Jacode4e::convert(\$line,'cp00930','utf8',{'ROUND_TRIP'=>1});

[SANGGUNIAN NG SHIFT CODE]

  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

[MGA HALIMBAWANG PROGRAMA]

  # 1) UTF-8 patungong mainframe encoding (may shift, space, 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) lumang 1978 Shift_JIS patungong UTF-8 (batay sa taon)
  Jacode4e::convert(\$line, 'utf8', 'sjis1978');

  # 3) round-trip: UTF-8 -> CP00930 -> UTF-8 ibinabalik ang orihinal
  Jacode4e::convert(\$line, 'cp00930', 'utf8', { 'ROUND_TRIP' => 1 });
  Jacode4e::convert(\$line, 'utf8', 'cp00930', { 'ROUND_TRIP' => 1 });

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