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
    the CGI manpage, the IO::Scalar manpage, the HTML::Stream manpage, the
    print entry in the perlfunc manpage

    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: README,v 1.8 2000/01/07 16:43:55 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.