Skip to content
handle CGI.pm-compatible HTTP header properties
Perl
Find file
Pull request Compare This branch is 8 commits behind master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib/CGI
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('type'); # => "text/plain"
      $props->exists('type'); # => true

      # update $header 
      $props->set( type => 'text/plain' ); # overwrite
      $props->delete('type'); # => "text/plain"
      $props->clear; # => $self

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

      # convenience methods
      $props->p3p(qw/CAO DSP LAW CURa/);
      $props->expires('+3d');
      $props->nph(1);
      $props->push_cookie( @cookies ); # @cookies are CGI::Cookie objects

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

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

DESCRIPTION
    This module helps you handle CGI.pm-compatible HTTP header properties.

    Unlike CGI::Header, this module focuses on manipulating the header
    property itself. If you're familiar with CGI::Application's
    "header_add()", "header_props()" or "header_type()" method, you can use
    this module easily.

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).

    $props->handler
        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->handler('redirect');
          $props->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-Length' -> 'content-length'

        2. start with a dash
              'content-length' -> '-content-length'

        3. use underscores instead of dashes except for the first character
              'content-length' -> '-content_length'

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

          # for CGI#header
          '-content_type'  -> '-type'
          '-cookies'       -> '-cookie'
          '-set_cookie'    -> '-cookie'
          '-window_target' -> '-target'

          # for CGI#redirect
          '-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( $prop )
    $value = $props->set( $prop => $value )
        Get or set the value of the header property. The property name
        ($prop) is not case sensitive. You can use dashes as a replacement
        for underscores in property names.

          $props->get('content_length');
          $props->get('Content-Length');

        The $value argument may be a plain string or a reference to an array
        of CGI::Cookie objects for the "cookie" property:

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

          # $cookie1 and $cookie2 are CGI::Cookie objects
          $props->set( cookie => [$cookie1, $cookie2] );
          my $cookies = $props->get('cookie'); # => [$cookie1, $cookie2]

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

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

    $bool = $props->exists( $prop )
        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
        identicalt 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);

        NOTE: If the "-nph" pragma is enabled, you can't set this property
        to a false value.

          if ( $props->query->nph ) { # <=> "use CGI '-nph';"
              $props->nph(0); # die "The '-nph' pragma is enabled'
          }

    $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.

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 477:
        You forgot a '=back' before '=head4'

    Around line 493:
        '=item' outside of any '=over'

Something went wrong with that request. Please try again.