#
# $Id: Page.pm,v 0.1.1.1 2001/04/17 10:41:55 ram Exp $
#
# Copyright (c) 2001, Raphael Manfredi
#
# You may redistribute only under the terms of the Artistic License,
# as specified in the README file that comes with the distribution.
#
# HISTORY
# $Log: Page.pm,v $
# Revision 0.1.1.1 2001/04/17 10:41:55 ram
# patch2: added note about possible parameters in content_type
#
# Revision 0.1 2001/03/31 10:54:03 ram
# Baseline for first Alpha release.
#
# $EndLog$
#
use strict;
package CGI::Test::Page;
#
# An abstract representation of a page, returned by an HTTP request.
# The page can be an error, or a real page, each with its own class hierarchy.
#
use Carp::Datum;
use Getargs::Long;
use Log::Agent;
#
# ->make
#
# Creation routine
#
sub make { logconfess "deferred" }
#
# Common attribute access
#
sub content_type { $_[0]->{content_type} }
sub user { $_[0]->{user} }
sub server { $_[0]->{server} }
#
# Queries
#
sub error_code { 0 } # Error code (0 = OK)
sub is_error { 0 } # True if page indicates HTTP error
sub form_count { 0 }
sub is_ok { !$_[0]->is_error }
#
# ->forms
#
# Returns list ref of CGI::Test::Form objects, one per <FORM></FORM> in the
# document. The order is the same as the one in the raw document.
#
# Meant to be redefined in CGI::Test::Page::HTML.
#
sub forms {
DFEATURE my $f_;
my $self = shift;
return DVAL [];
}
#
# ->delete
#
# Done with this page, cleanup by breaking circular refs.
#
sub delete {
DFEATURE my $f_;
my $self = shift;
$self->{server} = undef;
return DVOID;
}
1;
=head1 NAME
CGI::Test::Page - Abstract represention of an HTTP reply content
=head1 SYNOPSIS
# Deferred class, only heirs can be created
# $page holds a CGI::Test::Page object
use CGI::Test;
ok 1, $page->is_ok;
ok 2, $page->user ne ''; # authenticated access
my $ctype = $page->content_type;
ok 3, $ctype eq "text/plain";
$page->delete;
=head1 DESCRIPTION
The C<CGI::Test::Page> class is deferred. It is an abstract representation
of an HTTP reply content, which would be displayed on a browser, as a page.
It does not necessarily hold HTML content.
Here is an outline of the class hierarchy tree, with the leading C<CGI::Test::>
string stripped for readability, and a trailing C<*> indicating deferred
clases:
Page*
Page::Error
Page::Real*
Page::HTML
Page::Other
Page::Text
Those classes are constructed as needed by C<CGI::Test>. You must always
call I<delete> on them to break the circular references if you care about
reclaiming unused memory.
=head1 INTERFACE
This is the interface defined at the C<CGI::Test::Page> level.
Each subclass may add further specific features, but the following is
available to the whole hierarchy:
=over 4
=item C<content_type>
The MIME content type, along with parameters, as it appeared in the headers.
For instance, it can be:
text/html; charset=ISO-8859-1
Don't assume it to be just C<text/html> though. Use something like:
ok 1, $page->content_type =~ m|^text/html\b|;
in your regression tests, which will match whether there are parameters
following the content type or not.
=item C<delete>
Breaks circular references to allow proper reclaiming of unused memory.
Must be the last thing to call on the object before forgetting about it.
=item C<error_code>
The error code. Will be 0 to mean OK, but otherwise HTTP error codes
are used, as described by L<HTTP::Status>.
=item C<forms>
Returns a list reference containing all the CGI forms on the page,
as C<CGI::Test::Form> objects. Will be an empty list for anything
but C<CGI::Test::Page::HTML>, naturally.
=item C<form_count>
The amount of forms held in the C<forms> list.
=item C<is_error>
Returns I<true> when the page indicates an HTTP error.
=item C<is_ok>
Returns I<true> when the page is not the result of an HTTP error.
=item C<server>
Returns the server object that returned the page. Currently, this is
the C<CGI::Test> object, but it might change one day. In any case, this
is the place where GET/POST requests may be addresed.
=item C<user>
The authenticated user that requested this page, or C<undef> if no
authentication was made.
=back
=head1 AUTHOR
Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
=head1 SEE ALSO
CGI::Test::Page::Error(3), CGI::Test::Page::Real(3).
=cut