NAME
    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
    Jcode.pm supports both object and traditional approach. With object
    approach, you can go like;

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

    Which is more elegant than;

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

    For those unfamiliar with objects, Jcode.pm still supports getcode() and
    convert().

Methods
    Methods mentioned here all return Jcode object unless otherwise
    mentioned.

    $j = Jcode->new($str [, $icode]);
        Creates Jcode object $j from $str. Input code is automatically
        checked unless you explicitly set $icode. For available charset, see
        getcode() below.

        The object keeps the string in EUC format enternaly. When the object
        itself is evaluated, it returns the EUC-converted string so you can
        "print $j;" without calling access method if you are using EUC
        (thanks to function overload).

    Passing Reference
        Instead of scalar value, You can use reference as

        Jcode->new(\$str);

        This saves time a little bit. In exchange of the value of $str being
        converted. (In a way, $str is now "tied" to jcode object).

    $j->set($str [, $icode]);
        Sets $j's internal string to $str. Handy when you use Jcode object
        repeatedly (saves time and memory to create object).

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

    $j->append($str [, $icode]);
        Appends $str to $j's internal string.

    $j = jcode($str [, $icode]);
        shortcut for Jcode->new() so you can go like;

        $sjis = jcode($str)->sjis;

    $euc = $j->euc;
    $jis = $j->jis;
    $sjis = $j->sjis;
        What you code is what you get :)

    $iso_2022_jp = $j->iso_2022_jp
        Same as $j->z2h->jis. Hankaku Kanas are forcibly converted to
        Zenkaku.

    [@lines =] $jcode->jfold([$bytes_per_line, $newline_str]);
        folds lines in jcode string every $bytes_per_line (default: 72) in a
        way that does not clobber the multibyte string. (Sorry, no Kinsoku
        done!) with a newline string spified by $newline_str (default: \n).

  Methods that use MIME::Base64
    To use methods below, you need MIME::Base64. To install, simply

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

    $mime_header = $j->mime_encode([$lf, $bpl]);
        Converts $str to MIME-Header documented in RFC1522. When $lf is
        specified, it uses $lf to fold line (default: \n); When $bpl is
        specified, it uses $bpl for the number of bytes (default: 76);

    $j->mime_decode;
        Decodes MIME-Header in Jcode object.

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

  Methods implemented by Jcode::H2Z
    Methods below are actually implemented in Jcode::H2Z.

    $j->h2z([$keep_dakuten]);
        Converts X201 kana (Hankaku) to X208 kana (Zenkaku). When
        $keep_dakuten is set, it leaves dakuten as is (That is, "ka +
        dakuten" is left as is instead of being converted to "ga")

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

    $j->z2h;
        Converts X208 kana (Zenkaku) to X201 kana (Hankazu).

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

  Methods implemented in Jcode::Tr
    Methods here are actually implemented in Jcode::Tr.

    $j->tr($from, $to);
        Applies tr on Jcode object. $from and $to can contain EUC Japanese.

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

  Methods implemented in Jcode::Unicode
    If your perl does not support XS (or you can't "perl Makefile.PL",
    Jcode::Unicode::NoXS will be used.

    See Jcode::Unicode and Jcode::Unicode::NoXS for details

    $ucs2 = $j->ucs2;
        Returns UCS2 (Raw Unicode) string.

    $ucs2 = $j->utf8;
        Returns utf8 String.

  Instance Variables
    If you need to access instance variables of Jcode object, use access
    methods below instead of directly accessing them (That's what OOP is all
    about)

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

    $j->r_str
        Reference to the EUC-coded String.

    $j->icode
        Input charcode in recent operation.

    $j->nmatch
        Number of matches (Used in $j->tr, etc.)

Subroutines
    ($code, [$nmatch]) = getcode($str);
        Returns char code of $str. Return codes are as follows

         ascii   Ascii (Contains no Japanese Code)
         binary  Binary (Not Text File)
         euc     EUC-JP
         sjis    SHIFT_JIS
         jis     JIS (ISO-2022-JP)
         ucs2    UCS2 (Raw Unicode)
         utf8    UTF8

        When array context is used instead of scaler, it also returns how
        many character codes are found. As mentioned above, $str can be
        \$str instead.

    jcode.pl Users:
        This function is 100% upper-conpatible 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.  for
           Jcode.pm is no in-betweens.

    Jcode::convert($str, [$ocode, $icode, $opt]);
        Converts $str to char code specified by $ocode. When $icode is
        specified also, it assumes $icode for input string instead of the
        one checked by getcode(). As mentioned above, $str can be \$str
        instead.

    jcode.pl Users:
        This function is 100% upper-conpatible with jcode::convert() !

BUGS
    Unicode support by Jcode is far from efficient!

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> has helped me polish regexp from
    the very first stage of development.

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

SEE ALSO
    Jcode::Unicode
    Jcode::Unicode::NoXS

COPYRIGHT
    Copyright 1999 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.

