=encoding euc-jp

=head1 NAME

HTML::Entities::ImodePictogram - i-mode用絵文字のエンコード/デコード

=head1 SYNOPSIS

  use HTML::Entities::ImodePictogram;

  $html      = encode_pictogram($rawtext);
  $rawtext   = decode_pictogram($html);
  $cleantext = remove_pictogram($rawtext);

  use HTML::Entities::ImodePictogram qw(find_pictogram);

  $num_found = find_pictogram($rawtext, \&callback);

=head1 DESCRIPTION

HTML::Entities::ImodePictogram は、 Shift_JIS プライベート領域に割り当てられた、i-mode用絵文字を処理するモジュールです。

i-mode用絵文字についての詳細は、http://www.nttdocomo.co.jp/i/tag/emoji/index.html をご覧ください。

=head1 FUNCTIONS

このモジュールのすべての関数では、入出力の文字列は Shift_JIS でエンコードされていると想定しています。Shift_JIS と EUC-JP や UTF8 など他のエンコーディングとのコード変換については、L<Jcode> をご覧ください。

このモジュールは以下の関数をデフォルトでエクスポートします。

=over 4

=item encode_pictogram

  $html = encode_pictogram($rawtext);
  $html = encode_pictogram($rawtext, unicode => 1);

テキストに含まれる i-mode用絵文字をHTML参照にエンコードします。$rawtext が拡張絵文字を含む場合、Unicode コードポイント (C<&#xFFFF;>) でエンコードします。C<unicode> オプションを明示的に与えた場合、すべての絵文字を Unicode コードポイントでエンコードします。それ以外の場合は、SJIS10進数 (C<&#NNNNN;>) でエンコードします。

=item decode_pictogram

  $rawtext = decode_pictogram($html);

i-mode用絵文字のHTML参照(C<&#xFFFF;> と C<&#NNNNN;> の両方)を、実体に Shift_JIS でデコードします。

=item remove_pictogram

  $cleantext = remove_pictogram($rawtext);

テキストに含まれる i-mode用絵文字を削除します。

=back

このモジュールは以下の関数を必要ならばエクスポートします。

=over 4

=item find_pictogram

  $num_found = find_pictorgram($rawtext, \&callback);

テキスト中の i-mode用絵文字を探して、見つかったらそれぞれに対してコールバック関数を実行します。見つかった絵文字の数を返します。

コールバック関数には3つの引数が渡ります。1つめは見つかった絵文字のバイナリそのもの、2つめはその絵文字のShift_JISコードポイントを示す10進数の数字, 3つめは Unicode コードポイントです。コールバック関数の返り値によって、もとのテキストは置換されます。

encode_pictogram() の簡単なあ実装を紹介します。find_pictorgram() の使い方のよい例になるでしょう。この例では、拡張絵文字はサポートされていないことに注意してください。

  sub encode_pictogram {
      my $text = shift;
      find_pictogram($text, sub {
			 my($bin, $number, $cp) = @_;
			 return '&#' . $number . ';';
		     });
      return $text;
  }

=back

=head1 CAVEAT

=over 4

=item *

テキスト中のC<すべて>の文字にマッチする正規表現を利用しているため、このモジュールの動作は遅いです。これは、Shift_JIS の文字境界を見つけるには、すべてマッチさせるしかないのが原因です。

=item *

拡張絵文字のサポートは完全とは言えません。絵文字を Unicode で扱いたい場合は、perl 5.8.0 以上に付属の Encode モジュールや、Unicode::Japanese を見てください。

=back

=head1 AUTHOR

Tatsuhiko Miyagawa <miyagawa@bulknews.net>

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

=head1 SEE ALSO

L<HTML::Entities>, L<Unicode::Japanese>, http://www.nttdocomo.co.jp/p_s/imode/tag/emoji/

=cut