=encoding utf-8

=head1 NAME

Blosxom::Header::ja - 一意に HTTP ヘッダを指定する

=head1 SYNOPSIS

  use Blosxom::Header;

  my $header = Blosxom::Header->instance;

  $header->set(
      Status        => '304 Not Modified',
      Last_Modified => 'Wed, 23 Sep 2009 13:36:33 GMT',
  );

  my $status  = $header->get( 'Status' );
  my $bool    = $header->exists( 'ETag' );
  my @deleted = $header->delete( qw/Content-Disposition Content-Length/ );

  $header->push_cookie( @cookies );
  $header->push_p3p( @p3p );

  $header->clear;

=head1 DESCRIPTION

ブロッサムは単一の CGI スクリプトとして動作する、
ウェブログ・アプリケーションの一つである。
このアプリケーションは、C<$header> というハッシュのリファレンスをグローバル化する。
C<$header> は CGI モジュールの C<header()> 関数に渡され、HTTP ヘッダを生成する。

  package blosxom;
  use CGI;
  our $header = { -type => 'text/html' };
  # プラグインを読み込む
  print CGI::header( $header );

C<header()> は C<$header> のキーについて、大文字と小文字を区別しない。
また、キーの先頭にハイフンを付加するかどうかも任意だ。
他方、ハッシュのキーは大文字と小文字を区別する。
したがって、複数のプラグインが共存するような状況では、一意に C<$header>
を操作することができない。

=head2 METHODS

=over 4

=item $header = Blosxom::Header->instance

Blosxom::Header インスタンスを返す。インスタンスが存在しなければ、
新たに作成する。

=item $bool = $header->is_initialized

C<$blosxom::header> が初期化されているとき、真を返す。
初期化されていないとき、偽を返す。
Blosxom は C<blosxom::generate()> を呼ぶ直前に、この変数を初期化する。
C<$bool> が偽のとき、下記のメソッドは例外を投げる。

=item $header->set( $field => $value )

=item $header->set( $f1 => $v1, $f2 => $v2, ... )

$field で指定したフィールドに、$value を代入する。
フィールド名は大文字と小文字を区別しない。
またハイフンの代わりに、アンダーバーを使うこともできる。

$value は基本的に文字列をとる。
特に、フィールド名として C<Set-Cookie> あるいは C<P3P>
を指定したとき、リストのリファレンスをとる。

  $header->set( Set_Cookie => [ $cookie1, $cookie2 ] );
  $header->set( P3P => [ qw/CAO DSP LAW CURa/ ] );

=item $value = $header->get( $field )

=item @values = $header->get( $field )

引数としてフィールド名をとり、文字列を返す。
フィールドが存在しなければ C<undef> を返す。
また、リスト・コンテキストで、リストを返す。

  my @cookie = $header->get( 'Set-Cookie' );
  my @p3p    = $header->get( 'P3P' );

=item $bool = $header->exists( $field )

引数としてフィールド名をとり、フィールドが存在するとき真を返す。
存在しないとき偽を返す。

=item @deleted = $header->delete( @fields )

指定したフィールドをすべて削除する。
削除したフィールドの値を返す。

=item $header->push_cookie( @cookies )

Set-Cookie ヘッダを追加する。

=item $header->push_p3p( @p3p )

P3P タグを追加する。

=item $header->clear

すべてのフィールドを削除する。

=back

=head2 CONVENIENCE METHODS

以下のメソッドは、引数をつけたとき C<set()>、つけないとき C<get()> として働く。

=over 4

=item $header->attachment

  $header->attachment( 'foo.png' );

=item $header->charset

文字セットを指定する。C<< $header->type >> に C<charset> が含まれている場合、
この属性は無視される。

  $header->charset( 'utf-8' );

=item $header->cookie

  $header->cookie( [ 'foo', 'bar' ] );
  $header->cookie( 'baz' );

=item $header->expires

  $header->expires( '+30s' ); # 30 秒後
  $header->expires( '+10m' ); # 10 分後
  $header->expires( '+1h'  ); # 1 時間後
  $header->expires( '-1d'  ); # 昨日
  $header->expires( 'now'  ); # 現在
  $header->expires( '+3M'  ); # ３ヶ月後
  $header->expires( '+10y' ); # 10 年後

  # at the indicated time & date
  $header->expires( 'Thu, 25 Apr 1999 00:40:33 GMT' );

=item $header->nph

  $header->nph( 1 );

=item $header->p3p

  $header->p3p( [ qw/CAO DSP LAW CURa/ ] );
  $header->p3p( 'CAO DSP LAW CURa' );

=item $header->status

  $header->status( '304' );

=item $header->target

  $header->target( 'ResultsWindow' );

=item $header->type

メディア・タイプを指定する。

  $header->type( 'text/plain' );

この属性が C<undef> の場合、C<CGI::header()> がデフォルトの Content-Type ヘッダを
出力する。Content-Type ヘッダを出力したくない場合、空の文字列を代入
しなければならない。

  $header->type( q{} );

=back

=head1 DEPENDENCIES

L<Blosxom 2.0.0|http://blosxom.sourceforge.net/> or higher.

=head1 SEE ALSO

L<Blosxom::Header::Proxy>, L<CGI>, L<Class::Singleton>

=head1 AUTHOR

穴澤亮 (anazawa@cpan.org)

=head1 LICENSE AND COPYRIGHT

L<Perl Artistic ライセンス|perlartistic>に準ずる。

=cut
