Add error messages to make migration from Mechanize::Cookie easier.

Add a section to elaborate on the incompatibilities to README.md.

README.md

@@ -59,9 +59,68 @@ Or install it yourself as:
     set_cookie_header_value = cookies.set_cookie_value(my_url)
 
 
-## To-Do list
+## Incompatibilities with Mechanize::Cookie and CookieJar
 
-- Print kind error messages to make migration from Mechanize::Cookie easier
+There are several incompatibilities with Mechanize::Cookie and
+CookieJar.  Below is how to rewrite existing code written for
+Mechanize::Cookie with equivalent using HTTP::Cookie:
+
+- Mechanize::Cookie.parse
+
+    # before
+    cookie1 = Mechanize::Cookie.parse(uri, set_cookie1)
+    cookie2 = Mechanize::Cookie.parse(uri, set_cookie2, log)
+
+    # after
+    cookie1 = HTTP::Cookie.parse(set_cookie1, :origin => uri)
+    cookie2 = HTTP::Cookie.parse(set_cookie2, :origin => uri, :logger => log)
+
+- Mechanize::Cookie#set_domain
+
+    # before
+    cookie.set_domain(domain)
+
+    # after
+    cookie.domain = domain
+
+- Mechanize::CookieJar#add, #add!
+
+    # before
+    jar.add!(cookie1)
+    jar.add(uri, cookie2)
+
+    # after
+    jar.add(cookie1)
+    cookie2.origin = uri; jar.add(cookie2)  # or specify origin in parse() or new()
+
+- Mechanize::CookieJar#clear!
+
+    # before
+    jar.clear!
+
+    # after
+    jar.clear
+
+- Mechanize::CookieJar#save_as
+
+    # before
+    jar.save_as(file)
+
+    # after
+    jar.save(file)
+
+HTTP::Cookie and CookieJar raises runtime errors to help migration, so
+try running your test code once to find out how to fix your code base.
+
+The YAML serialization format has changed.  Loading YAML files
+generated by Mechanize::CookieJar#save_as will not raise an exception,
+but the content is simply ignored.  Note that there is (obviously) no
+forward compatibillity in the YAML serialization.  Trying to load a
+YAML file saved by HTTP::CookieJar with Mechanize::CookieJar will fail
+in ArgumentError.
+
+On the other hand, there has been (and will ever be) no change in the
+cookies.txt format.
 
 ## Contributing
 

lib/http/cookie.rb

@@ -163,7 +163,10 @@ class HTTP::Cookie
     #   instead of the current time
     # * +logger+
     #   Logger object useful for debugging
-    def parse(set_cookie, options = nil, &block)
+    def parse(set_cookie, options = nil, *_, &block)
+      _.empty? && !options.is_a?(String) or
+        raise ArgumentError, 'HTTP::Cookie equivalent for Mechanize::Cookie.parse(uri, set_cookie[, log]) is HTTP::Cookie.parse(set_cookie, :origin => uri[, :logger => log]).'
+
       if options
         logger = options[:logger]
         origin = options[:origin] and origin = URI(origin)
@@ -294,6 +297,11 @@ class HTTP::Cookie
     @domain = @domain_name.hostname
   end
 
+  # Used to exist in Mechanize::CookieJar.  Use #domain=().
+  def set_domain(domain)
+    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#set_domain() is #domain=().'
+  end
+
   def path=(path)
     @path = HTTP::Cookie.normalize_path(path)
   end

lib/http/cookie_jar.rb

@@ -28,7 +28,10 @@ class HTTP::CookieJar
   end
 
   # Add a +cookie+ to the jar and return self.
-  def add(cookie)
+  def add(cookie, *_)
+    _.empty? or
+      raise ArgumentError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add(uri, cookie) is #add(cookie) after setting cookie.origin = uri.'
+
     if cookie.domain.nil? || cookie.path.nil?
       raise ArgumentError, "a cookie with unknown domain or path cannot be added"
     end
@@ -38,6 +41,11 @@ class HTTP::CookieJar
   end
   alias << add
 
+  # Used to exist in Mechanize::CookieJar.  Use #add().
+  def add!(cookie)
+    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add!() is #add().'
+  end
+
   # Fetch the cookies that should be used for the URL/URI.
   def cookies(url)
     now = Time.now
@@ -145,10 +153,9 @@ class HTTP::CookieJar
     self
   end
 
-  # An obsolete name for save().
+  # Used to exist in Mechanize::CookieJar.  Use #save().
   def save_as(*args)
-    warn "%s() is obsolete; use save()." % __method__
-    save(*args)
+    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#save_as() is #save().'
   end
 
   # call-seq:
@@ -213,6 +220,11 @@ class HTTP::CookieJar
     self
   end
 
+  # Used to exist in Mechanize::CookieJar.  Use #clear().
+  def clear!(*args)
+    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#clear!() is #clear().'
+  end
+
   # Remove expired cookies and return self.
   def cleanup(session = false)
     @store.cleanup session

test/helper.rb

@@ -19,3 +19,15 @@ module Enumerable
     result
   end
 end
+
+module Test::Unit::Assertions
+  def assert_raises_with_message(exc, re, message = nil, &block)
+    e = nil
+    begin
+      block.call
+    rescue Exception => e
+    end
+    assert_instance_of(exc, e, message)
+    assert_match(re, e.message, message)
+  end
+end

test/test_http_cookie.rb

@@ -606,5 +606,19 @@ class TestHTTPCookie < Test::Unit::TestCase
     cookie = HTTP::Cookie.parse('a=b', :origin => URI('https://example.com/')).first
     assert_equal true,  cookie.valid_for_uri?(URI('https://example.com'))
   end
+
+  def test_migration
+    assert_raises_with_message(ArgumentError, /equivalent/) {
+      HTTP::Cookie.parse('http://example.com/', 'key=value')
+    }
+    assert_raises_with_message(ArgumentError, /equivalent/) {
+      HTTP::Cookie.parse('http://example.com/', 'key=value', Object.new)
+    }
+
+    cookie = HTTP::Cookie.new('key', 'value')
+    assert_raises_with_message(NoMethodError, /equivalent/) {
+      cookie.set_domain('www.example.com')
+    }
+  end
 end
 

test/test_http_cookie_jar.rb

@@ -566,4 +566,20 @@ class TestHTTPCookieJar < Test::Unit::TestCase
       cookie.domain == cookie.value
     }
   end
+
+  def test_migration
+    cookie = HTTP::Cookie.new(cookie_values)
+    assert_raises_with_message(ArgumentError, /equivalent/) {
+      @jar.add('http://example.com/', cookie)
+    }
+    assert_raises_with_message(NoMethodError, /equivalent/) {
+      @jar.add!(cookie)
+    }
+    assert_raises_with_message(NoMethodError, /equivalent/) {
+      @jar.clear!()
+    }
+    assert_raises_with_message(NoMethodError, /equivalent/) {
+      @jar.save_as('/dev/null')
+    }
+  end
 end