NAME
    CGI::Application::Plugin::Header - Plugin for handling header props.

SYNOPSIS
      package MyApp;
      use parent 'CGI::Application';
      use CGI::Application::Plugin::Header;

      sub do_something {
          my $self = shift;

          my $header = $self->header; # => CGI::Header object

          # get header props.
          my $type = $header->type; # => "text/plain"

          # set header props.
          $header->type("text/html");

          # compatible with the core methods of CGI::Application
          $self->header_props( type => "text/plain" );
          $self->header_add( type => "text/plain" );

          ...
      }

DESCRIPTION
    This plugin provides you the common syntax to handle CGI.pm-compatible
    HTTP header properties.

    By using this plugin, your application is capable of the following
    methods, where $cgiapp denotes the instance of your application which
    inherits from CGI::Application:

  ATTRIBUTES
    $header = $cgiapp->header
        Returns a CGI::Header object associated with $cgiapp. You can use
        all methods of $header.

          sub cgiapp_postrun {
              my ( $self, $body_ref ) = @_;
              $self->header->set( 'Content-Length' => length $$body_ref );
          }

    $header = $cgiapp->header( CGI::Header->new(...) )
        You can also define your "header" class which inherits from
        "CGI::Header". For example,

          package MyApp::Header;
          use parent 'CGI::Header';
          use CGI::Cookie;

          sub cookies {
              my $self    = shift;
              my $cookies = $self->header->{cookies} ||= [];

              return $cookies unless @_;

              if ( ref $_[0] eq 'HASH' ) {
                  push @$cookies, map { CGI::Cookie->new($_) } @_;
              }
              else {
                  push @$cookies, CGI::Cookie->new( @_ );
              }

              $self;
          }

        You can set "header" as follows:

          # using new()

          my $query  = CGI->new;
          my $header = MyApp::Header->new( query => $query );
          my $app    = MyApp->new( query => $query, header => $header );


          # using header()

          my $app = MyApp->new;

          $app->header( MyApp::Header->new( query => $app->query ) );

  METHODS
    This plugin overrides the following methods of CGI::Application:

    %header_props = $cgiapp->header_props
    %header_props = $cgiapp->header_props( $k1 => $v1, $k2 => $v2, ... )
    %header_props = $cgiapp->header_props({ $k1 => $v1, $k2 => $v2, ... })
    %header_props = $cgiapp->header_props({})
        Behaves like CGI::Application's "header_props" method, but the
        return format is modified. "keys" of %header_props are lowercased
        and start with a dash. The following aliases are used:

          '-content-type' -> '-type'
          '-cookie'       -> '-cookies'

        It's guaranteed that the keys are unique.

    $cgiapp->header_add( $k1 => $v1, $k2 => $v2, ... )
    $cgiapp->header_add({ $k1 => $v1, $k2 => $v2, ... })
        Behaves like CGI::Application's "header_add" method.

  COMPATIBILITY
    Header property names are normalized by $header automatically, and so
    this plugin breaks your code which depends on the return value of
    "header_props":

      my %header_props = $cgiapp->header_props; # => ( -cookies => 'ID=123456' )

      if ( exists $header_props{-cookie} ) {
          ...
      }

    Those codes can be rewritten using $header as well as "header_props" or
    "header_add":

      if ( $cgiapp->header->exists('-cookie') ) {
          ...
      }

    The following plugins are compatible with this module:

    CGI::Application::Plugin::Redirect

    The following plugins are roughly compatible with this module:

    CGI::Application::Plugin::Stream
        "Setting a custom Content-Length/-Content-Length header" is not
        supported by this module. In other words, the "stream_file" method
        always overwrites the "Content-Length" header.

    CGI::Application::Plugin::Session
        You need to overwrite the "alias" table of "CGI::Header":

          use parent 'CGI::Header';

          sub _build_alias {
              +{
                  'cookies'      => 'cookie',
                  'content-type' => 'type',
              };
          }

          sub cookies {
              my $self = shift;
              return $self->header->{cookies} unless @_;
              $self->header->{cookies} = shift;
              $self;
          }

          sub cookie {
              my $self = shift;
              $self->cookies(@_);
          }

AUTHOR
    Ryo Anazawa (anazawa@cpan.org)

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