Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
297 lines (221 sloc) 9.9 KB
CGI::Header::Props - handle HTTP header properties
use CGI;
use CGI::Header::Props;
my $query = CGI->new;
# 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->cookie( @cookies ); # @cookies are CGI::Cookie objects
$props->p3p(qw/CAO DSP LAW CURa/);
$props->status('301 Moved Permanently');
$props->header; # same reference as $header
# stringify $header
$props->as_string; # invokes $query->redirect
This document refers to CGI::Header::Props version 0.01.
This module helps you handle HTTP header properties.
Instances of application often hold those properties.'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 ("header" or "redirect") stringifies
"header_props" when "run" is invoked.
$props = CGI::Header::Props->new
Create a new "CGI::Header::Props" object.
Returns the header hash associated with this "CGI::Header::Props"
object. This attribute defaults to a reference to an empty hash.
Returns the query object associated with this "CGI::Header::Props"
object. This attribute defaults to the Singleton instance of
$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
my $h1 = $props->header;
# => {
# '-content_type' => 'text/plain',
# 'Set-Cookie' => 'ID=123456; path=/',
# 'expires' => '+3d',
# '-target' => 'ResultsWindow',
# '-content-length' => '3002',
# }
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''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:
# => {
# -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.
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
if ( $props->exists('ETag') ) {
$self = $props->clear
This will remove all header properties. Returns this object itself.
Stringifies the header props. associated with this object. The
header props. will be passed to'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 );
The following methods were named after property names recognized by'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:
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.
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"
$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
$self = $props->location( $url )
$url = $props->location
Get or set the Location header.
$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.
$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.
$self = $props->type( $media_type )
$media_type = $props->type
Get or set the "type" property. Represents the media type of the
message content.
Ryo Anazawa (
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
Jump to Line
Something went wrong with that request. Please try again.