home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _410f0631e330156857ee60a4e6a0a479 < prev    next >
Text File  |  2000-03-23  |  13KB  |  300 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>lwpcook - libwww-perl cookbook</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> lwpcook - libwww-perl cookbook</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  24.     <LI><A HREF="#get">GET</A></LI>
  25.     <LI><A HREF="#head">HEAD</A></LI>
  26.     <LI><A HREF="#post">POST</A></LI>
  27.     <LI><A HREF="#proxies">PROXIES</A></LI>
  28.     <LI><A HREF="#access to protected documents">ACCESS TO PROTECTED DOCUMENTS</A></LI>
  29.     <LI><A HREF="#https">HTTPS</A></LI>
  30.     <LI><A HREF="#mirroring">MIRRORING</A></LI>
  31.     <LI><A HREF="#large documents">LARGE DOCUMENTS</A></LI>
  32.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  33. </UL>
  34. <!-- INDEX END -->
  35.  
  36. <HR>
  37. <P>
  38. <H1><A NAME="name">NAME</A></H1>
  39. <P>lwpcook - libwww-perl cookbook</P>
  40. <P>
  41. <HR>
  42. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  43. <UL>
  44. <LI>Linux</LI>
  45. <LI>Solaris</LI>
  46. <LI>Windows</LI>
  47. </UL>
  48. <HR>
  49. <H1><A NAME="description">DESCRIPTION</A></H1>
  50. <P>This document contain some examples that show typical usage of the
  51. libwww-perl library.  You should consult the documentation for the
  52. individual modules for more detail.</P>
  53. <P>All examples should be runnable programs. You can, in most cases, test
  54. the code sections by piping the program text directly to perl.</P>
  55. <P>
  56. <HR>
  57. <H1><A NAME="get">GET</A></H1>
  58. <P>It is very easy to use this library to just fetch documents from the
  59. net.  The LWP::Simple module provides the <CODE>get()</CODE> function that return
  60. the document specified by its URL argument:</P>
  61. <PRE>
  62.   use LWP::Simple;
  63.   $doc = get '<A HREF="http://www.sn.no/libwww-perl/">http://www.sn.no/libwww-perl/</A>';</PRE>
  64. <P>or, as a perl one-liner using the <CODE>getprint()</CODE> function:</P>
  65. <PRE>
  66.   perl -MLWP::Simple -e 'getprint "<A HREF="http://www.sn.no/libwww-perl/"">http://www.sn.no/libwww-perl/"</A>;'</PRE>
  67. <P>or, how about fetching the latest perl by running this command:</P>
  68. <PRE>
  69.   perl -MLWP::Simple -e '
  70.     getstore "<A HREF="ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz"">ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz"</A>;,
  71.              "perl.tar.gz"'</PRE>
  72. <P>You will probably first want to find a CPAN site closer to you by
  73. running something like the following command:</P>
  74. <PRE>
  75.   perl -MLWP::Simple -e 'getprint "<A HREF="http://www.perl.com/perl/CPAN/CPAN.html"">http://www.perl.com/perl/CPAN/CPAN.html"</A>;'</PRE>
  76. <P>Enough of this simple stuff!  The LWP object oriented interface gives
  77. you more control over the request sent to the server.  Using this
  78. interface you have full control over headers sent and how you want to
  79. handle the response returned.</P>
  80. <PRE>
  81.   use LWP::UserAgent;
  82.   $ua = new LWP::UserAgent;
  83.   $ua->agent("$0/0.1 " . $ua->agent);
  84.   # $ua->agent("Mozilla/8.0") # pretend we are very capable browser</PRE>
  85. <PRE>
  86.   $req = new HTTP::Request 'GET' => '<A HREF="http://www.sn.no/libwww-perl">http://www.sn.no/libwww-perl</A>';
  87.   $req->header('Accept' => 'text/html');</PRE>
  88. <PRE>
  89.   # send request
  90.   $res = $ua->request($req);</PRE>
  91. <PRE>
  92.   # check the outcome
  93.   if ($res->is_success) {
  94.      print $res->content;
  95.   } else {
  96.      print "Error: " . $res->status_line . "\n";
  97.   }</PRE>
  98. <P>The lwp-request program (alias GET) that is distributed with the
  99. library can also be used to fetch documents from WWW servers.</P>
  100. <P>
  101. <HR>
  102. <H1><A NAME="head">HEAD</A></H1>
  103. <P>If you just want to check if a document is present (i.e. the URL is
  104. valid) try to run code that looks like this:</P>
  105. <PRE>
  106.   use LWP::Simple;</PRE>
  107. <PRE>
  108.   if (head($url)) {
  109.      # ok document exists
  110.   }</PRE>
  111. <P>The <CODE>head()</CODE> function really returns a list of meta-information about
  112. the document.  The first three values of the list returned are the
  113. document type, the size of the document, and the age of the document.</P>
  114. <P>More control over the request or access to all header values returned
  115. require that you use the object oriented interface described for GET
  116. above.  Just s/GET/HEAD/g.</P>
  117. <P>
  118. <HR>
  119. <H1><A NAME="post">POST</A></H1>
  120. <P>There is no simple procedural interface for posting data to a WWW server.  You
  121. must use the object oriented interface for this. The most common POST
  122. operation is to access a WWW form application:</P>
  123. <PRE>
  124.   use LWP::UserAgent;
  125.   $ua = new LWP::UserAgent;</PRE>
  126. <PRE>
  127.   my $req = new HTTP::Request 'POST','<A HREF="http://www.perl.com/cgi-bin/BugGlimpse">http://www.perl.com/cgi-bin/BugGlimpse</A>';
  128.   $req->content_type('application/x-www-form-urlencoded');
  129.   $req->content('match=www&errors=0');</PRE>
  130. <PRE>
  131.   my $res = $ua->request($req);
  132.   print $res->as_string;</PRE>
  133. <P>Lazy people use the HTTP::Request::Common module to set up a suitable
  134. POST request message (it handles all the escaping issues) and has a
  135. suitable default for the content_type:</P>
  136. <PRE>
  137.   use HTTP::Request::Common qw(POST);
  138.   use LWP::UserAgent;
  139.   $ua = new LWP::UserAgent;</PRE>
  140. <PRE>
  141.   my $req = POST '<A HREF="http://www.perl.com/cgi-bin/BugGlimpse">http://www.perl.com/cgi-bin/BugGlimpse</A>',
  142.                 [ search => 'www', errors => 0 ];</PRE>
  143. <PRE>
  144.   print $ua->request($req)->as_string;</PRE>
  145. <P>The lwp-request program (alias POST) that is distributed with the
  146. library can also be used for posting data.</P>
  147. <P>
  148. <HR>
  149. <H1><A NAME="proxies">PROXIES</A></H1>
  150. <P>Some sites use proxies to go through fire wall machines, or just as
  151. cache in order to improve performance.  Proxies can also be used for
  152. accessing resources through protocols not supported directly (or
  153. supported badly :-) by the libwww-perl library.</P>
  154. <P>You should initialize your proxy setting before you start sending
  155. requests:</P>
  156. <PRE>
  157.   use LWP::UserAgent;
  158.   $ua = new LWP::UserAgent;
  159.   $ua->env_proxy; # initialize from environment variables
  160.   # or
  161.   $ua->proxy(ftp  => '<A HREF="http://proxy.myorg.com">http://proxy.myorg.com</A>');
  162.   $ua->proxy(wais => '<A HREF="http://proxy.myorg.com">http://proxy.myorg.com</A>');
  163.   $ua->no_proxy(qw(no se fi));</PRE>
  164. <PRE>
  165.   my $req = HTTP::Request->new(GET => '<A HREF="wais://xxx.com/">wais://xxx.com/</A>');
  166.   print $ua->request($req)->as_string;</PRE>
  167. <P>The LWP::Simple interface will call <CODE>env_proxy()</CODE> for you automatically.
  168. Applications that use the $ua-><CODE>env_proxy()</CODE> method will normally not
  169. use the $ua-><CODE>proxy()</CODE> and $ua-><CODE>no_proxy()</CODE> methods.</P>
  170. <P>Some proxies also require that you send it a username/password in
  171. order to let requests through.  You should be able to add the
  172. required header, with something like this:</P>
  173. <PRE>
  174.  use LWP::UserAgent;</PRE>
  175. <PRE>
  176.  $ua = new LWP::UserAgent;
  177.  $ua->proxy(['http', 'ftp'] => '<A HREF="http://proxy.myorg.com">http://proxy.myorg.com</A>');</PRE>
  178. <PRE>
  179.  $req = new HTTP::Request 'GET',"<A HREF="http://www.perl.com"">http://www.perl.com"</A>;;
  180.  $req->proxy_authorization_basic("proxy_user", "proxy_password");</PRE>
  181. <PRE>
  182.  $res = $ua->request($req);
  183.  print $res->content if $res->is_success;</PRE>
  184. <P>Replace <CODE>proxy.myorg.com</CODE>, <CODE>proxy_user</CODE> and
  185. <CODE>proxy_password</CODE> with something suitable for your site.</P>
  186. <P>
  187. <HR>
  188. <H1><A NAME="access to protected documents">ACCESS TO PROTECTED DOCUMENTS</A></H1>
  189. <P>Documents protected by basic authorization can easily be accessed
  190. like this:</P>
  191. <PRE>
  192.   use LWP::UserAgent;
  193.   $ua = new LWP::UserAgent;
  194.   $req = new HTTP::Request GET => '<A HREF="http://www.sn.no/secret/">http://www.sn.no/secret/</A>';
  195.   $req->authorization_basic('aas', 'mypassword');
  196.   print $ua->request($req)->as_string;</PRE>
  197. <P>The other alternative is to provide a subclass of <EM>LWP::UserAgent</EM> that
  198. overrides the <CODE>get_basic_credentials()</CODE> method. Study the <EM>lwp-request</EM>
  199. program for an example of this.</P>
  200. <P>
  201. <HR>
  202. <H1><A NAME="https">HTTPS</A></H1>
  203. <P>URLs with https scheme are accessed in exactly the same way as with
  204. http scheme, provided that an SSL interface module for LWP has been
  205. properly installed (see the <EM>README.SSL</EM> file found in the
  206. libwww-perl distribution for more details).  If no SSL interface is
  207. installed for LWP to use, then you will get ``501 Protocol scheme
  208. 'https' is not supported'' errors when accessing such URLs.</P>
  209. <P>Here's an example of fetching and printing a WWW page using SSL:</P>
  210. <PRE>
  211.   use LWP::UserAgent;</PRE>
  212. <PRE>
  213.   my $ua = LWP::UserAgent->new;
  214.   my $req = HTTP::Request->new(GET => 'https://www.helsinki.fi/');
  215.   my $res = $ua->request($req);
  216.   if ($res->is_success) {
  217.       print $res->as_string;
  218.   } else {
  219.       print "Failed: ", $res->status_line, "\n";
  220.   }</PRE>
  221. <P>
  222. <HR>
  223. <H1><A NAME="mirroring">MIRRORING</A></H1>
  224. <P>If you want to mirror documents from a WWW server, then try to run
  225. code similar to this at regular intervals:</P>
  226. <PRE>
  227.   use LWP::Simple;</PRE>
  228. <PRE>
  229.   %mirrors = (
  230.      '<A HREF="http://www.sn.no/">http://www.sn.no/</A>'             => 'sn.html',
  231.      '<A HREF="http://www.perl.com/">http://www.perl.com/</A>'          => 'perl.html',
  232.      '<A HREF="http://www.sn.no/libwww-perl/">http://www.sn.no/libwww-perl/</A>' => 'lwp.html',
  233.      '<A HREF="gopher://gopher.sn.no/">gopher://gopher.sn.no/</A>'        => 'gopher.html',
  234.   );</PRE>
  235. <PRE>
  236.   while (($url, $localfile) = each(%mirrors)) {
  237.      mirror($url, $localfile);
  238.   }</PRE>
  239. <P>Or, as a perl one-liner:</P>
  240. <PRE>
  241.   perl -MLWP::Simple -e 'mirror("<A HREF="http://www.perl.com/"">http://www.perl.com/"</A>;, "perl.html")';</PRE>
  242. <P>The document will not be transfered unless it has been updated.</P>
  243. <P>
  244. <HR>
  245. <H1><A NAME="large documents">LARGE DOCUMENTS</A></H1>
  246. <P>If the document you want to fetch is too large to be kept in memory,
  247. then you have two alternatives.  You can instruct the library to write
  248. the document content to a file (second $ua-><CODE>request()</CODE> argument is a file
  249. name):</P>
  250. <PRE>
  251.   use LWP::UserAgent;
  252.   $ua = new LWP::UserAgent;</PRE>
  253. <PRE>
  254.   my $req = new HTTP::Request 'GET',
  255.                 '<A HREF="http://www.sn.no/~aas/perl/www/libwww-perl-5.00.tar.gz">http://www.sn.no/~aas/perl/www/libwww-perl-5.00.tar.gz</A>';
  256.   $res = $ua->request($req, "libwww-perl.tar.gz");
  257.   if ($res->is_success) {
  258.      print "ok\n";
  259.   }</PRE>
  260. <P>Or you can process the document as it arrives (second $ua-><CODE>request()</CODE>
  261. argument is a code reference):</P>
  262. <PRE>
  263.   use LWP::UserAgent;
  264.   $ua = new LWP::UserAgent;
  265.   $URL = '<A HREF="ftp://ftp.unit.no/pub/rfc/rfc-index.txt">ftp://ftp.unit.no/pub/rfc/rfc-index.txt</A>';</PRE>
  266. <PRE>
  267.   my $expected_length;
  268.   my $bytes_received = 0;
  269.   $ua->request(HTTP::Request->new('GET', $URL),
  270.                sub {
  271.                    my($chunk, $res) = @_;
  272.                    $bytes_received += length($chunk);
  273.                    unless (defined $expected_length) {
  274.                       $expected_length = $res->content_length || 0;
  275.                    }
  276.                    if ($expected_length) {
  277.                         printf STDERR "%d%% - ",
  278.                                   100 * $bytes_received / $expected_length;
  279.                    }
  280.                    print STDERR "$bytes_received bytes received\n";</PRE>
  281. <PRE>
  282.                    # XXX Should really do something with the chunk itself
  283.                    # print $chunk;
  284.                });</PRE>
  285. <P>
  286. <HR>
  287. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  288. <P>Copyright 1996-1999, Gisle Aas</P>
  289. <P>This library is free software; you can redistribute it and/or
  290. modify it under the same terms as Perl itself.</P>
  291. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  292. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  293. <STRONG><P CLASS=block> lwpcook - libwww-perl cookbook</P></STRONG>
  294. </TD></TR>
  295. </TABLE>
  296.  
  297. </BODY>
  298.  
  299. </HTML>
  300.