=encoding UTF-8

=head1 NAME

Lingua::JA::Moji - Handle many kinds of Japanese characters

=head1 SYNOPSIS

Convert various types of Japanese characters into one another.

    use Lingua::JA::Moji qw/kana2romaji romaji2kana/;
    use utf8;
    my $romaji = kana2romaji ('あいうえお');
    # $romaji is now 'aiueo'.
    my $kana = romaji2kana ($romaji);
    # $kana is now 'アイウエオ'.

=head1 DESCRIPTION

This module provides methods to convert different written forms of
Japanese into one another.

All the functions in this module assume the use of Unicode
encoding. All input and output strings must be encoded using UTF-8.





=head1 ROMANIZATION


These functions convert Japanese letters to and from romanized forms.







=head2 kana2romaji -- Convert kana to romaji

    use Lingua::JA::Moji 'kana2romaji';

    $romaji = kana2romaji ("うれしいこども");
    # Now $romaji = 'uresîkodomo'




Convert kana to a romanized form.

An optional second argument, a hash reference, controls the style of
conversion.

    use utf8;
    $romaji = kana2romaji ("しんぶん", {style => "hepburn"});
    # $romaji = "shimbun"

The possible options are

=over

=item style

The style of romanization. The default form of romanization is
"Nippon-shiki". See
L<http://www.sljfaq.org/afaq/nippon-shiki.html>. The user can set the
conversion style to "hepburn" or "passport" or "kunrei". See
L<http://www.sljfaq.org/afaq/kana-roman.html>.

=item use_m

If this is set to any "true" value, syllabic I<n>s (ん) which come
before "b" or "p" sounds, such as the first "n" in "shinbun" (しんぶん,
newspaper) will be converted into "m" rather than "n".

=item ve_type

C<ve_type> controls how long vowels are written. The default is to use
circumflexes to represent long vowels. If you set "ve_type" =>
"macron", then it uses macrons (the Hepburn system). If you set
C<< "ve_type" => "passport" >>, then it uses "oh" to write long "o"
vowels. If you set C<< "ve_type" => "none" >>, then it does not use "h".

=back









=head2 romaji2kana -- Convert romaji to kana

    use Lingua::JA::Moji 'romaji2kana';

    $kana = romaji2kana ('yamaguti');
    # Now $kana = 'ヤマグチ'





Convert romanized Japanese to kana. The romanization is highly liberal
and will attempt to convert any romanization it sees into kana.  To
convert romanized Japanese into hiragana, use L</romaji2hiragana>.

The second argument to the function contains options in the
form of a hash reference,

     $kana = romaji2kana ($romaji, {wapuro => 1});

Use an option C<< wapuro => 1 >> to convert long vowels into the
equivalent kana rather than I<chouon>.









=head2 romaji2hiragana -- Convert romaji to hiragana

    use Lingua::JA::Moji 'romaji2hiragana';

    $hiragana = romaji2hiragana ('babubo');
    # Now $hiragana = 'ばぶぼ'




Convert romanized Japanese into hiragana. This takes the same options
as L</romaji2kana>. It also switches on the "wapuro" option which makes
the use of long vowels with a kana rather than a chouon (long vowel
marker).









=head2 romaji_styles 

    use Lingua::JA::Moji 'romaji_styles';

    my @styles = romaji_styles ();
    # Returns a true value
    romaji_styles ("hepburn");
    # Returns the undefined value
    romaji_styles ("frogs");




Given an argument, return whether it is a legitimate style of romanization.

Without an argument, return a list of possible styles, as an array of
hash references, with each hash reference containing the short name
under the key "abbrev" and the full name under the key "full_name".









=head2 is_voiced 

    use Lingua::JA::Moji 'is_voiced';

    if (is_voiced ('が')) {
         print "が is voiced.\n";
    }




Given a kana or romaji input, C<is_voiced> returns a true value if the
sound is a voiced sound like I<a>, I<za>, I<ga>, etc. and the
undefined value if not.









=head2 is_romaji 

    use Lingua::JA::Moji 'is_romaji';

    # The following line returns "undef"
    is_romaji ("abcdefg");
    # The following line returns a defined value
    is_romaji ("atarimae");




Detect whether a string of alphabetical characters, which may also
include characters with macrons or circumflexes, "looks like"
romanized Japanese. If the test is successful, returns the romaji in a
canonical form.

This functions by converting the string to kana and seeing if it
converts cleanly or not.









=head2 normalize_romaji 

    use Lingua::JA::Moji 'normalize_romaji';

    $normalized = normalize_romaji ('tsumuji');




C<normalize_romaji> converts romanized Japanese to a canonical form,
which is based on the Nippon-shiki romanization, but without
representing long vowels using a circumflex. In the canonical form,
sokuon (っ) characters are converted into the string "xtu".

If there is kana in the input string, this will also be converted to
romaji.

C<normalize_romaji> is for comparing two Japanese words which may be
represented in different ways, for example in different romanization
systems, to see if they refer to the same word despite the difference
in writing. It does not provide a standardized or
officially-sanctioned form of romanization.











=head1 KANA





=head2 hira2kata -- Convert hiragana to katakana

    use Lingua::JA::Moji 'hira2kata';

    $katakana = hira2kata ('ひらがな');
    # Now $katakana = 'ヒラガナ'




C<hira2kata> converts hiragana into katakana. If the input is a list,
it converts each element of the list, and if required, returns a list
of the converted inputs, otherwise it returns a concatenation of the
strings.

    my @katakana = hira2kata (@hiragana);

This does not convert chouon signs.









=head2 kata2hira -- Convert katakana to hiragana

    use Lingua::JA::Moji 'kata2hira';

    $hiragana = kata2hira ('カキクケコ');
    # Now $hiragana = 'かきくけこ'




C<kata2hira> converts full-width katakana into hiragana. If the input
is a list, it converts each element of the list, and if required,
returns a list of the converted inputs, otherwise it returns a
concatenation of the strings.

    my @hiragana = hira2kata (@katakana);

This function does not convert chouon signs into long vowels. It also
does not convert half-width katakana into hiragana.









=head2 InHankakuKatakana 

    use Lingua::JA::Moji 'InHankakuKatakana';

    use utf8;
    if ('ｱ' =~ /\p{InHankakuKatakana}/) {
        print "ｱ is half-width katakana\n";
    }




C<InHankakuKatakana> is a character class for use in regular
expressions with C<\p> which can validate halfwidth katakana.









=head2 kana2hw -- Convert kana to halfwidth katakana

    use Lingua::JA::Moji 'kana2hw';

    $half_width = kana2hw ('あいウカキぎょう。');
    # Now $half_width = 'ｱｲｳｶｷｷﾞｮｳ｡'




C<kana2hw> converts hiragana, katakana, and fullwidth Japanese
punctuation to halfwidth katakana and halfwidth punctuation. Its
function is similar to the Emacs command C<japanese-hankaku-region>.
For the opposite function, see L<hw2katakana>. See also
L</katakana2hw> for a function which only converts katakana.









=head2 hw2katakana -- Convert halfwidth katakana to katakana

    use Lingua::JA::Moji 'hw2katakana';

    $full_width = hw2katakana ('ｱｲｳｶｷｷﾞｮｳ｡');
    # Now $full_width = 'アイウカキギョウ。'




C<hw2katakana> converts halfwidth katakana and Japanese punctuation to
fullwidth katakana and punctuation. Its function is similar to the
Emacs command C<japanese-zenkaku-region>. For the opposite function,
see L<kana2hw>.









=head2 is_kana 

    use Lingua::JA::Moji 'is_kana';

    




This function returns a true value if its argument is a string of
kana, or an undefined value if not. The input cannot contain
punctuation or the long vowel symbol (chouonpu).









=head2 is_hiragana 

    use Lingua::JA::Moji 'is_hiragana';

    




This function returns a true value if its argument is a string of
hiragana, and an undefined value if not. The entire string from
beginning to end must all be kana for this to return true. The kana
cannot include punctuation marks or the long vowel symbol (chouonpu,
「ー」).









=head2 kana2katakana -- Convert kana to katakana

    use Lingua::JA::Moji 'kana2katakana';

    




Convert any of katakana, halfwidth katakana, circled katakana and
hiragana to full width katakana.









=head2 kana_to_large 

    use Lingua::JA::Moji 'kana_to_large';

    $large = kana_to_large ('ぁあぃい');
    # Now $large = 'ああいい'




Convert small-sized kana such as 「ぁ」 into full-sized kana such as
「あ」.









=head2 kana_order 

    use Lingua::JA::Moji 'kana_order';

    $kana_order = kana_order ();




Returns an array reference containing an ordering of the kana. This is
useful for looping over the kana or sorting.









=head2 katakana2hw -- Convert katakana to halfwidth katakana

    use Lingua::JA::Moji 'katakana2hw';

    $hw = katakana2hw ("あいうえおアイウエオ");
    # Now $hw = 'あいうえおｱｲｳｴｵ'




Convert katakana to halfwidth katakana, leaving hiragana
unchanged. See also L</kana2hw>.









=head2 InKana 

    use Lingua::JA::Moji 'InKana';

    $is_kana = ('あいうえお' =~ /^\p{InKana}+$/);
    # Now $is_kana = '1'




A character class for use in regular expressions which matches kana
characters.











=head1 WIDE ASCII


Functions for handling the "wide ascii" which is sometimes used in
Japan. The "wide ascii" is a legacy of bitmapped fonts which has
survived into the present day. "Wide ascii" characters were special
bitmapped font characters created to be the same size as one kanji or
kana character.







=head2 InWideAscii 

    use Lingua::JA::Moji 'InWideAscii';

    use utf8;
    if ('Ａ' =~ /\p{InWideAscii}/) {
        print "Ａ is wide ascii\n";
    }




This is a character class for use with \p which matches a "wide ascii"
(全角英数字).









=head2 wide2ascii -- Convert wide ASCII characters to printable ASCII characters

    use Lingua::JA::Moji 'wide2ascii';

    $ascii = wide2ascii ('ａｂＣＥ０１９');
    # Now $ascii = 'abCE019'




Convert the "wide ASCII" used in Japan (fullwidth ASCII, 全角英数字)
into usual ASCII symbols (半角英数字).









=head2 ascii2wide -- Convert printable ASCII characters to wide ASCII characters

    use Lingua::JA::Moji 'ascii2wide';

    $wide = ascii2wide ('abCE019');
    # Now $wide = 'ａｂＣＥ０１９'




Convert usual ASCII symbols (半角英数字) into the "wide ASCII" used in
Japan (fullwidth ASCII, 全角英数字).












=head1 OTHER TYPES OF LETTERING





=head2 kana2morse -- Convert kana to Japanese morse code (wabun code)

    use Lingua::JA::Moji 'kana2morse';

    $morse = kana2morse ('しょっちゅう');
    # Now $morse = '--.-. -- .--. ..-. -..-- ..-'




Convert Japanese kana into Morse code. Note that Japanese morse code
does not have any way of representing small kana characters, so
converting to and then from morse code will result in しょっちゅう
becoming シヨツチユウ.









=head2 morse2kana -- Convert Japanese morse code (wabun code) to kana

    use Lingua::JA::Moji 'morse2kana';

    $kana = morse2kana ('--.-. -- .--. ..-. -..-- ..-');
    # Now $kana = 'シヨツチユウ'




Convert Japanese Morse code into kana. Each Morse code element must be separated by whitespace from the next one. 






=head3 Bugs

This has not been extensively tested.







=head2 kana2braille -- Convert kana to Japanese braille

    use Lingua::JA::Moji 'kana2braille';

    




Converts kana into the equivalent Japanese braille (I<tenji>) forms.






=head3 Bugs

This has not been extensively tested. This is not an adequate Japanese
braille convertor. Creating Japanese braille requires breaking
Japanese sentences up into individual words, but this does not attempt
to do that. People who are interested in building a Perl braille
convertor could start here.







=head2 braille2kana -- Convert Japanese braille to kana

    use Lingua::JA::Moji 'braille2kana';

    




Converts Japanese braille (I<tenji>) into the equivalent katakana.









=head2 kana2circled -- Convert kana to circled katakana

    use Lingua::JA::Moji 'kana2circled';

    $circled = kana2circled ('あいうえお');
    # Now $circled = '㋐㋑㋒㋓㋔'




This function converts kana into the "circled katakana" of Unicode,
which have code points from 32D0 to 32FE. See also L</circled2kana>.

Note that there is no circled form of the ン kana, so this is left
untouched.









=head2 circled2kana -- Convert circled katakana to kana

    use Lingua::JA::Moji 'circled2kana';

    $kana = circled2kana ('㋐㋑㋒㋓㋔');
    # Now $kana = 'アイウエオ'




This function converts the "circled katakana" of Unicode into
full-width katakana. See also L</kana2circled>.











=head1 KANJI





=head2 new2old_kanji -- Convert Modern kanji to Pre-1949 kanji

    use Lingua::JA::Moji 'new2old_kanji';

    $old = new2old_kanji ('三国 連太郎');
    # Now $old = '三國 連太郎'




Convert new-style (post-1949) kanji (Chinese characters) into old-style (pre-1949) kanji.






=head3 Bugs

The list of characters in this convertor may not contain every pair of
old/new kanji.

It will not correctly convert 弁 since this has three different
equivalents in the old system.







=head2 old2new_kanji -- Convert Pre-1949 kanji to Modern kanji

    use Lingua::JA::Moji 'old2new_kanji';

    $new = old2new_kanji ('櫻井');
    # Now $new = '桜井'




Convert old-style (pre-1949) kanji (Chinese characters) into new-style
(post-1949) kanji.









=head2 circled2kanji 

    use Lingua::JA::Moji 'circled2kanji';

    $kanji = circled2kanji ('㊯');
    # Now $kanji = '協'




Convert the circled forms of kanji into their uncircled equivalents.









=head2 kanji2circled 

    use Lingua::JA::Moji 'kanji2circled';

    $kanji = kanji2circled ('協嬉');
    # Now $kanji = '㊯嬉'




Convert the usual forms of kanji into circled equivalents, if they
exist. Note that only a limited number of kanji have circled forms.









=head2 bracketed2kanji 

    use Lingua::JA::Moji 'bracketed2kanji';

    $kanji = bracketed2kanji ('㈱');
    # Now $kanji = '株'




Convert bracketed form of kanji into unbracketed form.









=head2 kanji2bracketed 

    use Lingua::JA::Moji 'kanji2bracketed';

    $kanji = kanji2bracketed ('株');
    # Now $kanji = '㈱'




Convert unbracketed form of kanji into bracketed form, if it exists.











=head1 CYRILLIZATION


This is an experimental cyrillization of kana based on the information
in a Wikipedia article,
L<http://en.wikipedia.org/wiki/Cyrillization_of_Japanese>. The module
author does not know anything about cyrillization of kana, so any
assistance in correcting this is very welcome.







=head2 kana2cyrillic -- Convert kana to the Cyrillic (Russian) alphabet

    use Lingua::JA::Moji 'kana2cyrillic';

    $cyril = kana2cyrillic ('シンブン');
    # Now $cyril = 'симбун'







=head2 cyrillic2katakana -- Convert the Cyrillic (Russian) alphabet to katakana

    use Lingua::JA::Moji 'cyrillic2katakana';

    $kana = cyrillic2katakana ('симбун');
    # Now $kana = 'シンブン'









=head1 HANGUL (KOREAN LETTERS)





=head2 kana2hangul 

    use Lingua::JA::Moji 'kana2hangul';

    $hangul = kana2hangul ('すごわざ');
    # Now $hangul = '스고와자'




=head3 Bugs

=over

=item Doesn't deal with ん

=item May be incorrect

This is based on a list found on the internet at
L<http://kajiritate-no-hangul.com/kana.html>. There is currently no
proof of correctness.

=back





=head1 SUPPORT

=head2 Mailing list

There is a mailing list for this module and L<Convert::Moji> at
L<http://groups.google.com/group/perl-moji>. 

=head2 Other modules

=over

=item L<Lingua::KO::Munja>

This is similar to the present module for Korean.

=back

=head2 Books

Parts of this module are covered in the book "Perl CPAN Module Guide"
by Naoki Tomita (in Japanese), ISBN 978-4862671080, published by
WEB+DB PRESS plus, April 2011.

=head1 EXPORT

This module exports its functions only on request. To export all the
functions in the module,

    use Lingua::JA::Moji ':all';

=head1 AUTHOR

Ben Bullock, C<< <bkb@cpan.org> >>

=head1 COPYRIGHT & LICENSE

Copyright 2008-2012 Ben Bullock, all rights reserved.

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

=cut

=head1 ACKNOWLEDGEMENTS

Thanks to Naoki Tomita for various assitances (see
L<http://groups.google.com/group/perl-moji/browse_thread/thread/10a42c35f7c22ebc>).

