.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Test::Input 3pm"
.TH CGI::Test::Input 3pm "2022-06-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Test::Input \- Abstract representation of POST input
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # Deferred class, only heirs can be created
\& # $input holds a CGI::Test::Input object
\&
\& $input\->add_widget($w);                     # done internally for you
\&
\& $input\->add_field("name", "value");         # manual input construction
\& $input\->add_file("name", "path");           # deferred reading
\& $input\->add_file_now("name", "/tmp/path");  # read file immediately
\&
\& syswrite INPUT, $input\->data, $input\->length;   # if you really have to
\&
\& # $test is a CGI::Test object
\& $test\->POST("http://server:70/cgi\-bin/script", $input);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`CGI::Test::Input\*(C'\fR class is deferred.  It is an abstract representation
of \s-1HTTP POST\s0 request input, as expected by the \f(CW\*(C`POST\*(C'\fR routine of \f(CW\*(C`CGI::Test\*(C'\fR.
.PP
Unless you wish to issue a \f(CW\*(C`POST\*(C'\fR request manually to provide carefully
crafted input, you do not need to learn the interface of this hierarchy,
nor even bother knowing about it.
.PP
Otherwise, you need to decide which \s-1MIME\s0 encoding you want, and create an
object of the appropriate type.  Note that file uploading requires the use
of the \f(CW\*(C`multipart/form\-data\*(C'\fR encoding:
.PP
.Vb 4
\&           MIME Encoding                    Type to Create
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& application/x\-www\-form\-urlencoded   CGI::Test::Input::URL
\& multipart/form\-data                 CGI::Test::Input::Multipart
.Ve
.PP
Once the object is created, you will be able to add name/value tuples
corresponding to the \s-1CGI\s0 parameters to submit.
.PP
For instance:
.PP
.Vb 4
\&    my $input = CGI::Test::Input::Multipart\->new();
\&    $input\->add_field("login", "ram");
\&    $input\->add_field("password", "foobar");
\&    $input\->add_file("organization", "/etc/news/organization");
.Ve
.PP
Then, to inspect what is normally sent to the \s-1HTTP\s0 server:
.PP
.Vb 4
\&    print "Content\-Type: ", $input\->mime_type, "\e015\e012";
\&    print "Content\-Length: ", $input\->length, "\e015\e012";
\&    print "\e015\e012";
\&    print $input\->data;
.Ve
.PP
But usually you'll hand out the \f(CW$input\fR object to the \f(CW\*(C`POST\*(C'\fR routine
of \f(CW\*(C`CGI::Test\*(C'\fR.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Creation Routine"
.IX Subsection "Creation Routine"
It is called \f(CW\*(C`new\*(C'\fR as usual.  All subclasses have
the same creation routine signature, which takes no parameter.
.SS "Adding Parameters"
.IX Subsection "Adding Parameters"
\&\s-1CGI\s0 parameter are name/value tuples.  In case of file uploads, they can have
a content as well, the value being the file path on the client machine.
.ie n .IP """add_field"" \fIname\fR, \fIvalue\fR" 4
.el .IP "\f(CWadd_field\fR \fIname\fR, \fIvalue\fR" 4
.IX Item "add_field name, value"
Adds the \s-1CGI\s0 parameter \fIname\fR, whose value is \fIvalue\fR.
.IP "add_file \fIname\fR, \fIpath\fR" 4
.IX Item "add_file name, path"
Adds the file upload parameter \fIname\fR, located at \fIpath\fR.
.Sp
The file is not read immediately, so it must remain available until
the \fIdata\fR routine is called, at least.  It is not an error if the file
cannot be read at that time.
.Sp
When not using the \f(CW\*(C`multipart/form\-data\*(C'\fR encoding, only the name/path
tuple will be transmitted to the script.
.IP "add_file_now \fIname\fR, \fIpath\fR" 4
.IX Item "add_file_now name, path"
Same as \f(CW\*(C`add_file\*(C'\fR, but the file is immediately read and can therefore
be disposed of afterwards.  However, the file \fBmust\fR exist.
.IP "add_widget \fIwidget\fR" 4
.IX Item "add_widget widget"
Add any widget, i.e. a \f(CW\*(C`CGI::Test::Form::Widget\*(C'\fR object.  This routine
is called internally by \f(CW\*(C`CGI::Test\*(C'\fR to construct the input data when
submiting a form via \s-1POST.\s0
.SS "Generation"
.IX Subsection "Generation"
.ie n .IP """data""" 4
.el .IP "\f(CWdata\fR" 4
.IX Item "data"
Returns the data, under the proper encoding.
.ie n .IP """mime_type""" 4
.el .IP "\f(CWmime_type\fR" 4
.IX Item "mime_type"
Returns the proper \s-1MIME\s0 encoding type, suitable for inclusion within
a Content-Type header.
.ie n .IP """length""" 4
.el .IP "\f(CWlength\fR" 4
.IX Item "length"
Returns the data length.
.SH "AUTHORS"
.IX Header "AUTHORS"
The original author is Raphael Manfredi.
.PP
Steven Hilton was long time maintainer of this module.
.PP
Current maintainer is Alexander Tokarev \fI<tokarev@cpan.org>\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBCGI::Test\fR\|(3), \fBCGI::Test::Input::URL\fR\|(3), \fBCGI::Test::Input::Multipart\fR\|(3).