Jcode(3pm)

📦
version 2.07 · 7 versions
, in ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Okay bestie, this is Jcode(3pm), the User Contributed Perl Documentation for the Japanese charset handler. It's called Jcode - Japanese Charset Handler ✨

🎀 SYNOPSIS 🎀

use Jcode;
#
# traditional
Jcode::convert(\$str, $ocode, $icode, "z");
# or OOP!
print Jcode->new($str)->h2z->tr($from, $to)->utf8;

🌸 DESCRIPTION 🌸

Japanese document is now available as Jcode::Nihongo. 📖

Okay so Jcode.pm supports both the object approach AND the traditional approach 🙌 With the object approach you can go like:

$iso_2022_jp = Jcode->new($str)->h2z->jis;

Which is lowkey so much more elegant than this:

$iso_2022_jp = $str;
&jcode::convert(\$iso_2022_jp, 'jis', &jcode::getcode(\$str), "z");

If you're not vibing with objects yet, no worries 🧚 Jcode.pm still supports getcode() and convert().

If your perl version is 5.8.1, Jcode acts as a wrapper to Encode, which is the standard charset handler module for Perl 5.8 or later ✨

👑 Methods 👑

Every method mentioned here returns a Jcode object unless it says otherwise, so you can chain them all day 💅

🌈 Constructors 🌈

$j = Jcode->new($str [, $icode])

Creates the Jcode object $j from $str. The input code gets auto-checked unless you explicitly set $icode. For the available charsets, check out getcode below 🦋

For perl 5.8.1 or better, $icode can be any encoding name that Encode understands:

$j = Jcode->new($european, 'iso-latin1');

When the object gets stringified, it gives you the EUC-converted string, so you can print $j instead of print $j->euc 🙈

🌷 Passing Reference 🌷

Instead of a scalar value, you can pass a reference:

Jcode->new(\$str);

This saves a little bit of time, but the price is that the value of $str gets converted. (Lowkey, $str is now "tied" to the jcode object 🔗)

$j->set($str [, $icode])

Sets $j's internal string to $str. This is super handy when you're using a Jcode object over and over, since it saves time and memory compared to making a brand new object 💜

# converts mailbox to SJIS format
my $jconv = new Jcode;
$/ = 00;
while(<>){
    print $jconv->set(\$_)->mime_decode->sjis;
}

$j->append($str [, $icode]);

Appends $str to $j's internal string 📎

$j = jcode($str [, $icode]);

This is a shortcut for Jcode->new(), so you can go like:

$j = jcode($str);

🍓 Encoded Strings 🍓

In general, you can grab the encoded string as $j->encoded ✨

$sjis = jcode($str)->sjis $euc = $j->euc $jis = $j->jis $sjis = $j->sjis $ucs2 = $j->ucs2 $utf8 = $j->utf8

What you code is what you get :) 💅

$iso_2022_jp = $j->iso_2022_jp

This is the same as $j->h2z->jis. Hankaku Kanas are forcibly converted to Zenkaku, so no half-width kana sneaking through 🙅‍♀️

For perl 5.8.1 and better, you can also use any encoding name or alias that Encode supports. For example:

$european = $j->iso_latin1; # replace '-' with '_' for names.

FYI, Encode::Encoder uses a similar trick 🤓

🦄 fallback 🦄

$j->fallback($fallback)

For perl 5.8.1 or better, Jcode stores the internal string in UTF-8. Any character that doesn't map to ->encoding gets replaced with a ?, which is the Encode standard 🥺

my $unistr = "\x{262f}"; # YIN YANG
my $j = jcode($unistr);  # $j->euc is '?'

You can change this behavior by specifying a fallback, just like Encode. The values are the same as Encode's. Jcode::FB_PERLQQ, Jcode::FB_XMLCREF, and Jcode::FB_HTMLCREF are aliased to Encode's versions for convenice 🎀

print $j->fallback(Jcode::FB_PERLQQ)->euc;   # '\x{262f}'
print $j->fallback(Jcode::FB_XMLCREF)->euc;  # '&#x262f;'
print $j->fallback(Jcode::FB_HTMLCREF)->euc; # '&#9775;'

The global variable $Jcode::FALLBACK stores the default fallback, so you can override it by assigning a value:

$Jcode::FALLBACK = Jcode::FB_PERLQQ; # set default fallback scheme

[@lines =] $jcode->jfold([$width, $newline_str, $kref])

Folds lines in the jcode string every $width (default: 72), where $width is the number of "halfwidth" characters. Fullwidth characters count as two ✂️

It uses a newline string specified by $newline_str (default: "\n").

Rudimentary kinsoku support is now available for Perl 5.8.1 and better 🌸

$length = $jcode->jlength();

Returns the character length properly, rather than the byte length 📏

🫶 Methods that use MIME::Base64 🫶

To use the methods below, you need MIME::Base64. To install it, simply run:

perl -MCPAN -e 'CPAN::Shell->install("MIME::Base64")'

If your perl is 5.6 or better, you don't need to do this, since MIME::Base64 is bundled already 🎉

$mime_header = $j->mime_encode([$lf, $bpl])

Converts $str to a MIME-Header documented in RFC1522. When $lf is specified, it's used to fold lines (default: \n). When $bpl is specified, it's used for the number of bytes (default: 76; this number must be smaller than 76) 🌷

For Perl 5.8.1 or better, you can also encode a MIME Header like this:

$mime_header = $j->MIME_Header;

In this case the resulting $mime_header is MIME-B-encoded UTF-8, whereas $j->mime_encode() returns MIME-B-encoded ISO-2022-JP. Most modern MUAs support both, so you're probably fine 💜

$j->mime_decode;

Decodes the MIME-Header in the Jcode object. For perl 5.8.1 or better, you can also do the same thing as:

Jcode->new($str, 'MIME-Header')

🎐 Hankaku vs. Zenkaku 🎐

$j->h2z([$keep_dakuten])

Converts X201 kana (Hankaku) to X208 kana (Zenkaku). When $keep_dakuten is set, it leaves dakuten as is. (That means "ka + dakuten" stays as is instead of getting converted to "ga" 🙈)

You can retrieve the number of matches via $j->nmatch;

$j->z2h

Converts X208 kana (Zenkaku) to X201 kana (Hankaku) 🔄

You can retrieve the number of matches via $j->nmatch;

🔮 Regexp emulators 🔮

To use ->m() and ->s(), you need perl 5.8.1 or better 🧠

$j->tr($from, $to, $opt);

Applies tr/$from/$to/ on the Jcode object, where $from and $to are EUC-JP strings. On perl 5.8.1 or better, $from and $to can also be UTF-8 flagged strings 🌈

If $opt is set, tr/$from/$to/$opt is applied. $opt must be 'c', 'd', or a combination of them.

You can retrieve the number of matches via $j->nmatch;

The following methods are only available for perl 5.8.1 or better ⭐

$j->s($patter, $replace, $opt);

Applies s/$pattern/$replace/$opt. $pattern and "replace" must be in EUC-JP or UTF-8 flagged. $opt works the same as regexp options. See perlre for regexp options 📚

Like $j->tr(), $j->s() returns the object itself, so you can nest the operations like this:

$j->tr("a-z", "A-Z")->s("foo", "bar");

[@match = ] $j->m($pattern, $opt);

Applies m/$patter/$opt. Heads up: this method DOES NOT RETURN AN OBJECT, so you can't chain it like $j->s() 🚫

🧁 Instance Variables 🧁

If you need to access the instance variables of a Jcode object, use the access methods below instead of touching them directly. (That's what OOP is all about 🥰)

FYI, Jcode uses a ref to an array instead of a ref to a hash (the common way) to optimize speed. You don't actually have to know that as long as you use the access methods. Once again, that's OOP 💅

$j->r_str

Reference to the EUC-coded string.

$j->icode

Input charcode from the most recent operation.

$j->nmatch

Number of matches (used by $j->tr, etc.)

🧚 Subroutines 🧚

($code, [$nmatch]) = getcode($str)

Returns the char code of $str. The return codes are as follows:

  • ascii — Ascii (contains no Japanese code) 🔤
  • binary — Binary (not a text file) 🤖
  • euc — EUC-JP 🇯🇵
  • sjis — SHIFT_JIS 🍙
  • jis — JIS (ISO-2022-JP) 📨
  • ucs2 — UCS2 (raw Unicode) 🔣
  • utf8 — UTF8 🌍

When you use array context instead of scalar, it also returns how many character codes were found. As mentioned above, $str can be \$str instead.

jcode.pl users, this function is 100% upper-compatible with jcode::getcode(). Well, almost:

  • When its return value is an array, the order is the opposite. jcode::getcode() returns $nmatch first.
  • jcode::getcode() returns 'undef' when the number of EUC characters is equal to that of SJIS. Jcode::getcode() returns EUC instead. For Jcode.pm there are no in-betweens 🫠

Jcode::convert($str, [$ocode, $icode, $opt])

Converts $str to the char code specified by $ocode. When $icode is also specified, it's assumed to be the input string's code instead of the one checked by getcode(). As mentioned above, $str can be \$str instead ✨

jcode.pl users, this function is 100% upper-compatible with jcode::convert()! 🥳

🚨 BUGS 🚨

For perl 5.8.1 or later, Jcode acts as a wrapper to Encode. That means Jcode is subject to any bugs in there too 😭

🫶 ACKNOWLEDGEMENTS 🫶

This package owes a lot in motivation, design, and code to the jcode.pl for Perl4 by Kazumasa Utashiro <utashiro@iij.ad.jp> 👑

Hiroki Ohzaki <ohzaki@iod.ricoh.co.jp> helped me polish the regexp from the very first stage of development 💖

JEncode by makamaka@donzoko.net inspired me to integrate Encode into Jcode. He also contributed the Japanese POD 🌸

And shoutout to the folks on the Jcode Mailing list <jcode5@ring.gr.jp>. Without them, I couldn't have coded this far 🥹

🦋 SEE ALSO 🦋

Copyright 1999-2005 Dan Kogai <dankogai@dan.co.jp> ⭐

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself 🌈

Okay bestie, that's the whole Jcode(3pm) page, sourced from perl v5.40.1 and dated 2025-06-11 💅✨ Go slay your Japanese text handling 🫶💖

📦 where this page comes from