http-cookie 1.0.0.pre12 → 1.0.4

data/lib/http/cookie/version.rb

@@ -1,5 +1,5 @@
 module HTTP
   class Cookie
-    VERSION = "1.0.0.pre12"
+    VERSION = "1.0.4"
   end
 end

data/lib/http/cookie_jar.rb

@@ -6,9 +6,6 @@ require 'http/cookie'
 # any particular website.
 
 class HTTP::CookieJar
-  require 'http/cookie_jar/abstract_store'
-  require 'http/cookie_jar/abstract_saver'
-
   class << self
     def const_missing(name)
       case name.to_s
@@ -19,7 +16,7 @@ class HTTP::CookieJar
       end
       begin
         require file
-      rescue LoadError => e
+      rescue LoadError
         raise NameError, 'can\'t resolve constant %s; failed to load %s' % [name, file]
       end
       if const_defined?(name)
@@ -32,16 +29,38 @@ class HTTP::CookieJar
 
   attr_reader :store
 
+  def get_impl(base, value, *args)
+    case value
+    when base
+      value
+    when Symbol
+      begin
+        base.implementation(value).new(*args)
+      rescue IndexError => e
+        raise ArgumentError, e.message
+      end
+    when Class
+      if base >= value
+        value.new(*args)
+      else
+        raise TypeError, 'not a subclass of %s: %s' % [base, value]
+      end
+    else
+      raise TypeError, 'invalid object: %s' % value.inspect
+    end
+  end
+  private :get_impl
+
   # Generates a new cookie jar.
   #
   # Available option keywords are as below:
   #
   # :store
   # : The store class that backs this jar. (default: `:hash`)
-  # A symbol or an instance of a store class is accepted.  Symbols are
-  # mapped to store classes, like `:hash` to
-  # HTTP::CookieJar::HashStore and `:mozilla` to
-  # HTTP::CookieJar::MozillaStore.
+  # A symbol addressing a store class, a store class, or an instance
+  # of a store class is accepted.  Symbols are mapped to store
+  # classes, like `:hash` to HTTP::CookieJar::HashStore and `:mozilla`
+  # to HTTP::CookieJar::MozillaStore.
   #
   # Any options given are passed through to the initializer of the
   # specified store class.  For example, the `:mozilla`
@@ -52,16 +71,10 @@ class HTTP::CookieJar
       :store => :hash,
     }
     opthash.update(options) if options
-    case store = opthash[:store]
-    when Symbol
-      @store = AbstractStore.implementation(store).new(opthash)
-    when AbstractStore
-      @store = store
-    else
-      raise TypeError, 'wrong object given as cookie store: %s' % store.inspect
-    end
+    @store = get_impl(AbstractStore, opthash[:store], opthash)
   end
 
+  # The copy constructor.  Not all backend store classes support cloning.
   def initialize_copy(other)
     @store = other.instance_eval { @store.dup }
   end
@@ -94,7 +107,7 @@ class HTTP::CookieJar
       begin
         cookie.acceptable?
       rescue RuntimeError => e
-          raise ArgumentError, e.message
+        raise ArgumentError, e.message
       end
     self
   end
@@ -139,7 +152,7 @@ class HTTP::CookieJar
   #
   # If (and only if) the `uri` option is given, last access time of
   # each cookie is updated to the current time.
-  def each(uri = nil, &block)
+  def each(uri = nil, &block) # :yield: cookie
     block_given? or return enum_for(__method__, uri)
 
     if uri
@@ -193,6 +206,10 @@ class HTTP::CookieJar
   #
   # * `:format`
   #
+  #     Specifies the format for saving.  A saver class, a symbol
+  #     addressing a saver class, or a pre-generated instance of a
+  #     saver class is accepted.
+  #
   #     <dl class="rdoc-list note-list">
   #       <dt>:yaml</dt>
   #       <dd>YAML structure (default)</dd>
@@ -210,7 +227,7 @@ class HTTP::CookieJar
   #     </dl>
   #
   # All options given are passed through to the underlying cookie
-  # saver module.
+  # saver module's constructor.
   def save(writable, *options)
     opthash = {
       :format => :yaml,
@@ -223,20 +240,20 @@ class HTTP::CookieJar
       when Symbol
         opthash[:format] = options
       else
-        opthash.update(options) if options
+        if hash = Hash.try_convert(options)
+          opthash.update(hash)
+        end
       end
     when 2
       opthash[:format], options = options
-      opthash.update(options) if options
+      if hash = Hash.try_convert(options)
+        opthash.update(hash)
+      end
     else
       raise ArgumentError, 'wrong number of arguments (%d for 1-3)' % (1 + options.size)
     end
 
-    begin
-      saver = AbstractSaver.implementation(opthash[:format]).new(opthash)
-    rescue IndexError => e
-      raise ArgumentError, e.message
-    end
+    saver = get_impl(AbstractSaver, opthash[:format], opthash)
 
     if writable.respond_to?(:write)
       saver.save(writable, self)
@@ -261,6 +278,10 @@ class HTTP::CookieJar
   #
   # * `:format`
   #
+  #     Specifies the format for loading.  A saver class, a symbol
+  #     addressing a saver class, or a pre-generated instance of a
+  #     saver class is accepted.
+  #
   #     <dl class="rdoc-list note-list">
   #       <dt>:yaml</dt>
   #       <dd>YAML structure (default)</dd>
@@ -269,7 +290,7 @@ class HTTP::CookieJar
   #     </dl>
   #
   # All options given are passed through to the underlying cookie
-  # saver module.
+  # saver module's constructor.
   def load(readable, *options)
     opthash = {
       :format => :yaml,
@@ -282,20 +303,20 @@ class HTTP::CookieJar
       when Symbol
         opthash[:format] = options
       else
-        opthash.update(options) if options
+        if hash = Hash.try_convert(options)
+          opthash.update(hash)
+        end
       end
     when 2
       opthash[:format], options = options
-      opthash.update(options) if options
+      if hash = Hash.try_convert(options)
+        opthash.update(hash)
+      end
     else
       raise ArgumentError, 'wrong number of arguments (%d for 1-3)' % (1 + options.size)
     end
 
-    begin
-      saver = AbstractSaver.implementation(opthash[:format]).new(opthash)
-    rescue IndexError => e
-      raise ArgumentError, e.message
-    end
+    saver = get_impl(AbstractSaver, opthash[:format], opthash)
 
     if readable.respond_to?(:write)
       saver.load(readable, self)
@@ -314,7 +335,8 @@ class HTTP::CookieJar
     self
   end
 
-  # Removes expired cookies and returns self.
+  # Removes expired cookies and returns self.  If `session` is true,
+  # all session cookies are removed as well.
   def cleanup(session = false)
     @store.cleanup session
     self

data/lib/http/cookie_jar/abstract_saver.rb

@@ -1,3 +1,6 @@
+# :markup: markdown
+
+# An abstract superclass for all saver classes.
 class HTTP::CookieJar::AbstractSaver
   class << self
     @@class_map = {}
@@ -16,20 +19,25 @@ class HTTP::CookieJar::AbstractSaver
       end
     end
 
-    def inherited(subclass)
+    def inherited(subclass) # :nodoc:
       @@class_map[class_to_symbol(subclass)] = subclass
     end
 
-    def class_to_symbol(klass)
+    def class_to_symbol(klass) # :nodoc:
       klass.name[/[^:]+?(?=Saver$|$)/].downcase.to_sym
     end
   end
 
+  # Defines options and their default values.
   def default_options
     # {}
   end
   private :default_options
 
+  # :call-seq:
+  #   new(**options)
+  #
+  # Called by the constructor of each subclass using super().
   def initialize(options = nil)
     options ||= {}
     @logger  = options[:logger]
@@ -41,10 +49,16 @@ class HTTP::CookieJar::AbstractSaver
     }
   end
 
+  # Implements HTTP::CookieJar#save().
+  #
+  # This is an abstract method that each subclass must override.
   def save(io, jar)
     # self
   end
 
+  # Implements HTTP::CookieJar#load().
+  #
+  # This is an abstract method that each subclass must override.
   def load(io, jar)
     # self
   end

data/lib/http/cookie_jar/abstract_store.rb

@@ -1,5 +1,7 @@
+# :markup: markdown
 require 'monitor'
 
+# An abstract superclass for all store classes.
 class HTTP::CookieJar::AbstractStore
   include MonitorMixin
 
@@ -15,25 +17,30 @@ class HTTP::CookieJar::AbstractStore
       begin
         require 'http/cookie_jar/%s_store' % symbol
         @@class_map.fetch(symbol)
-      rescue LoadError, IndexError
-        raise IndexError, 'cookie store unavailable: %s' % symbol.inspect
+      rescue LoadError, IndexError => e
+        raise IndexError, 'cookie store unavailable: %s, error: %s' % symbol.inspect, e.message
       end
     end
 
-    def inherited(subclass)
+    def inherited(subclass) # :nodoc:
       @@class_map[class_to_symbol(subclass)] = subclass
     end
 
-    def class_to_symbol(klass)
+    def class_to_symbol(klass) # :nodoc:
       klass.name[/[^:]+?(?=Store$|$)/].downcase.to_sym
     end
   end
 
+  # Defines options and their default values.
   def default_options
     # {}
   end
   private :default_options
 
+  # :call-seq:
+  #   new(**options)
+  #
+  # Called by the constructor of each subclass using super().
   def initialize(options = nil)
     super() # MonitorMixin
     options ||= {}
@@ -45,14 +52,21 @@ class HTTP::CookieJar::AbstractStore
     }
   end
 
+  # This is an abstract method that each subclass must override.
   def initialize_copy(other)
     # self
   end
 
+  # Implements HTTP::CookieJar#add().
+  #
+  # This is an abstract method that each subclass must override.
   def add(cookie)
     # self
   end
 
+  # Implements HTTP::CookieJar#delete().
+  #
+  # This is an abstract method that each subclass must override.
   def delete(cookie)
     # self
   end
@@ -66,7 +80,9 @@ class HTTP::CookieJar::AbstractStore
   #
   # If (and only if) the +uri+ option is given, last access time of
   # each cookie is updated to the current time.
-  def each(uri = nil, &block)
+  #
+  # This is an abstract method that each subclass must override.
+  def each(uri = nil, &block) # :yield: cookie
     # if uri
     #   ...
     # else
@@ -78,14 +94,22 @@ class HTTP::CookieJar::AbstractStore
   end
   include Enumerable
 
+  # Implements HTTP::CookieJar#empty?().
   def empty?
-    # true or false
+    each { return false }
+    true
   end
 
+  # Implements HTTP::CookieJar#clear().
+  #
+  # This is an abstract method that each subclass must override.
   def clear
     # self
   end
 
+  # Implements HTTP::CookieJar#cleanup().
+  #
+  # This is an abstract method that each subclass must override.
   def cleanup(session = false)
     # if session
     #   select { |cookie| cookie.session? || cookie.expired? }

data/lib/http/cookie_jar/cookiestxt_saver.rb

@@ -1,9 +1,25 @@
+# :markup: markdown
 require 'http/cookie_jar'
 
 # CookiestxtSaver saves and loads cookies in the cookies.txt format.
 class HTTP::CookieJar::CookiestxtSaver < HTTP::CookieJar::AbstractSaver
-  True  = "TRUE"
-  False = "FALSE"
+  # :singleton-method: new
+  # :call-seq:
+  #   new(**options)
+  #
+  # Available option keywords are below:
+  #
+  # * `:header`
+  #
+  #     Specifies the header line not including a line feed, which is
+  #     only used by #save().  None is output if nil is
+  #     given. (default: `"# HTTP Cookie File"`)
+  #
+  # * `:linefeed`
+  #
+  #     Specifies the line separator (default: `"\n"`).
+
+  ##
 
   def save(io, jar)
     io.puts @header if @header
@@ -28,8 +44,13 @@ class HTTP::CookieJar::CookiestxtSaver < HTTP::CookieJar::AbstractSaver
     }
   end
 
+  # :stopdoc:
+  True  = "TRUE"
+  False = "FALSE"
+
   HTTPONLY_PREFIX = '#HttpOnly_'
   RE_HTTPONLY_PREFIX = /\A#{HTTPONLY_PREFIX}/
+  # :startdoc:
 
   # Serializes the cookie into a cookies.txt line.
   def cookie_to_record(cookie)

data/lib/http/cookie_jar/hash_store.rb

@@ -1,13 +1,6 @@
+# :markup: markdown
 require 'http/cookie_jar'
 
-# :stopdoc:
-class Array
-  def sort_by!(&block)
-    replace(sort_by(&block))
-  end unless method_defined?(:sort_by!)
-end
-# :startdoc:
-
 class HTTP::CookieJar
   # A store class that uses a hash-based cookie store.
   #
@@ -26,6 +19,9 @@ class HTTP::CookieJar
       }
     end
 
+    # :call-seq:
+    #   new(**options)
+    #
     # Generates a hash based cookie store.
     #
     # Available option keywords are as below:
@@ -50,6 +46,7 @@ class HTTP::CookieJar
       @gc_index = 0
     end
 
+    # The copy constructor.  This store class supports cloning.
     def initialize_copy(other)
       @jar = Marshal.load(Marshal.dump(other.instance_variable_get(:@jar)))
     end
@@ -67,13 +64,11 @@ class HTTP::CookieJar
       self
     end
 
-    def each(uri = nil)
+    def each(uri = nil) # :yield: cookie
       now = Time.now
       if uri
-        thost = DomainName.new(uri.host)
         tpath = uri.path
         @jar.each { |domain, paths|
-          next unless thost.cookie_domain?(domain)
           paths.each { |path, hash|
             next unless HTTP::Cookie.path_match?(path, tpath)
             hash.delete_if { |name, cookie|
@@ -113,10 +108,6 @@ class HTTP::CookieJar
       self
     end
 
-    def empty?
-      @jar.empty?
-    end
-
     def cleanup(session = false)
       now = Time.now
       all_cookies = []