MAN page from RedHat Other perl-libwww-5.35-1.i386.rpm

lib::HTTP::Request::Common

Section: User Contributed Perl Documentation (3)
Updated: libwww-perl-5.35
Index

NAME

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::Requestobjects. These functions are usually more convenient to use than thestandard HTTP::Request constructor for these common requests. Thefollowing functions are provided.

GET $url, Header => Value,...

The GET() function returns a HTTP::Request object initialized with theGET method and the specified URL. Without additional arguments itis exactly equivalent to the following call

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

but is less clutter. It also reads better when used together with theLWP::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 specifyingsome key/value pairs as optional arguments. For instance:

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

A header key called `Content' is special and when seen the value willinitialize 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,...]

This works mostly like GET() with POST as method, but this functionalso takes a second optional array or hash reference parameter($form_ref). This argument can be used to pass key/value pairs forthe form content. By default we will initialize a request using theapplication/x-www-form-urlencoded content type. This means thatyou can emulate a HTML <form> POSTing like this:

  POST 'http://www.perl.org/survey.cgi',       [ name   => 'Gisle Aas',         email  => 'gisleAATTaas.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 usedfor Form-based File Upload as specified in RFC 1867. You triggerthis content format by specifying a content type of 'form-data' asone of the request headers. If one of the values in the $form_ref isan array reference, then it is treated as a file part specificationwith the following interpretation:

  [ $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. Theroutine will croak if the file can't be opened. Use an undef as $filevalue if you want to specify the content directly. The $filename isthe filename to report in the request. If this value is undefined,then the basename of the $file will be used. You can specify an emptystring as $filename if you don't want any filename in the request.

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

  POST 'http://www.perl.org/survey.cgi',       Content_Type => 'form-data',       Content      => [ name  => 'Gisle Aas',                         email => 'gisleAATTaas.no',                         gender => 'M',                         born   => '1964',                         init   => ["$ENV{HOME}/.profile"],                       ]

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

  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"    gisleAATTaas.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--

COPYRIGHT

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

This document was created byman2html,using the manual pages.