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";
I am form: hear me submit.
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 . 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.