/ 
Blosxom-Header-0.05004
/ Blosxom::Header

NAME

Blosxom::Header - Missing interface to modify HTTP headers

SYNOPSIS

# Object-oriented interface

use Blosxom::Header;

my $Header = Blosxom::Header->instance;

# or

use Blosxom::Header qw/$Header/;

$Header->set(
    Status        => '304 Not Modified',
    Last_Modified => 'Wed, 23 Sep 2009 13:36:33 GMT',
);

my $status = $Header->get( 'Status' );
my $bool = $Header->exists( 'ETag' );
my @deleted = $Header->delete( qw/Content-Disposition Content-Length/ );

$Header->push_cookie( @cookies );
$Header->push_p3p( @tags );

$Header->clear;


# Procedural interface

use Blosxom::Header qw(
    header_get    header_set  header_exists
    header_delete header_push
);

header_set(
    Status        => '304 Not Modified',
    Last_Modified => 'Wed, 23 Sep 2009 13:36:33 GMT',
);

my $status = header_get( 'Status' );
my $bool = header_exists( 'ETag' );
my @deleted = header_delete( qw/Content-Disposition Content-Length/ );

header_push( Set_Cookie => @cookies );
header_push( P3P => @tags );

DESCRIPTION

Blosxom, an weblog application, globalizes $header which is a reference to a hash. This application passes $header to CGI::header() to generate HTTP headers.

package blosxom;
use CGI;
our $header = { -type => 'text/html' };
# Loads plugins
print CGI::header( $header );

header() doesn't care whether keys of $header are lowercased nor starting with a dash, and also transliterates underscores into dashes in field names.

HOW THIS MODULE NORMALIZES FIELD NAMES

To specify field names consistently, we need to normalize them. If you follow one of normalization rules, you can modify $header consistently. This module normalizes field names as follows.

Remember how Blosxom initializes $header:

$header = { -type => 'text/html' };

A key -type is starting with a dash and lowercased, and so this module follows the same rules:

'Status'  # not normalized
'status'  # not normalized
'-status' # normalized

How about Content-Length? It contains a dash. To avoid quoting when specifying hash keys, this module transliterates dashes into underscores in field names:

'Content-Length'  # not normalized
'-content-length' # not normalized
'-content_length' # normalized

If you follow the above normalization rule, you can modify $header directly. In other words, this module is compatible with the way modifying $header directly when you follow the above rule. Blosxom::Header::Fast explains the details.

VARIABLE

The following variable is exported on demand.

$Header

The same reference as Blosxom::Header->instance returns.

use Blosxom::Header qw/$Header/;

In this case, this module creates the instance when loaded. Otherwise doesn't.

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

A synonym for Blosxom::Header->instance->push_cookie( @cookies ).

header_push( P3P => @tags )

A synonym for Blosxom::Header->instance->push_p3p( @tags ).

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.

INSTANCE METHODS

$bool = $header->is_initialized

Returns a Boolean value telling whether $blosxom::header is initialized or not. Blosxom initializes the variable just before blosxom::generate() is called. If $bool was false, the following methods throw exceptions.

Internally, this method is a shortcut for

$bool = ref $blosxom::header eq 'HASH';
$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 header field name ($field) isn't case-sensitive. You can use '_' as a replacement for '-' in header names.

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        => [ qw/CAO DSP LAW CURa/ ],
);
$value = $header->get( $field )
@values = $header->get( @fields )

Returns the value of one or more header fields.

The following forms are obsolete. Use cookie() or p3p() instead.

my @cookies = $header->get( 'Set-Cookie' );
my @tags    = $header->get( 'P3P' );

# become

my @cookies = $header->cookie;
my @tags    = $header->p3p;
$bool = $header->exists( $field )

Returns a Boolean value telling whether the specified HTTP header exists.

@deleted = $header->delete( @fields )

Deletes the specified elements from HTTP headers. Returns values of deleted elements.

$header->push_cookie( @cookies )

Pushes the Set-Cookie headers onto HTTP headers. Returns the number of the elements following the completed push_cookie().

my @cookies = $header->get( 'Set-Cookie' ); # ( 'foo', 'bar' )
$header->push_cookie( 'baz' );
@cookies = $header->get( 'Set-Cookie' ); # ( 'foo', 'bar', 'baz' )
$header->push_p3p( @p3p )

Adds P3P tags to the P3P header.

my @tags = $header->get( 'P3P' ); # ( 'CAO', 'DSP' )
$header->push_p3p( 'LAW', 'CURa' );
@tags = $header->get( '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. In scalar context return the number of distinct field names.

CONVENIENCE METHODS

The following methods were named after parameters recognized by CGI::header(). They can both be used to read and to set the value of an attribute. The value is set if you pass an argument to the method. If the given attribute wasn't defined then undef is returned.

$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 $cd = $header->get( 'Content-Disposition' );
# => 'attachment; filename="genome.jpg"'
$header->charset

Returns the upper-cased character set specified in the Content-Type header. If not provided, defaults to ISO-8859-1.

$charset = $header->charset; # UTF-8 (Readonly)
$header->cookie

Represents the Set-Cookie headers. The parameter can be an array.

$header->cookie( 'foo', 'bar' );
my @cookies = $header->cookie; # ( 'foo', 'bar' )
$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' );
$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 either 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

my $status = $header->get( 'Status' ); # 304 Not Modified
$header->set( Status => '304 Not Modified' );
$header->target

Represents the Window-Target header.

$header->target( 'ResultsWindow' );
my $target = $header->target; # ResultsWindow

$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' );

$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 @ct   = $heder->type;  # ( 'text/html', 'charset=ISO-8859-1' )

my $ct = $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 modify $blosxom::header before the variable was initialized. See $header->is_initialized.

Useless use of %s with no values

You used the push_cookie() or push_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::Proxy, CGI, Class::Singleton

ACKNOWLEDGEMENT

Blosxom was written by Rael Dornfest. The Blosxom Development Team succeeded 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.