HTTP::Request::Common - Construct common HTTP::Request
       objects

SYNOPSIS

         use HTTP::Request::Common;
         $ua = LWP::UserAgent->new;
         $ua->request(GET 'http://www.sn.no/');
         $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);

DESCRIPTION

       This module provide functions that return newly created
       HTTP::Request objects.  These functions are usually more
       convenient than the standard HTTP::Request constructor for
       these common requests.  The following functions are
       provided.

       GET $url, [Header => Value,...]
           The GET() function returns a HTTP::Request object
           initialized with the GET method and the specified URL.
           Without additional arguments it is exactly equivalent
           to the following call

             HTTP::Request->new(GET => $url)

           but is less clutter.  It also reads better when used
           together with the LWP::UserAgent->request() method:

             my $ua = new LWP::UserAgent;
             my $res = $ua->request(GET 'http://www.sn.no')
             if ($res->is_success) { ...

           You can also initialize the header values in the
           request by specifying some key/value pairs as optional
           arguments.  For instance:

             $ua->request(GET 'http://www.sn.no',
                              If_Match => 'foo',
                              From     => 'gisle@aas.no',
                         );

           A header key called 'Content' is special and when seen
           the value will initialize the content part of the
           request instead of setting a header.

       HEAD $url, [Header => Value,...]
           Like GET() but the method in the request is HEAD.

       PUT $url, [Header => Value,...]
           Like GET() but the method in the request is PUT.

       POST $url, [$form_ref], [Header => Value,...]
           hash reference parameter ($form_ref).  This argument
           can be used to pass key/value pairs for the form
           content.  By default we will initialize a request
           using the application/x-www-form-urlencoded content
           type.  This means that you can emulate a HTML <form>
           POSTing like this:

             POST 'http://www.perl.org/survey.cgi',
                  [ name   => 'Gisle Aas',
                    email  => 'gisle@aas.no',
                    gender => 'M',
                    born   => '1964',
                    perc   => '3%',
                  ];

           This will create a HTTP::Request object that looks
           like this:

             POST http://www.perl.org/survey.cgi
             Content-Length: 66
             Content-Type: application/x-www-form-urlencoded

             name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25

           The POST method also supports the multipart/form-data
           content used for Form-based File Upload as specified
           in RFC 1867.  You trigger this content format by
           specifying a content type of 'form-data'.  If one of
           the values in the $form_ref is an array reference,
           then it is treated as a file part specification with
           the following values:

             [ $file, $filename, Header => Value... ]

           The first value in the array ($file) is the name of a
           file to open.  This file will be read an its content
           placed in the request.  The routine will croak if the
           file can't be opened.  Use an undef as $file value if
           you want to specify the content directly.  The
           $filename is the filename to report in the request.
           If this value is undefined, then the basename of the
           $file will be used.  You can specify an empty string
           as $filename if you don't want any filename in the
           request.

           Sending my ~/.profile to the survey used as example
           above can be achieved by this:





                  Content_Type => 'form-data',
                  Content      => [ name  => 'Gisle Aas',
                                    email => 'gisle@aas.no',
                                    gender => 'M',
                                    born   => '1964',
                                    init   => ["$ENV{HOME}/.profile"],
                                  ]

           This will create a HTTP::Request object that almost
           looks this (the boundary and the content of your
           ~/.profile is likely to be different):

             POST http://www.perl.org/survey.cgi
             Content-Length: 388
             Content-Type: multipart/form-data; boundary="6G+f"

             --6G+f
             Content-Disposition: form-data; name="name"

             Gisle Aas
             --6G+f
             Content-Disposition: form-data; name="email"

             gisle@aas.no
             --6G+f
             Content-Disposition: form-data; name="gender"

             M
             --6G+f
             Content-Disposition: form-data; name="born"

             1964
             --6G+f
             Content-Disposition: form-data; name="init"; filename=".profile"
             Content-Type: text/plain

             PATH=/local/perl/bin:$PATH
             export PATH

             --6G+f--

SEE ALSO

       the HTTP::Request manpage, the LWP::UserAgent manpage

COPYRIGHT

       Copyright 1997, Gisle Aas

       This library is free software; you can redistribute it
       and/or modify it under the same terms as Perl itself.