Problem

You want to submit form values to a CGI script from your program.

Solution

If you're submitting form values using the GET method, create a URL and encode the form using the query_form method:

use LWP::Simple;
use URI::URL;

my $url = url('http://www.perl.com/cgi-bin/cpan_mod');
$url->query_form(module => 'DB_File', readme => 1);
$content = get($url);

If you're using the POST method, create your own user agent and encode the content appropriately:

use HTTP::Request::Common qw(POST);
use LWP::UserAgent;

$ua = LWP::UserAgent->new();
my $req = POST 'http://www.perl.com/cgi-bin/cpan_mod',
               [ module => 'DB_File', readme => 1 ];
$content = $ua->request($req)->as_string;

Discussion

For simple operations, the procedural interface of the LWP::Simple module is sufficient. For fancier ones, the LWP::UserAgent module provides a virtual browser object, which you manipulate using method calls.

The format of a query string is:

field1=value1&field2=value2&field3=value3

In GET requests, this is encoded in the URL being requested:

http://www.site.com/path/to/
script.cgi?field1=value1&field2=value2&field3=value3

Fields must still be properly escaped, so setting the arg form parameter to "this isn't <EASY>&<FUN>" would yield:

http://www.site.com/path/to/
script.cgi?arg=%22this+isn%27t+%3CEASY%3E+%26+%3CFUN%3E%22

The query_form method called on a URL object correctly escapes the form values for you, or you could use the URI::Escape::uri_escape or CGI::escape_html functions on your own. In POST requests, the query string is the body of the HTTP document sent to the CGI script.

We can use the LWP::Simple module to submit data in a GET request, but there is no corresponding LWP::Simple interface for POST requests. Instead, the HTTP::Request::Common module's POST function conveniently creates a properly formatted request with everything properly escaped.

If you need to go through a proxy, construct your user agent and tell it to use a proxy this way:

$ua->proxy(['http', 'ftp'] => 'http://proxy.myorg.com:8081');

That says that both HTTP and FTP requests through this user agent should be routed through the proxy on port 8081 at proxy.myorg.com .

See Also

The documentation for the CPAN modules LWP::Simple, LWP::UserAgent, HTTP::Request::Common, URI::Escape, and URI::URL; Recipe 20.1