--- AnyEvent-HTTP/README	2011/01/04 08:29:28	1.15
+++ AnyEvent-HTTP/README	2011/05/10 12:33:51	1.20
@@ -14,7 +14,7 @@
 
     This module implements a simple, stateless and non-blocking HTTP client.
     It supports GET, POST and other request methods, cookies and more, all
-    on a very low level. It can follow redirects supports proxies and
+    on a very low level. It can follow redirects, supports proxies, and
     automatically limits the number of connections to the values specified
     in the RFC.
 
@@ -123,6 +123,9 @@
             if the default AnyEvent string gets blocked by webservers sooner
             or later.
 
+            Also, make sure that your headers names and values do not
+            contain any embedded newlines.
+
         timeout => $seconds
             The time-out to use for various stages - each connect attempt
             will reset the timeout, as will read or write activity, i.e.
@@ -131,12 +134,14 @@
             Default timeout is 5 minutes.
 
         proxy => [$host, $port[, $scheme]] or undef
-            Use the given http proxy for all requests. If not specified,
-            then the default proxy (as specified by $ENV{http_proxy}) is
-            used.
+            Use the given http proxy for all requests, or no proxy if
+            "undef" is used.
 
             $scheme must be either missing or must be "http" for HTTP.
 
+            If not specified, then the default proxy is used (see
+            "AnyEvent::HTTP::set_proxy").
+
         body => $string
             The request body, usually empty. Will be sent as-is (future
             versions of this module might offer more options).
@@ -368,6 +373,10 @@
 
         To clear an already-set proxy, use "undef".
 
+        When AnyEvent::HTTP is laoded for the first time it will query the
+        default proxy from the operating system, currently by looking at
+        "$ENV{http_proxy"}.
+
     AnyEvent::HTTP::cookie_jar_expire $jar[, $session_end]
         Remove all cookies from the cookie jar that have been expired. If
         $session_end is given and true, then additionally remove all session
@@ -453,7 +462,107 @@
         non-idle TCP connections. This number can be useful for
         load-leveling.
 
-  SOCKS PROXIES
+  SHOWCASE
+    This section contaisn some more elaborate "real-world" examples or code
+    snippets.
+
+  HTTP/1.1 FILE DOWNLOAD
+    Downloading files with HTTP can be quite tricky, especially when
+    something goes wrong and you want to resume.
+
+    Here is a function that initiates and resumes a download. It uses the
+    last modified time to check for file content changes, and works with
+    many HTTP/1.0 servers as well, and usually falls back to a complete
+    re-download on older servers.
+
+    It calls the completion callback with either "undef", which means a
+    nonretryable error occured, 0 when the download was partial and should
+    be retried, and 1 if it was successful.
+
+       use AnyEvent::HTTP;
+
+       sub download($$$) {
+          my ($url, $file, $cb) = @_;
+
+          open my $fh, "+<", $file
+             or die "$file: $!";
+
+          my %hdr;
+          my $ofs = 0;
+
+          warn stat $fh;
+          warn -s _;
+          if (stat $fh and -s _) {
+             $ofs = -s _;
+             warn "-s is ", $ofs;#d#
+             $hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9];
+             $hdr{"range"} = "bytes=$ofs-";
+          }
+
+          http_get $url,
+             headers   => \%hdr,
+             on_header => sub {
+                my ($hdr) = @_;
+
+                if ($hdr->{Status} == 200 && $ofs) {
+                   # resume failed
+                   truncate $fh, $ofs = 0;
+                }
+
+                sysseek $fh, $ofs, 0;
+
+                1
+             },
+             on_body   => sub {
+                my ($data, $hdr) = @_;
+
+                if ($hdr->{Status} =~ /^2/) {
+                   length $data == syswrite $fh, $data
+                      or return; # abort on write errors
+                }
+
+                1
+             },
+             sub {
+                my (undef, $hdr) = @_;
+
+                my $status = $hdr->{Status};
+
+                if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) {
+                   utime $fh, $time, $time;
+                }
+
+                if ($status == 200 || $status == 206 || $status == 416) {
+                   # download ok || resume ok || file already fully downloaded
+                   $cb->(1, $hdr);
+
+                } elsif ($status == 412) {
+                   # file has changed while resuming, delete and retry
+                   unlink $file;
+                   $cb->(0, $hdr);
+
+                } elsif ($status == 500 or $status == 503 or $status =~ /^59/) {
+                   # retry later
+                   $cb->(0, $hdr);
+
+                } else {
+                   $cb->(undef, $hdr);
+                }
+             }
+          ;
+       }
+
+       download "http://server/somelargefile", "/tmp/somelargefile", sub {
+          if ($_[0]) {
+             print "OK!\n";
+          } elsif (defined $_[0]) {
+             print "please retry later\n";
+          } else {
+             print "ERROR\n";
+          }
+       };
+
+   SOCKS PROXIES
     Socks proxies are not directly supported by AnyEvent::HTTP. You can
     compile your perl to support socks, or use an external program such as
     socksify (dante) or tsocks to make your program use a socks proxy