NAME
Blosxom::Header - Object representing CGI response headers
SYNOPSIS
# Object-oriented interface
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 @deleted = $header->delete( qw/Content-Disposition Content-Length/ );
# Procedural interface
use Blosxom::Header qw/header_set header_get header_delete/;
header_set(
Status => '304 Not Modified',
Last_Modified => 'Wed, 23 Sep 2009 13:36:33 GMT',
);
my $status = header_get( 'Status' );
my @deleted = header_delete( qw/Content-Disposition Content-Length/ );
DESCRIPTION
This module provides Blosxom plugin developers with an interface to handle CGI response headers.
VARIABLE
FUNCTIONS
The following functions are exported on demand.
- @values = header_get( @fields )
-
A synonym for
Blosxom::Header->instance->get()
. - header_set( $field => $value )
- header_set( $f1 => $v2, $f2 => $v2, ... )
-
A synonym for
Blosxom::Header->instance->set()
. - $bool = header_exists( $field )
-
A synonym for
Blosxom::Header->instance->exists()
. - @deleted = header_delete( @fields )
-
A synonym for
Blosxom::Header->instance->delete()
. -
This function is obsolete and will be removed in 0.06. See "HANDLING COOKIES".
-
A synonym for
Blosxom::Header->instance->push_p3p()
. - each_header( CodeRef )
- $field = each_header()
- ( $field, $value ) = each_header()
-
A synonym for
Blosxom::Header->instance->each()
. - header_push()
-
This function is obsolete and will be removed in 0.06.
CLASS METHODS
- $header = Blosxom::Header->instance
-
Returns a current Blosxom::Header object instance or create a new one.
- $header = Blosxom::Header->has_instance
-
Returns a reference to any existing instance or
undef
if none is defined. - $bool = Blosxom::Header->is_initialized
-
Returns a Boolean value telling whether
$blosxom::header
is initialized or not. Blosxom initializes the variable just beforeblosxom::generate()
is called. If$bool
was false,instance()
would throw an exception.Internally, this method is a shortcut for
$bool = ref $blosxom::header eq 'HASH';
INSTANCE METHODS
- $value = $header->get( $field )
- @values = $header->get( @fields )
-
Returns the value of one or more header fields. Accepts a list of field names case-insensitive. You can use underscores as a replacement for dashes in header names.
- $header->set( $field => $value )
- $header->set( $f1 => $v1, $f2 => $v2, ... )
-
Sets the value of one or more header fields. Accepts a list of named arguments.
The $value argument must be a plain string, except for when the Set-Cookie or P3P header is specified. In exceptional cases, $value may be a reference to an array.
$header->set( Set_Cookie => [ $cookie1, $cookie2 ], P3P => [ 'CAO', 'DSP', 'LAW', 'CURa' ], );
- $bool = $header->exists( $field )
-
Returns a Boolean value telling whether the specified HTTP header exists.
- @deleted = $header->delete( @fields )
-
Deletes the specified fields from HTTP headers. Returns values of deleted fields.
-
This method is obsolete and will be removed in 0.06. Use
$header->set_cookie
instead. -
Adds P3P tags to the P3P header. Accepts a list of P3P tags.
# get P3P tags my @tags = $header->p3p; # ( 'CAO', 'DSP', 'LAW' ) # add P3P tags $header->push_p3p( 'CURa' ); @tags = $header->p3p; # ( 'CAO', 'DSP', 'LAW', 'CURa' )
- $header->clear
-
This will remove all header fields.
Internally, this method is a shortcut for
%{ $blosxom::header } = ( -type => q{} );
- @fields = $header->field_names
-
Returns the list of distinct names for the fields present in the header. The field names have case as returned by
CGI::header()
. In scalar context return the number of distinct field names. - $header->each( \&callback )
-
Apply a subroutine to each header field in turn. The callback routine is called with two parameters; the name of the field and a value. Any return values of the callback routine are ignored.
$header->each(sub { my ( $field, $value ) = @_; ... });
- $field = $header->each
- ( $field, $value ) = $header->each
-
When called in list context, returns two parameters; the name of the field and a value, so that you can iterate over it. When called in scalar context, returns only the field name for the next header field. When the header is entirely read, a null array is returned in list context, and
undef
in scalar context.while ( my ( $field, $value ) = $header->each ) { print "$field: $value\n"; }
You can reset the iterator by calling
$header->field_names
.If you
set()
ordelete()
header fields while you're iterating over it, you may get entries skipped or duplicated, so don't. - $bool = $header->is_empty
-
Returns a Boolean value telling whether
$header->field_names
returns a null array or not.$header->clear; my $is_empty = $header->is_empty; # true
- @headers = $header->flatten
-
Returns a new array that is a one-dimensional flattening of header fields.
my @headers = $header->flatten; # => ( 'P3P', [ 'CAO', 'DSP' ], 'Content-Type', 'text/plain' )
NOTE: This method does not flatten recursively.
HANDLING COOKIES
cookie()
and push_cookie()
are obsolete and will be removed in 0.06. These methods was replaced with set_cookie()
and get_cookie()
.
-
Overwrites existent cookie.
$header->set_cookie( ID => 123456 ); $header->set_cookie( ID => { value => '123456', path => '/', domain => '.example.com', expires => '+3M', } );
-
Returns a CGI::Cookie object whose
name()
is stringwise equal to$name
.my $id = $header->get_cookie( 'ID' ); # CGI::Cookie object my $value = $id->value; # 123456
CONVENIENCE METHODS
Most of these methods were named after parameters recognized by CGI::header()
. These can both be used to read and to set the value of a header. The value is set if you pass an argument to the method. If the given header wasn't defined then undef
would be returned.
Methods that deal with dates/times always convert their value to system time (seconds since Jan 1, 1970).
- $header->attachment
-
Can be used to turn the page into an attachment. Represents suggested name for the saved file.
$header->attachment( 'genome.jpg' ); my $attachment = $header->attachment; # genome.jpg my $disposition = $header->get( 'Content-Disposition' ); # => 'attachment; filename="genome.jpg"'
- $header->charset
-
Returns the upper-cased character set specified in the Content-Type header.
$charset = $header->charset; # UTF-8 (Readonly)
-
This method is obsolete and will be removed in 0.06. Use
$header->get_cookie
or$header->set_cookie
instead. - $header->date
-
This header represents the date and time at which the message was originated. This method expects machine time when the header value is set.
$header->date( time ); # set current date
NOTE: If any of expires(), nph() or cookie() was set, the Date header would be added automatically and you couldn't modify the value. In other words, the Date header would be fixed.
- $header->expires
-
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:
$header->expires( '+30s' ); # 30 seconds from now $header->expires( '+10m' ); # ten minutes from now $header->expires( '+1h' ); # one hour from now $header->expires( '-1d' ); # yesterday $header->expires( 'now' ); # immediately $header->expires( '+3M' ); # in three months $header->expires( '+10y' ); # in ten years time # at the indicated time & date $header->expires( 'Thu, 25 Apr 1999 00:40:33 GMT' ); # another representation of 'now' $header->expires( time );
- $header->last_modified
-
This header indicates the date and time at which the resource was last modified. This method expects machine time when the header value is set.
# check if document is more than 1 hour old if ( my $last_modified = $header->last_modified ) { if ( $last_modified < time - 60 * 60 ) { ... } }
- $header->nph
-
If set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script:
$header->nph( 1 );
- $header->p3p
-
Represents the P3P header. The parameter can be an array or a space-delimited string.
$header->p3p( qw/CAO DSP LAW CURa/ ); $header->p3p( 'CAO DSP LAW CURa' ); my @tags = $header->p3p; # ( 'CAO', 'DSP', 'LAW', 'CURa' )
In this case, the outgoing header will be formatted as:
P3P: policyref="/w3c/p3p.xml" CP="CAO DSP LAW CURa"
- $header->status
-
Represents HTTP status code.
$header->status( 304 ); my $code = $header->status; # 304
cf.
$header->set( Status => '304 Not Modified' ); my $status = $header->get( 'Status' ); # 304 Not Modified
- $header->target
-
Represents the Window-Target header.
$header->target( 'ResultsWindow' ); my $target = $header->target; # ResultsWindow
cf.
$header->set( Window_Target => 'ResultsWindow' ); $target = $header->get( 'Window-Target' ); # ResultsWindow
- $header->type
-
The Content-Type header indicates the media type of the message content.
$header->type( 'text/plain; charset=utf-8' );
The above is a shortcut for
$header->set( Content_Type => 'text/plain; charset=utf-8' );
The value returned will be converted to lower case, and potential parameters will be chopped off and returned as a separate value if in an array context.
my $type = $header->type; # 'text/html' my @type = $header->type; # ( 'text/html', 'charset=ISO-8859-1' )
cf.
my $content_type = $header->get( 'Content-Type' ); # => 'text/html; charset=ISO-8859-1'
If there is no such header field, then the empty string is returned. This makes it safe to do the following:
if ( $header->type eq 'text/html' ) { ... }
DIAGNOSTICS
- $blosxom::header hasn't been initialized yet
-
You attempted to create a Blosxom::Header object before the variable was initialized. See
Blosxom::Header->is_initialized()
. - Useless use of %s with no values
-
You used the
push_cookie()
orpush_p3p()
method with no argument apart from the array, like$header->push_cookie()
or$header->push_p3p()
. - Unknown status code "%d%d%d" passed to status()
-
The given status code is unknown to HTTP::Status.
DEPENDENCIES
Blosxom 2.0.0 or higher.
SEE ALSO
Blosxom::Header::Adapter, HTTP::Headers, Plack::Util, Class::Singleton
- D. Robinson and K.Coar, "The Common Gateway Interface (CGI) Version 1.1", RFC 3875, October 2004
ACKNOWLEDGEMENT
Blosxom was originally written by Rael Dornfest. The Blosxom Development Team succeeded to the maintenance.
BUGS AND LIMITATIONS
There are no known bugs in this module. Please report problems to ANAZAWA (anazawa@cpan.org). Patches are welcome.
AUTHOR
Ryo Anazawa (anazawa@cpan.org)
LICENSE AND COPYRIGHT
Copyright (c) 2011-2012 Ryo Anazawa. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.