local-lib5/man/man3/lwptut.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "lwptut 3"
 132 .TH lwptut 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 lwptut \-\- An LWP Tutorial
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 \&\s-1LWP\s0 (short for \*(L"Library for \s-1WWW\s0 in Perl\*(R") is a very popular group of
 138 Perl modules for accessing data on the Web. Like most Perl
 139 module\-distributions, each of \s-1LWP\s0's component modules comes with
 140 documentation that is a complete reference to its interface. However,
 141 there are so many modules in \s-1LWP\s0 that it's hard to know where to start
 142 looking for information on how to do even the simplest most common
 143 things.
 144 .PP
 145 Really introducing you to using \s-1LWP\s0 would require a whole book \*(-- a book
 146 that just happens to exist, called \fIPerl & \s-1LWP\s0\fR. But this article
 147 should give you a taste of how you can go about some common tasks with
 148 \&\s-1LWP\s0.
 149 .Sh "Getting documents with LWP::Simple"
 150 .IX Subsection "Getting documents with LWP::Simple"
 151 If you just want to get what's at a particular \s-1URL\s0, the simplest way
 152 to do it is LWP::Simple's functions.
 153 .PP
 154 In a Perl program, you can call its \f(CW\*(C`get($url)\*(C'\fR function.  It will try
 155 getting that \s-1URL\s0's content.  If it works, then it'll return the
 156 content; but if there's some error, it'll return undef.
 157 .PP
 158 .Vb 2
 159 \&  my $url = 'http://freshair.npr.org/dayFA.cfm?todayDate=current';
 160 \&    # Just an example: the URL for the most recent /Fresh Air/ show
 161 .Ve
 162 .PP
 163 .Vb 3
 164 \&  use LWP::Simple;
 165 \&  my $content = get $url;
 166 \&  die "Couldn't get $url" unless defined $content;
 167 .Ve
 168 .PP
 169 .Vb 1
 170 \&  # Then go do things with $content, like this:
 171 .Ve
 172 .PP
 173 .Vb 6
 174 \&  if($content =~ m/jazz/i) {
 175 \&    print "They're talking about jazz today on Fresh Air!\en";
 176 \&  }
 177 \&  else {
 178 \&    print "Fresh Air is apparently jazzless today.\en";
 179 \&  }
 180 .Ve
 181 .PP
 182 The handiest variant on \f(CW\*(C`get\*(C'\fR is \f(CW\*(C`getprint\*(C'\fR, which is useful in Perl
 183 one\-liners.  If it can get the page whose \s-1URL\s0 you provide, it sends it
 184 to \s-1STDOUT\s0; otherwise it complains to \s-1STDERR\s0.
 185 .PP
 186 .Vb 1
 187 \&  % perl \-MLWP::Simple \-e "getprint 'http://cpan.org/RECENT'"
 188 .Ve
 189 .PP
 190 That is the \s-1URL\s0 of a plain text file that lists new files in \s-1CPAN\s0 in
 191 the past two weeks.  You can easily make it part of a tidy little
 192 shell command, like this one that mails you the list of new
 193 \&\f(CW\*(C`Acme::\*(C'\fR modules:
 194 .PP
 195 .Vb 2
 196 \&  % perl \-MLWP::Simple \-e "getprint 'http://cpan.org/RECENT'"  \e
 197 \&     | grep "/by\-module/Acme" | mail \-s "New Acme modules! Joy!" $USER
 198 .Ve
 199 .PP
 200 There are other useful functions in LWP::Simple, including one function
 201 for running a \s-1HEAD\s0 request on a \s-1URL\s0 (useful for checking links, or
 202 getting the last-revised time of a \s-1URL\s0), and two functions for
 203 saving/mirroring a \s-1URL\s0 to a local file. See the LWP::Simple documentation for the full details, or chapter 2 of \fIPerl
 204 & \s-1LWP\s0\fR for more examples.
 205 .Sh "The Basics of the \s-1LWP\s0 Class Model"
 206 .IX Subsection "The Basics of the LWP Class Model"
 207 LWP::Simple's functions are handy for simple cases, but its functions
 208 don't support cookies or authorization, don't support setting header
 209 lines in the \s-1HTTP\s0 request, generally don't support reading header lines
 210 in the \s-1HTTP\s0 response (notably the full \s-1HTTP\s0 error message, in case of an
 211 error). To get at all those features, you'll have to use the full \s-1LWP\s0
 212 class model.
 213 .PP
 214 While \s-1LWP\s0 consists of dozens of classes, the main two that you have to
 215 understand are LWP::UserAgent and HTTP::Response. LWP::UserAgent
 216 is a class for \*(L"virtual browsers\*(R" which you use for performing requests,
 217 and HTTP::Response is a class for the responses (or error messages)
 218 that you get back from those requests.
 219 .PP
 220 The basic idiom is \f(CW\*(C`$response = $browser\->get($url)\*(C'\fR, or more fully
 221 illustrated:
 222 .PP
 223 .Vb 1
 224 \&  # Early in your program:
 225 .Ve
 226 .PP
 227 .Vb 2
 228 \&  use LWP 5.64; # Loads all important LWP classes, and makes
 229 \&                #  sure your version is reasonably recent.
 230 .Ve
 231 .PP
 232 .Vb 1
 233 \&  my $browser = LWP::UserAgent\->new;
 234 .Ve
 235 .PP
 236 .Vb 1
 237 \&  ...
 238 .Ve
 239 .PP
 240 .Vb 2
 241 \&  # Then later, whenever you need to make a get request:
 242 \&  my $url = 'http://freshair.npr.org/dayFA.cfm?todayDate=current';
 243 .Ve
 244 .PP
 245 .Vb 3
 246 \&  my $response = $browser\->get( $url );
 247 \&  die "Can't get $url \-\- ", $response\->status_line
 248 \&   unless $response\->is_success;
 249 .Ve
 250 .PP
 251 .Vb 3
 252 \&  die "Hey, I was expecting HTML, not ", $response\->content_type
 253 \&   unless $response\->content_type eq 'text/html';
 254 \&     # or whatever content\-type you're equipped to deal with
 255 .Ve
 256 .PP
 257 .Vb 1
 258 \&  # Otherwise, process the content somehow:
 259 .Ve
 260 .PP
 261 .Vb 6
 262 \&  if($response\->decoded_content =~ m/jazz/i) {
 263 \&    print "They're talking about jazz today on Fresh Air!\en";
 264 \&  }
 265 \&  else {
 266 \&    print "Fresh Air is apparently jazzless today.\en";
 267 \&  }
 268 .Ve
 269 .PP
 270 There are two objects involved: \f(CW$browser\fR, which holds an object of
 271 class LWP::UserAgent, and then the \f(CW$response\fR object, which is of
 272 class HTTP::Response. You really need only one browser object per
 273 program; but every time you make a request, you get back a new
 274 HTTP::Response object, which will have some interesting attributes:
 275 .IP "\(bu" 4
 276 A status code indicating
 277 success or failure
 278 (which you can test with \f(CW\*(C`$response\->is_success\*(C'\fR).
 279 .IP "\(bu" 4
 280 An \s-1HTTP\s0 status
 281 line that is hopefully informative if there's failure (which you can
 282 see with \f(CW\*(C`$response\->status_line\*(C'\fR,
 283 returning something like \*(L"404 Not Found\*(R").
 284 .IP "\(bu" 4
 285 A \s-1MIME\s0 content-type like \*(L"text/html\*(R", \*(L"image/gif\*(R",
 286 \&\*(L"application/xml\*(R", etc., which you can see with
 287 \&\f(CW\*(C`$response\->content_type\*(C'\fR
 288 .IP "\(bu" 4
 289 The actual content of the response, in \f(CW\*(C`$response\->decoded_content\*(C'\fR.
 290 If the response is \s-1HTML\s0, that's where the \s-1HTML\s0 source will be; if
 291 it's a \s-1GIF\s0, then \f(CW\*(C`$response\->decoded_content\*(C'\fR will be the binary
 292 \&\s-1GIF\s0 data.
 293 .IP "\(bu" 4
 294 And dozens of other convenient and more specific methods that are
 295 documented in the docs for HTTP::Response, and its superclasses
 296 HTTP::Message and HTTP::Headers.
 297 .Sh "Adding Other \s-1HTTP\s0 Request Headers"
 298 .IX Subsection "Adding Other HTTP Request Headers"
 299 The most commonly used syntax for requests is \f(CW\*(C`$response =
 300 $browser\->get($url)\*(C'\fR, but in truth, you can add extra \s-1HTTP\s0 header
 301 lines to the request by adding a list of key-value pairs after the \s-1URL\s0,
 302 like so:
 303 .PP
 304 .Vb 1
 305 \&  $response = $browser\->get( $url, $key1, $value1, $key2, $value2, ... );
 306 .Ve
 307 .PP
 308 For example, here's how to send some more Netscape-like headers, in case
 309 you're dealing with a site that would otherwise reject your request:
 310 .PP
 311 .Vb 6
 312 \&  my @ns_headers = (
 313 \&   'User\-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
 314 \&   'Accept' => 'image/gif, image/x\-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
 315 \&   'Accept\-Charset' => 'iso\-8859\-1,*,utf\-8',
 316 \&   'Accept\-Language' => 'en\-US',
 317 \&  );
 318 .Ve
 319 .PP
 320 .Vb 1
 321 \&  ...
 322 .Ve
 323 .PP
 324 .Vb 1
 325 \&  $response = $browser\->get($url, @ns_headers);
 326 .Ve
 327 .PP
 328 If you weren't reusing that array, you could just go ahead and do this:
 329 .PP
 330 .Vb 6
 331 \&  $response = $browser\->get($url,
 332 \&   'User\-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
 333 \&   'Accept' => 'image/gif, image/x\-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
 334 \&   'Accept\-Charset' => 'iso\-8859\-1,*,utf\-8',
 335 \&   'Accept\-Language' => 'en\-US',
 336 \&  );
 337 .Ve
 338 .PP
 339 If you were only ever changing the 'User\-Agent' line, you could just change
 340 the \f(CW$browser\fR object's default line from \*(L"libwww\-perl/5.65\*(R" (or the like)
 341 to whatever you like, using the LWP::UserAgent \f(CW\*(C`agent\*(C'\fR method:
 342 .PP
 343 .Vb 1
 344 \&   $browser\->agent('Mozilla/4.76 [en] (Win98; U)');
 345 .Ve
 346 .Sh "Enabling Cookies"
 347 .IX Subsection "Enabling Cookies"
 348 A default LWP::UserAgent object acts like a browser with its cookies
 349 support turned off. There are various ways of turning it on, by setting
 350 its \f(CW\*(C`cookie_jar\*(C'\fR attribute. A \*(L"cookie jar\*(R" is an object representing
 351 a little database of all
 352 the \s-1HTTP\s0 cookies that a browser can know about. It can correspond to a
 353 file on disk (the way Netscape uses its \fIcookies.txt\fR file), or it can
 354 be just an in-memory object that starts out empty, and whose collection of
 355 cookies will disappear once the program is finished running.
 356 .PP
 357 To give a browser an in-memory empty cookie jar, you set its \f(CW\*(C`cookie_jar\*(C'\fR
 358 attribute like so:
 359 .PP
 360 .Vb 1
 361 \&  $browser\->cookie_jar({});
 362 .Ve
 363 .PP
 364 To give it a copy that will be read from a file on disk, and will be saved
 365 to it when the program is finished running, set the \f(CW\*(C`cookie_jar\*(C'\fR attribute
 366 like this:
 367 .PP
 368 .Vb 7
 369 \&  use HTTP::Cookies;
 370 \&  $browser\->cookie_jar( HTTP::Cookies\->new(
 371 \&    'file' => '/some/where/cookies.lwp',
 372 \&        # where to read/write cookies
 373 \&    'autosave' => 1,
 374 \&        # save it to disk when done
 375 \&  ));
 376 .Ve
 377 .PP
 378 That file will be an LWP-specific format. If you want to be access the
 379 cookies in your Netscape cookies file, you can use the
 380 HTTP::Cookies::Netscape class:
 381 .PP
 382 .Vb 2
 383 \&  use HTTP::Cookies;
 384 \&    # yes, loads HTTP::Cookies::Netscape too
 385 .Ve
 386 .PP
 387 .Vb 4
 388 \&  $browser\->cookie_jar( HTTP::Cookies::Netscape\->new(
 389 \&    'file' => 'c:/Program Files/Netscape/Users/DIR\-NAME\-HERE/cookies.txt',
 390 \&        # where to read cookies
 391 \&  ));
 392 .Ve
 393 .PP
 394 You could add an \f(CW\*(C`'autosave' => 1\*(C'\fR line as further above, but at
 395 time of writing, it's uncertain whether Netscape might discard some of
 396 the cookies you could be writing back to disk.
 397 .Sh "Posting Form Data"
 398 .IX Subsection "Posting Form Data"
 399 Many \s-1HTML\s0 forms send data to their server using an \s-1HTTP\s0 \s-1POST\s0 request, which
 400 you can send with this syntax:
 401 .PP
 402 .Vb 7
 403 \& $response = $browser\->post( $url,
 404 \&   [
 405 \&     formkey1 => value1,
 406 \&     formkey2 => value2,
 407 \&     ...
 408 \&   ],
 409 \& );
 410 .Ve
 411 .PP
 412 Or if you need to send \s-1HTTP\s0 headers:
 413 .PP
 414 .Vb 9
 415 \& $response = $browser\->post( $url,
 416 \&   [
 417 \&     formkey1 => value1,
 418 \&     formkey2 => value2,
 419 \&     ...
 420 \&   ],
 421 \&   headerkey1 => value1,
 422 \&   headerkey2 => value2,
 423 \& );
 424 .Ve
 425 .PP
 426 For example, the following program makes a search request to AltaVista
 427 (by sending some form data via an \s-1HTTP\s0 \s-1POST\s0 request), and extracts from
 428 the \s-1HTML\s0 the report of the number of matches:
 429 .PP
 430 .Vb 4
 431 \&  use strict;
 432 \&  use warnings;
 433 \&  use LWP 5.64;
 434 \&  my $browser = LWP::UserAgent\->new;
 435 .Ve
 436 .PP
 437 .Vb 1
 438 \&  my $word = 'tarragon';
 439 .Ve
 440 .PP
 441 .Vb 10
 442 \&  my $url = 'http://www.altavista.com/sites/search/web';
 443 \&  my $response = $browser\->post( $url,
 444 \&    [ 'q' => $word,  # the Altavista query string
 445 \&      'pg' => 'q', 'avkw' => 'tgz', 'kl' => 'XX',
 446 \&    ]
 447 \&  );
 448 \&  die "$url error: ", $response\->status_line
 449 \&   unless $response\->is_success;
 450 \&  die "Weird content type at $url \-\- ", $response\->content_type
 451 \&   unless $response\->content_is_html;
 452 .Ve
 453 .PP
 454 .Vb 7
 455 \&  if( $response\->decoded_content =~ m{AltaVista found ([0\-9,]+) results} ) {
 456 \&    # The substring will be like "AltaVista found 2,345 results"
 457 \&    print "$word: $1\en";
 458 \&  }
 459 \&  else {
 460 \&    print "Couldn't find the match\-string in the response\en";
 461 \&  }
 462 .Ve
 463 .Sh "Sending \s-1GET\s0 Form Data"
 464 .IX Subsection "Sending GET Form Data"
 465 Some \s-1HTML\s0 forms convey their form data not by sending the data
 466 in an \s-1HTTP\s0 \s-1POST\s0 request, but by making a normal \s-1GET\s0 request with
 467 the data stuck on the end of the \s-1URL\s0.  For example, if you went to
 468 \&\f(CW\*(C`imdb.com\*(C'\fR and ran a search on \*(L"Blade Runner\*(R", the \s-1URL\s0 you'd see
 469 in your browser window would be:
 470 .PP
 471 .Vb 1
 472 \&  http://us.imdb.com/Tsearch?title=Blade%20Runner&restrict=Movies+and+TV
 473 .Ve
 474 .PP
 475 To run the same search with \s-1LWP\s0, you'd use this idiom, which involves
 476 the \s-1URI\s0 class:
 477 .PP
 478 .Vb 3
 479 \&  use URI;
 480 \&  my $url = URI\->new( 'http://us.imdb.com/Tsearch' );
 481 \&    # makes an object representing the URL
 482 .Ve
 483 .PP
 484 .Vb 4
 485 \&  $url\->query_form(  # And here the form data pairs:
 486 \&    'title'    => 'Blade Runner',
 487 \&    'restrict' => 'Movies and TV',
 488 \&  );
 489 .Ve
 490 .PP
 491 .Vb 1
 492 \&  my $response = $browser\->get($url);
 493 .Ve
 494 .PP
 495 See chapter 5 of \fIPerl & \s-1LWP\s0\fR for a longer discussion of \s-1HTML\s0 forms
 496 and of form data, and chapters 6 through 9 for a longer discussion of
 497 extracting data from \s-1HTML\s0.
 498 .Sh "Absolutizing URLs"
 499 .IX Subsection "Absolutizing URLs"
 500 The \s-1URI\s0 class that we just mentioned above provides all sorts of methods
 501 for accessing and modifying parts of URLs (such as asking sort of \s-1URL\s0 it
 502 is with \f(CW\*(C`$url\->scheme\*(C'\fR, and asking what host it refers to with \f(CW\*(C`$url\->host\*(C'\fR, and so on, as described in the docs for the \s-1URI\s0 class.  However, the methods of most immediate interest
 503 are the \f(CW\*(C`query_form\*(C'\fR method seen above, and now the \f(CW\*(C`new_abs\*(C'\fR method
 504 for taking a probably-relative \s-1URL\s0 string (like \*(L"../foo.html\*(R") and getting
 505 back an absolute \s-1URL\s0 (like \*(L"http://www.perl.com/stuff/foo.html\*(R"), as
 506 shown here:
 507 .PP
 508 .Vb 2
 509 \&  use URI;
 510 \&  $abs = URI\->new_abs($maybe_relative, $base);
 511 .Ve
 512 .PP
 513 For example, consider this program that matches URLs in the \s-1HTML\s0
 514 list of new modules in \s-1CPAN:\s0
 515 .PP
 516 .Vb 4
 517 \&  use strict;
 518 \&  use warnings;
 519 \&  use LWP;
 520 \&  my $browser = LWP::UserAgent\->new;
 521 .Ve
 522 .PP
 523 .Vb 4
 524 \&  my $url = 'http://www.cpan.org/RECENT.html';
 525 \&  my $response = $browser\->get($url);
 526 \&  die "Can't get $url \-\- ", $response\->status_line
 527 \&   unless $response\->is_success;
 528 .Ve
 529 .PP
 530 .Vb 4
 531 \&  my $html = $response\->decoded_content;
 532 \&  while( $html =~ m/<A HREF=\e"(.*?)\e"/g ) {
 533 \&    print "$1\en";
 534 \&  }
 535 .Ve
 536 .PP
 537 When run, it emits output that starts out something like this:
 538 .PP
 539 .Vb 7
 540 \&  MIRRORING.FROM
 541 \&  RECENT
 542 \&  RECENT.html
 543 \&  authors/00whois.html
 544 \&  authors/01mailrc.txt.gz
 545 \&  authors/id/A/AA/AASSAD/CHECKSUMS
 546 \&  ...
 547 .Ve
 548 .PP
 549 However, if you actually want to have those be absolute URLs, you
 550 can use the \s-1URI\s0 module's \f(CW\*(C`new_abs\*(C'\fR method, by changing the \f(CW\*(C`while\*(C'\fR
 551 loop to this:
 552 .PP
 553 .Vb 3
 554 \&  while( $html =~ m/<A HREF=\e"(.*?)\e"/g ) {
 555 \&    print URI\->new_abs( $1, $response\->base ) ,"\en";
 556 \&  }
 557 .Ve
 558 .PP
 559 (The \f(CW\*(C`$response\->base\*(C'\fR method from HTTP::Message
 560 is for returning what \s-1URL\s0
 561 should be used for resolving relative URLs \*(-- it's usually just
 562 the same as the \s-1URL\s0 that you requested.)
 563 .PP
 564 That program then emits nicely absolute URLs:
 565 .PP
 566 .Vb 7
 567 \&  http://www.cpan.org/MIRRORING.FROM
 568 \&  http://www.cpan.org/RECENT
 569 \&  http://www.cpan.org/RECENT.html
 570 \&  http://www.cpan.org/authors/00whois.html
 571 \&  http://www.cpan.org/authors/01mailrc.txt.gz
 572 \&  http://www.cpan.org/authors/id/A/AA/AASSAD/CHECKSUMS
 573 \&  ...
 574 .Ve
 575 .PP
 576 See chapter 4 of \fIPerl & \s-1LWP\s0\fR for a longer discussion of \s-1URI\s0 objects.
 577 .PP
 578 Of course, using a regexp to match hrefs is a bit simplistic, and for
 579 more robust programs, you'll probably want to use an HTML-parsing module
 580 like HTML::LinkExtor or HTML::TokeParser or even maybe
 581 HTML::TreeBuilder.
 582 .Sh "Other Browser Attributes"
 583 .IX Subsection "Other Browser Attributes"
 584 LWP::UserAgent objects have many attributes for controlling how they
 585 work.  Here are a few notable ones:
 586 .IP "\(bu" 4
 587 \&\f(CW\*(C`$browser\->timeout(15);\*(C'\fR
 588 .Sp
 589 This sets this browser object to give up on requests that don't answer
 590 within 15 seconds.
 591 .IP "\(bu" 4
 592 \&\f(CW\*(C`$browser\->protocols_allowed( [ 'http', 'gopher'] );\*(C'\fR
 593 .Sp
 594 This sets this browser object to not speak any protocols other than \s-1HTTP\s0
 595 and gopher. If it tries accessing any other kind of \s-1URL\s0 (like an \*(L"ftp:\*(R"
 596 or \*(L"mailto:\*(R" or \*(L"news:\*(R" \s-1URL\s0), then it won't actually try connecting, but
 597 instead will immediately return an error code 500, with a message like
 598 \&\*(L"Access to 'ftp' URIs has been disabled\*(R".
 599 .IP "\(bu" 4
 600 \&\f(CW\*(C`use LWP::ConnCache; $browser\->conn_cache(LWP::ConnCache\->new());\*(C'\fR
 601 .Sp
 602 This tells the browser object to try using the \s-1HTTP/1\s0.1 \*(L"Keep\-Alive\*(R"
 603 feature, which speeds up requests by reusing the same socket connection
 604 for multiple requests to the same server.
 605 .IP "\(bu" 4
 606 \&\f(CW\*(C`$browser\->agent( 'SomeName/1.23 (more info here maybe)' )\*(C'\fR
 607 .Sp
 608 This changes how the browser object will identify itself in
 609 the default \*(L"User\-Agent\*(R" line is its \s-1HTTP\s0 requests.  By default,
 610 it'll send "libwww\-perl/\fIversionnumber\fR\*(L", like
 611 \&\*(R"libwww\-perl/5.65".  You can change that to something more descriptive
 612 like this:
 613 .Sp
 614 .Vb 1
 615 \&  $browser\->agent( 'SomeName/3.14 (contact@robotplexus.int)' );
 616 .Ve
 617 .Sp
 618 Or if need be, you can go in disguise, like this:
 619 .Sp
 620 .Vb 1
 621 \&  $browser\->agent( 'Mozilla/4.0 (compatible; MSIE 5.12; Mac_PowerPC)' );
 622 .Ve
 623 .IP "\(bu" 4
 624 \&\f(CW\*(C`push @{ $ua\->requests_redirectable }, 'POST';\*(C'\fR
 625 .Sp
 626 This tells this browser to obey redirection responses to \s-1POST\s0 requests
 627 (like most modern interactive browsers), even though the \s-1HTTP\s0 \s-1RFC\s0 says
 628 that should not normally be done.
 629 .PP
 630 For more options and information, see the full documentation for LWP::UserAgent.
 631 .Sh "Writing Polite Robots"
 632 .IX Subsection "Writing Polite Robots"
 633 If you want to make sure that your LWP-based program respects \fIrobots.txt\fR
 634 files and doesn't make too many requests too fast, you can use the LWP::RobotUA
 635 class instead of the LWP::UserAgent class.
 636 .PP
 637 LWP::RobotUA class is just like LWP::UserAgent, and you can use it like so:
 638 .PP
 639 .Vb 3
 640 \&  use LWP::RobotUA;
 641 \&  my $browser = LWP::RobotUA\->new('YourSuperBot/1.34', 'you@yoursite.com');
 642 \&    # Your bot's name and your email address
 643 .Ve
 644 .PP
 645 .Vb 1
 646 \&  my $response = $browser\->get($url);
 647 .Ve
 648 .PP
 649 But HTTP::RobotUA adds these features:
 650 .IP "\(bu" 4
 651 If the \fIrobots.txt\fR on \f(CW$url\fR's server forbids you from accessing
 652 \&\f(CW$url\fR, then the \f(CW$browser\fR object (assuming it's of class LWP::RobotUA)
 653 won't actually request it, but instead will give you back (in \f(CW$response\fR) a 403 error
 654 with a message \*(L"Forbidden by robots.txt\*(R".  That is, if you have this line:
 655 .Sp
 656 .Vb 2
 657 \&  die "$url \-\- ", $response\->status_line, "\enAborted"
 658 \&   unless $response\->is_success;
 659 .Ve
 660 .Sp
 661 then the program would die with an error message like this:
 662 .Sp
 663 .Vb 2
 664 \&  http://whatever.site.int/pith/x.html \-\- 403 Forbidden by robots.txt
 665 \&  Aborted at whateverprogram.pl line 1234
 666 .Ve
 667 .IP "\(bu" 4
 668 If this \f(CW$browser\fR object sees that the last time it talked to
 669 \&\f(CW$url\fR's server was too recently, then it will pause (via \f(CW\*(C`sleep\*(C'\fR) to
 670 avoid making too many requests too often. How long it will pause for, is
 671 by default one minute \*(-- but you can control it with the \f(CW\*(C`$browser\->delay( \f(CIminutes\f(CW )\*(C'\fR attribute.
 672 .Sp
 673 For example, this code:
 674 .Sp
 675 .Vb 1
 676 \&  $browser\->delay( 7/60 );
 677 .Ve
 678 .Sp
 679 \&...means that this browser will pause when it needs to avoid talking to
 680 any given server more than once every 7 seconds.
 681 .PP
 682 For more options and information, see the full documentation for LWP::RobotUA.
 683 .Sh "Using Proxies"
 684 .IX Subsection "Using Proxies"
 685 In some cases, you will want to (or will have to) use proxies for
 686 accessing certain sites and/or using certain protocols. This is most
 687 commonly the case when your \s-1LWP\s0 program is running (or could be running)
 688 on a machine that is behind a firewall.
 689 .PP
 690 To make a browser object use proxies that are defined in the usual
 691 environment variables (\f(CW\*(C`HTTP_PROXY\*(C'\fR, etc.), just call the \f(CW\*(C`env_proxy\*(C'\fR
 692 on a user-agent object before you go making any requests on it.
 693 Specifically:
 694 .PP
 695 .Vb 2
 696 \&  use LWP::UserAgent;
 697 \&  my $browser = LWP::UserAgent\->new;
 698 .Ve
 699 .PP
 700 .Vb 2
 701 \&  # And before you go making any requests:
 702 \&  $browser\->env_proxy;
 703 .Ve
 704 .PP
 705 For more information on proxy parameters, see the LWP::UserAgent documentation, specifically the \f(CW\*(C`proxy\*(C'\fR, \f(CW\*(C`env_proxy\*(C'\fR,
 706 and \f(CW\*(C`no_proxy\*(C'\fR methods.
 707 .Sh "\s-1HTTP\s0 Authentication"
 708 .IX Subsection "HTTP Authentication"
 709 Many web sites restrict access to documents by using \*(L"\s-1HTTP\s0
 710 Authentication\*(R". This isn't just any form of \*(L"enter your password\*(R"
 711 restriction, but is a specific mechanism where the \s-1HTTP\s0 server sends the
 712 browser an \s-1HTTP\s0 code that says \*(L"That document is part of a protected
 713 \&'realm', and you can access it only if you re-request it and add some
 714 special authorization headers to your request\*(R".
 715 .PP
 716 For example, the Unicode.org admins stop email-harvesting bots from
 717 harvesting the contents of their mailing list archives, by protecting
 718 them with \s-1HTTP\s0 Authentication, and then publicly stating the username
 719 and password (at \f(CW\*(C`http://www.unicode.org/mail\-arch/\*(C'\fR) \*(-- namely
 720 username \*(L"unicode\-ml\*(R" and password \*(L"unicode\*(R".
 721 .PP
 722 For example, consider this \s-1URL\s0, which is part of the protected
 723 area of the web site:
 724 .PP
 725 .Vb 1
 726 \&  http://www.unicode.org/mail\-arch/unicode\-ml/y2002\-m08/0067.html
 727 .Ve
 728 .PP
 729 If you access that with a browser, you'll get a prompt
 730 like
 731 \&\*(L"Enter username and password for 'Unicode\-MailList\-Archives' at server
 732 \&'www.unicode.org'\*(R".
 733 .PP
 734 In \s-1LWP\s0, if you just request that \s-1URL\s0, like this:
 735 .PP
 736 .Vb 2
 737 \&  use LWP;
 738 \&  my $browser = LWP::UserAgent\->new;
 739 .Ve
 740 .PP
 741 .Vb 3
 742 \&  my $url =
 743 \&   'http://www.unicode.org/mail\-arch/unicode\-ml/y2002\-m08/0067.html';
 744 \&  my $response = $browser\->get($url);
 745 .Ve
 746 .PP
 747 .Vb 4
 748 \&  die "Error: ", $response\->header('WWW\-Authenticate') || 'Error accessing',
 749 \&    #  ('WWW\-Authenticate' is the realm\-name)
 750 \&    "\en ", $response\->status_line, "\en at $url\en Aborting"
 751 \&   unless $response\->is_success;
 752 .Ve
 753 .PP
 754 Then you'll get this error:
 755 .PP
 756 .Vb 4
 757 \&  Error: Basic realm="Unicode\-MailList\-Archives"
 758 \&   401 Authorization Required
 759 \&   at http://www.unicode.org/mail\-arch/unicode\-ml/y2002\-m08/0067.html
 760 \&   Aborting at auth1.pl line 9.  [or wherever]
 761 .Ve
 762 .PP
 763 \&...because the \f(CW$browser\fR doesn't know any the username and password
 764 for that realm (\*(L"Unicode\-MailList\-Archives\*(R") at that host
 765 (\*(L"www.unicode.org\*(R").  The simplest way to let the browser know about this
 766 is to use the \f(CW\*(C`credentials\*(C'\fR method to let it know about a username and
 767 password that it can try using for that realm at that host.  The syntax is:
 768 .PP
 769 .Vb 5
 770 \&  $browser\->credentials(
 771 \&    'servername:portnumber',
 772 \&    'realm\-name',
 773 \&   'username' => 'password'
 774 \&  );
 775 .Ve
 776 .PP
 777 In most cases, the port number is 80, the default \s-1TCP/IP\s0 port for \s-1HTTP\s0; and
 778 you usually call the \f(CW\*(C`credentials\*(C'\fR method before you make any requests.
 779 For example:
 780 .PP
 781 .Vb 5
 782 \&  $browser\->credentials(
 783 \&    'reports.mybazouki.com:80',
 784 \&    'web_server_usage_reports',
 785 \&    'plinky' => 'banjo123'
 786 \&  );
 787 .Ve
 788 .PP
 789 So if we add the following to the program above, right after the \f(CW\*(C`$browser = LWP::UserAgent\->new;\*(C'\fR line...
 790 .PP
 791 .Vb 5
 792 \&  $browser\->credentials(  # add this to our $browser 's "key ring"
 793 \&    'www.unicode.org:80',
 794 \&    'Unicode\-MailList\-Archives',
 795 \&    'unicode\-ml' => 'unicode'
 796 \&  );
 797 .Ve
 798 .PP
 799 \&...then when we run it, the request succeeds, instead of causing the
 800 \&\f(CW\*(C`die\*(C'\fR to be called.
 801 .Sh "Accessing \s-1HTTPS\s0 URLs"
 802 .IX Subsection "Accessing HTTPS URLs"
 803 When you access an \s-1HTTPS\s0 \s-1URL\s0, it'll work for you just like an \s-1HTTP\s0 \s-1URL\s0
 804 would \*(-- if your \s-1LWP\s0 installation has \s-1HTTPS\s0 support (via an appropriate
 805 Secure Sockets Layer library).  For example:
 806 .PP
 807 .Vb 8
 808 \&  use LWP;
 809 \&  my $url = 'https://www.paypal.com/';   # Yes, HTTPS!
 810 \&  my $browser = LWP::UserAgent\->new;
 811 \&  my $response = $browser\->get($url);
 812 \&  die "Error at $url\en ", $response\->status_line, "\en Aborting"
 813 \&   unless $response\->is_success;
 814 \&  print "Whee, it worked!  I got that ",
 815 \&   $response\->content_type, " document!\en";
 816 .Ve
 817 .PP
 818 If your \s-1LWP\s0 installation doesn't have \s-1HTTPS\s0 support set up, then the
 819 response will be unsuccessful, and you'll get this error message:
 820 .PP
 821 .Vb 3
 822 \&  Error at https://www.paypal.com/
 823 \&   501 Protocol scheme 'https' is not supported
 824 \&   Aborting at paypal.pl line 7.   [or whatever program and line]
 825 .Ve
 826 .PP
 827 If your \s-1LWP\s0 installation \fIdoes\fR have \s-1HTTPS\s0 support installed, then the
 828 response should be successful, and you should be able to consult
 829 \&\f(CW$response\fR just like with any normal \s-1HTTP\s0 response.
 830 .PP
 831 For information about installing \s-1HTTPS\s0 support for your \s-1LWP\s0
 832 installation, see the helpful \fI\s-1README\s0.SSL\fR file that comes in the
 833 libwww-perl distribution.
 834 .Sh "Getting Large Documents"
 835 .IX Subsection "Getting Large Documents"
 836 When you're requesting a large (or at least potentially large) document,
 837 a problem with the normal way of using the request methods (like \f(CW\*(C`$response = $browser\->get($url)\*(C'\fR) is that the response object in
 838 memory will have to hold the whole document \*(-- \fIin memory\fR. If the
 839 response is a thirty megabyte file, this is likely to be quite an
 840 imposition on this process's memory usage.
 841 .PP
 842 A notable alternative is to have \s-1LWP\s0 save the content to a file on disk,
 843 instead of saving it up in memory.  This is the syntax to use:
 844 .PP
 845 .Vb 3
 846 \&  $response = $ua\->get($url,
 847 \&                         ':content_file' => $filespec,
 848 \&                      );
 849 .Ve
 850 .PP
 851 For example,
 852 .PP
 853 .Vb 3
 854 \&  $response = $ua\->get('http://search.cpan.org/',
 855 \&                         ':content_file' => '/tmp/sco.html'
 856 \&                      );
 857 .Ve
 858 .PP
 859 When you use this \f(CW\*(C`:content_file\*(C'\fR option, the \f(CW$response\fR will have
 860 all the normal header lines, but \f(CW\*(C`$response\->content\*(C'\fR will be
 861 empty.
 862 .PP
 863 Note that this \*(L":content_file\*(R" option isn't supported under older
 864 versions of \s-1LWP\s0, so you should consider adding \f(CW\*(C`use LWP 5.66;\*(C'\fR to check
 865 the \s-1LWP\s0 version, if you think your program might run on systems with
 866 older versions.
 867 .PP
 868 If you need to be compatible with older \s-1LWP\s0 versions, then use
 869 this syntax, which does the same thing:
 870 .PP
 871 .Vb 2
 872 \&  use HTTP::Request::Common;
 873 \&  $response = $ua\->request( GET($url), $filespec );
 874 .Ve
 875 .SH "SEE ALSO"
 876 .IX Header "SEE ALSO"
 877 Remember, this article is just the most rudimentary introduction to
 878 \&\s-1LWP\s0 \*(-- to learn more about \s-1LWP\s0 and LWP-related tasks, you really
 879 must read from the following:
 880 .IP "\(bu" 4
 881 LWP::Simple \*(-- simple functions for getting/heading/mirroring URLs
 882 .IP "\(bu" 4
 883 \&\s-1LWP\s0 \*(-- overview of the libwww-perl modules
 884 .IP "\(bu" 4
 885 LWP::UserAgent \*(-- the class for objects that represent \*(L"virtual browsers\*(R"
 886 .IP "\(bu" 4
 887 HTTP::Response \*(-- the class for objects that represent the response to
 888 a \s-1LWP\s0 response, as in \f(CW\*(C`$response = $browser\->get(...)\*(C'\fR
 889 .IP "\(bu" 4
 890 HTTP::Message and HTTP::Headers \*(-- classes that provide more methods
 891 to HTTP::Response.
 892 .IP "\(bu" 4
 893 \&\s-1URI\s0 \*(-- class for objects that represent absolute or relative URLs
 894 .IP "\(bu" 4
 895 URI::Escape \*(-- functions for URL-escaping and URL-unescaping strings
 896 (like turning \*(L"this & that\*(R" to and from \*(L"this%20%26%20that\*(R").
 897 .IP "\(bu" 4
 898 HTML::Entities \*(-- functions for HTML-escaping and HTML-unescaping strings
 899 (like turning "C. & E. Bronte\*:\*(L" to and from \*(R"C. &amp; E. Bront&euml;")
 900 .IP "\(bu" 4
 901 HTML::TokeParser and HTML::TreeBuilder \*(-- classes for parsing \s-1HTML\s0
 902 .IP "\(bu" 4
 903 HTML::LinkExtor \*(-- class for finding links in \s-1HTML\s0 documents
 904 .IP "\(bu" 4
 905 The book \fIPerl & \s-1LWP\s0\fR by Sean M. Burke.  O'Reilly & Associates, 2002.
 906 \&\s-1ISBN:\s0 0\-596\-00178\-9.  \f(CW\*(C`http://www.oreilly.com/catalog/perllwp/\*(C'\fR
 907 .SH "COPYRIGHT"
 908 .IX Header "COPYRIGHT"
 909 Copyright 2002, Sean M. Burke.  You can redistribute this document and/or
 910 modify it, but only under the same terms as Perl itself.
 911 .SH "AUTHOR"
 912 .IX Header "AUTHOR"
 913 Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR