The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Blosxom-Header-0.05008
/ Blosxom::Header

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

$Header

This variable isn't exported any more. Sorry for incovenience :(

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

push_cookie( @cookies )

This function is obsolete and will be removed in 0.06. See "HANDLING COOKIES".

push_p3p( @tags )

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 before blosxom::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.

$header->push_cookie( @cookies )

This method is obsolete and will be removed in 0.06. Use $header->set_cookie instead.

$header->push_p3p( @tags )

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

$header->set_cookie( $name => $value )
$header->set_cookie( $name => { value => $value, ... } )

Overwrites existent cookie.

  $header->set_cookie( ID => 123456 );

  $header->set_cookie(
     ID => {
         value   => '123456',
         path    => '/',
         domain  => '.example.com',
         expires => '+3M',
      }
  );
$cookie = $header->get_cookie( $name )

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)
$header->cookie

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