README.rdoc in rest-client-1.3.1 vs README.rdoc in rest-client-1.4.0.a

- old
+ new

@@ -47,48 +47,61 @@
   site = RestClient::Resource.new('http://example.com')
   site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'
 
 See RestClient::Resource docs for details.
 
-== Exceptions
+== Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
 
 * for results code between 200 and 206 a RestClient::Response will be returned
-* for results code between 301 and 303 the redirection will be automatically followed
-* for other result codes a RestClient::Exception holding the Response will be raised, a specific exception class will be thrown for know error codes
+* for results code 301 and 302 the redirection will be followed if the request is a get or a head
+* for result code 303 the redirection will be followed and the request transformed into a get
+* for other cases a RestClient::Exception holding the Response will be raised, a specific exception class will be thrown for know error codes
 
    RestClient.get 'http://example.com/resource'
    ➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound
 
    begin
      RestClient.get 'http://example.com/resource'
    rescue => e
      e.response
    end
-   ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+   ➔ 404 Resource Not Found | text/html 282 bytes
 
 == Result handling
 
 A block can be passed to the RestClient method, this block will then be called with the Response.
-Response.return! can be called to invoke the default response's behavior (return the Response for 200..206, raise an exception in other cases).
+Response.return! can be called to invoke the default response's behavior.
 
   # Don't raise exceptions but return the response
-  RestClient.get('http://example.com/resource'){|response| response}
-  ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+  RestClient.get('http://example.com/resource'){|response| response }
+  ➔ 404 Resource Not Found | text/html 282 bytes
 
   # Manage a specific error code
-  RestClient.get('http://my-rest-service.com/resource'){ |response|
+  RestClient.get('http://my-rest-service.com/resource'){ |response, &block|
     case response.code
     when 200
       p "It worked !"
       response
     when 423
       raise SomeCustomExceptionIfYouWant
     else
-      response.return!
+      response.return! &block
     end
   }
 
+  # Follow redirections for all request types and not only for get and head
+  # RFC : "If the 301 (or 302) status code is received in response to a request other than GET or HEAD,
+  #        the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user,
+  #        since this might change the conditions under which the request was issued."
+  RestClient.get('http://my-rest-service.com/resource'){ |response, &block|
+    if [301, 302].include? response.code
+      response.follow_redirection &block
+    else
+      response.return! &block
+    end
+  }
+
 == Non-normalized URIs.
 
 If you want to use non-normalized URIs, you can normalize them with the addressable gem (http://addressable.rubyforge.org/api/).
 
   require 'addressable/uri'
@@ -101,21 +114,21 @@
 == Shell
 
 The restclient shell command gives an IRB session with RestClient already loaded:
 
   $ restclient
-  ➔ RestClient.get 'http://example.com'
+  >> RestClient.get 'http://example.com'
 
 Specify a URL argument for get/post/put/delete on that resource:
 
   $ restclient http://example.com
-  ➔ put '/resource', 'data'
+  >> put '/resource', 'data'
 
 Add a user and password for authenticated resources:
 
   $ restclient https://example.com user pass
-  ➔ delete '/private/resource'
+  >> delete '/private/resource'
 
 Create ~/.restclient for named sessions:
 
   sinatra:
     url: http://localhost:4567
@@ -194,9 +207,25 @@
     :ssl_ca_file      =>  "ca_certificate.pem",
     :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER
   ).get
 
 Self-signed certificates can be generated with the openssl command-line tool.
+
+== Hook
+
+RestClient.add_before_execution_proc add a Proc to be called before each execution, it's handy if you need a direct access to the http request.
+
+Example:
+
+  # Add oath support using the oauth gem
+  require 'oauth'
+  access_token = ...
+
+  RestClient.add_before_execution_proc do |req, params|
+    access_token.sign! req
+  end
+
+  RestClient.get 'http://example.com'
 
 == Meta
 
 Written by Adam Wiggins, major modifications by Blake Mizerany, maintained by Julien Kirch
 