Date/Japanese/Era.pod

=head1 NAME

Date::Japanese::Era - 和暦と西暦の相互変換

=head1 SYNOPSIS

  use Date::Japanese::Era;

  # グレゴリア暦から (月と日が必須)
  $era = Date::Japanese::Era->new(1970, 1, 1);

  # 和暦から
  $era = Date::Japanese::Era->new('昭和', 52);

  $name      = $era->name;         # '昭和' in EUC-jp (default)
  $gengou    = $era->gengou;       # 同上

  $year      = $era->year;         # 52
  $gregorian = $era->gregorian_year;       # 1977

  # JIS X0301 テーブルを変換に使用する
  use Date::Japanese::Era 'JIS_X0301';

=head1 DESCRIPTION

Date::Japanese::Era は和暦と西暦(グレゴリア暦)の相互変換を行うモジュー
ルです。

=head1 METHODS

=over 4

=item codeset

  $codeset = Date::Japanese::Era->codeset;
  Date::Japanese::Era->codeset($encoding);

和暦の文字エンコーディングを設定/取得します。例えば以下のコードでは、
和暦の入出力は UTF-8 エンコードされます。

  Date::Japanese::Era->codeset('utf8');
  $era = Date::Japanese::Era->new($name, $year); # $name は UTF-8
  print $era->name;                              # これも UTF-8

この機能を利用するには Jcode モジュールが必要です。ない場合には 
codeset() の呼び出しは、warning が出力され、無視されます。

=item new

  $era = Date::Japanese::Era->new($year, $month, $day);
  $era = Date::Japanese::Era->new($era_name, $year);

あたらしく Date::Japanese::Era クラスのインスタンスを生成します。グレ
ゴリア暦から生成する場合には、月と日が必須です。グレゴリア暦からの変換
には Date::Calc が必要です。

元号名は日本語か ASCII のどちらでもかまいません。Jcode モジュールがイ
ンストールされている場合は、エンコードを codeset() で設定できます。デ
フォルトは EUC-JP です。

入力が不正な場合(たとえば、元号と年の存在しない組合せや、存在しない元
号名など)、例外が投げられます。

=item name

  $name = $era->name;

元号名を日本語で返します。エンコーディングは codeset() で設定できます。
デフォルトは EUC-JP です。

=item gengou

name() の別名です。

=item name_ascii

  $name_ascii = $era->name_ascii;

元号名を US-ASCII で返します。

=item year

  $year = $era->year;

年を和暦で返します。

=item gregorian_year

  $year = $era->gregorian_year;

年をグレゴリア暦で返します。

=back

=head1 EXAMPLES

  # 2001年は H-13
  my $era = Date::Japanese::Era->new(2001, 8, 31);
  printf "%s-%s", uc(substr($era->name_ascii, 0, 1)), $era->year;

  # 西暦に変換
  my $era = Date::Japanese::Era->new('平成', 13);
  print $era->gregorian_year;   # 2001

=head1 CAVEATS

=over 4

=item *

元号が変わった日は新しい方(後の方)の元号で扱われます。

=item *

現状サポートしているのは「明治」までです。

=item *

もし現在の元号(平成)が変わった場合、Date::Japanese::Era::Table をアッ
プグレードする必要があります。(Table はグローバル変数として定義してあ
るので、必要なら上書きすることとも出来ます)

=back

=head1 TODO

=over 4

=item *

日付パラメータはいろんなフォーマットがありえます。Date::Simple などで
置き換えるべきかもしれません。

=item *

もっと以前の元号もサポート。

=back

=head1 AUTHOR

Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>

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

=head1 SEE ALSO

L<Date::Calc>, L<Jcode>, L<Date::Simple>

=cut