Mark all with_ chainable methods as deprecated.

Closes #207.

Author: ixti

CHANGES.md

@@ -1,5 +1,6 @@
 ## master (unreleased)
 
+* Deprecate chainable methods with `with_` prefix. See #207. (@ixti)
 * Add support of HTTPS connections through proxy. See #186. (@Connorhd)
 
 

README.md

@@ -170,19 +170,16 @@ the full, raw power of HTTP, we can perform content negotiation the way HTTP
 intends us to, by using the Accept header:
 
 ```ruby
-HTTP.with_headers(:accept => 'application/json').
+HTTP.headers(:accept => 'application/json').
   get('https://github.com/httprb/http.rb/commit/HEAD')
 ```
 
 This requests JSON from GitHub. GitHub is smart enough to understand our
 request and returns a response with Content-Type: application/json.
 
-Shorter aliases exists for HTTP.with_headers:
+Shorter alias exists for `HTTP.headers`:
 
 ```ruby
-HTTP.with(:accept => 'application/json').
-  get('https://github.com/httprb/http.rb/commit/HEAD')
-
 HTTP[:accept => 'application/json'].
   get('https://github.com/httprb/http.rb/commit/HEAD')
 ```
@@ -208,7 +205,7 @@ And Chain all together!
 
 ```ruby
 HTTP.basic_auth(:user => 'user', :pass => 'pass')
-  .with('Cookie' => '9wq3w')
+  .headers('Cookie' => '9wq3w')
   .get('https://example.com')
 ```
 
@@ -258,8 +255,8 @@ so.
 ```ruby
 require 'http'
 
-http = HTTP.with_cache(metastore:   "file:/var/cache/my-app-http/meta",
-                       entitystore: "file:/var/cache/my-app-http/entity")
+http = HTTP.cache(:metastore   => "file:/var/cache/my-app-http/meta",
+                  :entitystore => "file:/var/cache/my-app-http/entity")
 
 http.get("http://example.com/")   # makes request
 http.get("http://example.com/")   # skips making request and returns

lib/http/chainable.rb

@@ -140,20 +140,31 @@ def follow(opts = {})
       branch default_options.with_follow opts
     end
 
-    # @deprecated
+    # @deprecated will be removed in 1.0.0
     # @see #follow
     alias_method :with_follow, :follow
 
-    def with_cache(cache)
+    def cache(cache)
       branch default_options.with_cache(cache)
     end
 
+    # @deprecated will be removed in 1.0.0
+    # @see #cache
+    alias_method :with_cache, :cache
+
     # Make a request with the given headers
     # @param headers
-    def with_headers(headers)
+    def headers(headers)
       branch default_options.with_headers(headers)
     end
-    alias_method :with, :with_headers
+
+    # @deprecated will be removed in 1.0.0
+    # @see #headers
+    alias_method :with, :headers
+
+    # @deprecated will be removed in 1.0.0
+    # @see #headers
+    alias_method :with_headers, :headers
 
     # Accept the given MIME type(s)
     # @param type

spec/lib/http_spec.rb

@@ -190,10 +190,10 @@
     end
   end
 
-  describe ".with_cache" do
+  describe ".cache" do
     it "sets cache option" do
       cache = double(:cache, :perform => nil)
-      client = HTTP.with_cache cache
+      client = HTTP.cache cache
       expect(client.default_options[:cache]).to eq cache
     end
   end