view release on metacpan or  search on metacpan

lib/CGI/PrintWrapper.pm  view on Meta::CPAN

    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>

=head1 DESCRIPTION

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

You could just call C<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 B<CGI> with B<HTML::Stream>, the
problem which prompted my solution, illustrated above).

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

=head1 CONSTRUCTOR

=over

=item C<new ($h)>

Creates a new B<CGI::PrintWrapper>, printing the results of B<CGI>
methods onto the print handle object, C<$h>.

=item C<new ($h, @cgi_args)>

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

=back

=head1 METHODS

=over

=item C<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
C<param()>.

=item C<io ( )>

Returns the underlying print handle object.

=item C<AUTOLOAD>

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

=back

=head1 SEE ALSO

L<CGI>, L<IO::Scalar>, L<HTML::Stream>, L<perlfunc/print>

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

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

B<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.

=head1 DIAGNOSTICS

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

=over

=item No print handle

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

    $cgi = CGI::PrintWrapper->new;

=item '%s' is not a print handle

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

=item Couldn't create CGI object because %s

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

=back

=head1 BUGS AND CAVEATS

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

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

=head1 AUTHORS

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