NAME

       CGI::Test::Input - Abstract representation of POST input

SYNOPSIS

        # 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);

DESCRIPTION

       The "CGI::Test::Input" class is deferred.  It is an abstract representation of HTTP POST
       request input, as expected by the "POST" routine of "CGI::Test".

       Unless you wish to issue a "POST" request manually to provide carefully crafted input, you
       do not need to learn the interface of this hierarchy, nor even bother knowing about it.

       Otherwise, you need to decide which MIME encoding you want, and create an object of the
       appropriate type.  Note that file uploading requires the use of the "multipart/form-data"
       encoding:

                  MIME Encoding                    Type to Create
        ---------------------------------   ---------------------------
        application/x-www-form-urlencoded   CGI::Test::Input::URL
        multipart/form-data                 CGI::Test::Input::Multipart

       Once the object is created, you will be able to add name/value tuples corresponding to the
       CGI parameters to submit.

       For instance:

           my $input = CGI::Test::Input::Multipart->new();
           $input->add_field("login", "ram");
           $input->add_field("password", "foobar");
           $input->add_file("organization", "/etc/news/organization");

       Then, to inspect what is normally sent to the HTTP server:

           print "Content-Type: ", $input->mime_type, "\015\012";
           print "Content-Length: ", $input->length, "\015\012";
           print "\015\012";
           print $input->data;

       But usually you'll hand out the $input object to the "POST" routine of "CGI::Test".

INTERFACE

   Creation Routine
       It is called "new" as usual.  All subclasses have the same creation routine signature,
       which takes no parameter.

   Adding Parameters
       CGI 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.

       "add_field" name, value
           Adds the CGI parameter name, whose value is value.

       add_file name, path
           Adds the file upload parameter name, located at path.

           The file is not read immediately, so it must remain available until the data routine
           is called, at least.  It is not an error if the file cannot be read at that time.

           When not using the "multipart/form-data" encoding, only the name/path tuple will be
           transmitted to the script.

       add_file_now name, path
           Same as "add_file", but the file is immediately read and can therefore be disposed of
           afterwards.  However, the file must exist.

       add_widget widget
           Add any widget, i.e. a "CGI::Test::Form::Widget" object.  This routine is called
           internally by "CGI::Test" to construct the input data when submiting a form via POST.

   Generation
       "data"
           Returns the data, under the proper encoding.

       "mime_type"
           Returns the proper MIME encoding type, suitable for inclusion within a Content-Type
           header.

       "length"
           Returns the data length.

AUTHORS

       The original author is Raphael Manfredi.

       Steven Hilton was long time maintainer of this module.

       Current maintainer is Alexander Tokarev <tokarev@cpan.org>.

SEE ALSO

       CGI::Test(3), CGI::Test::Input::URL(3), CGI::Test::Input::Multipart(3).