NAME

CGI::PrintWrapper - CGI methods output to a print handle

SYNOPSIS

    use CGI::PrintHandle;
    use IO::Scalar; # just an example
    use HTML::Stream; # continuing the example

    # Fine, there really is no such tag as "WEAK":
    HTML::Stream->accept_tag ('WEAK');

    my $content = '';
    my $handle = IO::Scalar->new (\$content);
    my $cgi = CGI::PrintHandle ($handle, '');
    my $html = HTML::Stream->new ($handle);

    # Not a very exciting example:
    $cgi->start_form;
    $html->WEAK->t ('I am form: hear me submit.')->_WEAK;
    $cgi->submit;
    $cgi->end_form;

    print "$content\n";
<FORM METHOD="POST"  ENCTYPE="application/x-www-form-urlencoded">
<WEAK>I am form: hear me submit.</WEAK><INPUT TYPE="submit" NAME=".submit"></FORM>

DESCRIPTION

CGI::PrintWrapper arranges for CGI methods to output their results by printing onto an arbitrary handle. This gets around the problem that the CGI's subs return strings, which may be inconvient when you wish to use CGI for something besides CGI script processing.

You could just call print yourself on the appropriate file handle, but there are many contexts in which it is cleaner to provide the extra abstraction (such as mixing CGI with HTML::Stream, the problem which prompted my solution, illustrated above).

CGI::PrintWrapper creates the necessary callbacks for printing dynamically, updating the symbol table as it encounters a new CGI method.

CONSTRUCTOR

new ($h)

Creates a new CGI::PrintWrapper, printing the results of CGI methods onto the print handle object, $h. Because of the semantics of CGI's own new method, this form of new is mostly useful in CGI scripts, as it will attempt to read from STDIN. To prevent this behavior, call the next form of new with an empty string, thus:

    my $cgi = CGI::PrintWrapper->new ($some_handle, '');

new ($h, @cgi_args)

Creates a new CGI::PrintWrapper, printing the results of CGI methods onto the print handle object, $h, and using the additional arguments to construct the CGI object.

METHODS

cgi ( )

Returns the underlying CGI object. This is handy for invoking methods on the object whose result you do not wish to print, such as param().

io ( )

Returns the underlying print handle object.

AUTOLOAD

Initially, CGI::PrintWrapper has no methods (except as mentioned above). As the caller invokes CGI methods, AUTOLOAD creates anonymous subroutines to perform the actual CGI method call indirection and print the results with the print handle object. It also updates the symbol table for CGI::PrintWrapper so that future calls can bypass AUTOLOAD. This makes a CGI::PrintWrapper object transparently a CGI object, usable as a drop-in replacement.

SEE ALSO

CGI, IO::Scalar, HTML::Stream, "print" in perlfunc

CGI is the canonical package for working with fill-out forms on the web. It is particularly useful for generating HTML for such forms.

IO::Scalar is a handy package for treating a string as an object supporting IO handle semantics.

HTML::Stream is a nice package for writing HTML markup and content into an IO handle with stream semantics. It's main drawback is lack of support for HTML 4.0.

DIAGNOSTICS

The following are the diagnostics generated by Class::Class. Items marked "(W)" are non-fatal (invoke Carp::carp); those marked "(F)" are fatal (invoke Carp::croak).

No print handle

(F) The caller tried to create a new CGI::PrintWrapper without supplying the mandatory first argument, a print handle:

    $cgi = CGI::PrintWrapper->new;

'%s' is not a print handle

(F) The caller tried to create a new CGI::PrintWrapper using an object which does not support print as the mandatory first argument.

Couldn't create CGI object because %s

(F) The caller tried to create a new CGI::PrintWrapper using bad addtional arguments to the constructor for CGI.

BUGS AND CAVEATS

There is no way of controlling now to use CGI, for example, if you wished to precompile all the methods. Instead, you should make the appropriate call to use yourself for CGI, in addition to that for CGI::PrintWrapper, thus:

    use CGI qw(:compile);
    use CGI::PrintWrapper;

AUTHORS

B. K. Oxley (binkley) at Home <binkley@bigfoot.com>. I am grateful to my employer, DataCraft, Inc., for time spent preparing this package for public consumption.

COPYRIGHT

  $Id: PrintWrapper.pm,v 1.11 2000/01/07 16:40:24 binkley Exp $

  Copyright 1999, B. K. Oxley (binkley).

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.