Skip to content
handle CGI.pm-compatible HTTP header properties
Perl
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib/CGI/Header
t
tools
xt
Makefile.PL
README

README

NAME
    CGI::Header::Props - handle CGI.pm-compatible HTTP header properties

SYNOPSIS
      use CGI;
      use CGI::Header::Props;

      my $query = CGI->new;

      # CGI.pm-compatibe HTTP header properties
      my $header = {
          type    => 'text/html',
          charset => 'utf-8'
      };

      my $props = CGI::Header::Props->new(
          query   => $query,
          handler => 'header', # or 'redirect'
          header  => $header
      );

      # inspect $header
      $props->get('Content-Length'); # => 3002
      $props->exists('Content-Length'); # => true

      # update $header 
      $props->set( 'Content-Length' => 3002 ); # overwrite
      $props->delete('Content-Length'); # => 3002
      $props->clear; # => $self

      # convenience methods
      $props->attachment('genome.jpg');
      $props->charset('utf-8'); 
      $props->cookie( @cookies ); # @cookies are CGI::Cookie objects
      $props->expires('+3d');
      $props->location('http://somewhere.else/in/movie/land');
      $props->nph(1);
      $props->p3p(qw/CAO DSP LAW CURa/);
      $props->status('301 Moved Permanently');
      $props->type('image/gif');

      $props->header; # same reference as $header

      # stringify $header
      $props->handler('redirect');
      $props->as_string; # invokes $query->redirect

VERSION
    This document refers to CGI::Header::Props version 0.01.

DESCRIPTION
    This module helps you handle CGI.pm-compatible HTTP header properties.
    Instances of CGI.pm-based application often hold those properties.
    CGI.pm's "header" or "redirect" method is used to convert the header
    property into CGI response headers.

    This module is inspired by how CGI::Application handles the header
    property. The framework has "header_props" attribute. "header_add"
    method can be used to update "header_props". "header_type" represents
    which method of CGI.pm ("header" or "redirect") stringifies
    "header_props" when "run" is invoked.

METHODS
    $props = CGI::Header::Props->new
        Create a new "CGI::Header::Props" object.

    $props->header
        Returns the header hash associated with this "CGI::Header::Props"
        object. This attribute defaults to a reference to an empty hash.

    $props->query
        Returns the query object associated with this "CGI::Header::Props"
        object. This attribute defaults to the Singleton instance of CGI.pm
        ($CGI::Q).

    $self = $props->handler('redirect')
        Works like CGI::Application's "header_type()" method. This method
        can be used to declare that you are setting a redirection header.
        This attribute defaults to "header".

          $props->hadnler('redirect')->as_string; # invokes $props->query->redirect

    $self = $props->rehash
        Rebuilds the header hash to normalize property names without
        changing the reference. Returns this object itself. If property
        names aren't normalized, the methods listed below won't work as you
        expect.

          my $h1 = $props->header;
          # => {
          #      '-content_type'   => 'text/plain',
          #      'Set-Cookie'      => 'ID=123456; path=/',
          #      'expires'         => '+3d',
          #      '-target'         => 'ResultsWindow',
          #      '-content-length' => '3002',
          # }

          $props->rehash;

          my $h2 = $props->header; # same reference as $h1
          # => {
          #      '-type'           => 'text/plain',
          #      '-cookie'         => 'ID=123456; path=/',
          #      '-expires'        => '+3d',
          #      '-target'         => 'ResultsWindow',
          #      '-content-length' => '3002',
          # }

        Normalized property names are:

        1. lowercased
              'Content_Type' -> 'content_type'

        2. use dashes instead of underscores except for the first character
              'content_type' -> 'content-type'

        CGI.pm's "header()" method also accepts aliases of property names.
        This module converts them as follows:

          'content-type'  -> 'type'
          'cookies'       -> 'cookie'
          'set-cookie'    -> 'cookie'
          'uri'           -> 'location'
          'url'           -> 'location'
          'window-target' -> 'target'

        If a property name is duplicated, throws an exception:

          $props->header;
          # => {
          #     -Type        => 'text/plain',
          #     Content_Type => 'text/html',
          # }

          $props->rehash; # die "Property "type' already exists"

    $value = $props->get( $field )
    $value = $props->set( $field => $value )
        Get or set the value of the header field. The field name ($field) is
        not case sensitive.

          $props->get('content-length');
          $props->get('Content-Length');

        The $value argument must be a plain string:

          $props->set( 'Content-Length' => 3002 );
          my $length = $props->get('Content-Length'); # => 3002

    $value = $props->delete( $field )
        Deletes the specified field. Returns the value of the deleted field.

          my $value = $props->delete('Content-Disposition'); # => "inline"

    $bool = $props->exists( $field )
        Returns a Boolean value telling whether the specified property
        exists.

          if ( $props->exists('ETag') ) {
              ...
          }

    $self = $props->clear
        This will remove all header properties. Returns this object itself.

    $props->as_string
        Stringifies the header props. associated with this object. The
        header props. will be passed to CGI.pm's "header()" or "redirect()"
        method (It depends on the return value of "$props->handler"). It's
        identical to:

          my $handler = $props->handler; # => "header" or "redirect"
          $props->query->$handler( $props->header );

   PROPERTIES
    The following methods were named after property names recognized by
    CGI.pm's "header" method. Most of these methods can both be used to read
    and to set the value of a property.

    If you pass an argument to the method, the property value will be set,
    and also the current object itself will be returned ; therefore you can
    chain methods as follows:

      $props->type('text/html')->charset('utf-8');

    If no argument is supplied, the property value will be returned. If the
    given property doesn't exist, "undef" will be returned.

    $self = $props->attachment( $filename )
    $filename = $props->attachment
        Get or set the "attachment" property. Can be used to turn the page
        into an attachment. Represents suggested name for the saved file.

          $props->attachment('genome.jpg');
          my $filename = $props->attachment; # => "genome.jpg"

        In this case, the outgoing header will be formatted as:

          Content-Disposition: attachment; filename="genome.jpg"

    $self = $props->charset( $character_set )
    $character_set = $props->charset
        Get or set the "charset" property. Represents the character set sent
        to the browser.

    $self = $props->cookie( @cookies )
    @cookies = $props->cookie
        Get or set the "cookie" property. The parameter can be a list of
        CGI::Cookie objects.

    $props->push_cookie( @cookies )
        Given a list of CGI::Cookie objects, appends them to the "cookie"
        property.

    $self = $props->expires( $format )
    $format = $props->expires
        Get or set the "expires" property. The Expires header gives the date
        and time after which the entity should be considered stale. You can
        specify an absolute or relative expiration interval. The following
        forms are all valid for this field:

          $props->expires('+30s'); # 30 seconds from now
          $props->expires('+10m'); # ten minutes from now
          $props->expires( '+1h'); # one hour from now
          $props->expires( 'now'); # immediately
          $props->expires( '+3M'); # in three months
          $props->expires('+10y'); # in ten years time

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

        If set to a true value, the "date" property will be removed
        automatically.

    $self = $props->location( $url )
    $url = $props->location
        Get or set the Location header.

          $props->location('http://somewhere.else/in/movie/land');

    $self = $props->nph( $bool )
    $bool = $props->nph
        Get or set the "nph" property. If set to a true value, will issue
        the correct headers to work with a NPH (no-parse-header) script.

          $props->nph(1);

    $self = $props->p3p( @tags )
    @tags = $props->p3p
        Get or set the "p3p" property. The parameter can be an array or a
        space-delimited string. Returns a list of P3P tags. (In scalar
        context, returns the number of P3P tags.)

          $props->p3p(qw/CAO DSP LAW CURa/);
          # or
          $props->p3p('CAO DSP LAW CURa');

          my @tags = $props->p3p; # => ("CAO", "DSP", "LAW", "CURa")
          my $size = $props->p3p; # => 4

        In this case, the outgoing header will be formatted as:

          P3P: policyref="/w3c/p3p.xml", CP="CAO DSP LAW CURa"

    $props->push_p3p( @tags )
        Given a list of P3P tags, appends them to the "p3p" property.

    $self = $props->status( $status )
    $status = $props->status
        Get or set the Status header.

          $props->status('304 Not Modified');

    $self = $props->target( $window_target )
    $window_target = $props->target
        Get or set the Window-Target header.

          $props->target('ResultsWindow');

    $self = $props->type( $media_type )
    $media_type = $props->type
        Get or set the "type" property. Represents the media type of the
        message content.

          $props->type('text/html');

SEE ALSO
    CGI

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.

Something went wrong with that request. Please try again.