http-cookie 0.1.2 → 0.1.4

data/README.md

@@ -70,12 +70,12 @@ equivalent using `HTTP::Cookie`:
 - `Mechanize::Cookie.parse`
 
         # before
-        cookie1 = Mechanize::Cookie.parse(uri, set_cookie1)
-        cookie2 = Mechanize::Cookie.parse(uri, set_cookie2, log)
+        cookies1 = Mechanize::Cookie.parse(uri, set_cookie1)
+        cookies2 = 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)
+        cookies1 = HTTP::Cookie.parse(set_cookie1, :origin => uri)
+        cookies2 = HTTP::Cookie.parse(set_cookie2, :origin => uri, :logger => log)
 
 - `Mechanize::Cookie#set_domain`
 

data/lib/http/cookie/version.rb

@@ -1,5 +1,5 @@
 module HTTP
   class Cookie
-    VERSION = "0.1.2"
+    VERSION = "0.1.4"
   end
 end

data/lib/http/cookie.rb

@@ -72,6 +72,10 @@ class HTTP::Cookie
   # is called if defined.  Each key can be either a symbol or a
   # string, downcased or not.
   #
+  # This methods accepts any attribute name for which a setter method
+  # is defined.  Beware, however, any error (typically ArgumentError)
+  # a setter method raises will be passed through.
+  #
   # e.g.
   #     new("uid", "a12345")
   #     new("uid", "a12345", :domain => 'example.org',
@@ -149,7 +153,9 @@ class HTTP::Cookie
 
     # Parses a Set-Cookie header value +set_cookie+ into an array of
     # Cookie objects.  Parts (separated by commas) that are malformed
-    # are ignored.
+    # or invalid are silently ignored.  For example, a cookie that a
+    # given origin is not allowed to issue is not included in the
+    # resulted array.
     #
     # If a block is given, each cookie object is passed to the block.
     #
@@ -301,10 +307,13 @@ class HTTP::Cookie
     raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#set_domain() is #domain=().'
   end
 
+  # Sets the path attribute.
   def path=(path)
     @path = HTTP::Cookie.normalize_path(path)
   end
 
+  # Sets the origin of the cookie.  This initializes the `domain` and
+  # `path` attribute values if unknown yet.
   def origin=(origin)
     @origin.nil? or
       raise ArgumentError, "origin cannot be changed once it is set"
@@ -316,6 +325,8 @@ class HTTP::Cookie
     @origin = origin
   end
 
+  # Sets the expires attribute.  A `Time` object, a string
+  # representation of date/time, and `nil` are good values to set.
   def expires=(t)
     case t
     when nil, Time
@@ -325,11 +336,14 @@ class HTTP::Cookie
     end
   end
 
+  # Tests if this cookie is expired by now, or by a given time.
   def expired?(time = Time.now)
     return false unless @expires
     time > @expires
   end
 
+  # Expires this cookie by setting the expires attribute value to a
+  # past date.
   def expire
     @expires = UNIX_EPOCH
     self
@@ -339,6 +353,8 @@ class HTTP::Cookie
   alias httponly? httponly
   alias session? session
 
+  # Tests if it is OK to accept this cookie if it is sent from a given
+  # +uri.
   def acceptable_from_uri?(uri)
     uri = URI(uri)
     return false unless URI::HTTP === uri && uri.host
@@ -358,6 +374,8 @@ class HTTP::Cookie
     end
   end
 
+  # Tests if it is OK to send this cookie to a given +uri+, A runtime
+  # error is raised if the cookie's domain is unknown.
   def valid_for_uri?(uri)
     if @domain.nil?
       raise "cannot tell if this cookie is valid because the domain is unknown"
@@ -391,16 +409,16 @@ class HTTP::Cookie
     if (HTTP::Cookie.normalize_path(origin) + './').path != @path
       string << "; path=#{@path}"
     end
-    if expires = @expires
+    if @expires
       string << "; expires=#{@expires.httpdate}"
     end
-    if comment = @comment
+    if @comment
       string << "; comment=#{@comment}"
     end
-    if httponly?
+    if @httponly
       string << "; HttpOnly"
     end
-    if secure?
+    if @secure
       string << "; secure"
     end
     string

data/lib/http/cookie_jar/abstract_saver.rb

@@ -1,5 +1,3 @@
-require 'http/cookie_jar'
-
 class HTTP::CookieJar::AbstractSaver
   class << self
     @@class_map = {}
@@ -13,7 +11,7 @@ class HTTP::CookieJar::AbstractSaver
       begin
         require 'http/cookie_jar/%s_saver' % symbol
         @@class_map.fetch(symbol)
-      rescue LoadError, IndexError => e
+      rescue LoadError, IndexError
         raise IndexError, 'cookie saver unavailable: %s' % symbol.inspect
       end
     end

data/lib/http/cookie_jar/abstract_store.rb

@@ -1,5 +1,3 @@
-require 'http/cookie_jar'
-
 class HTTP::CookieJar::AbstractStore
   class << self
     @@class_map = {}
@@ -13,7 +11,7 @@ class HTTP::CookieJar::AbstractStore
       begin
         require 'http/cookie_jar/%s_store' % symbol
         @@class_map.fetch(symbol)
-      rescue LoadError, IndexError => e
+      rescue LoadError, IndexError
         raise IndexError, 'cookie store unavailable: %s' % symbol.inspect
       end
     end

data/lib/http/cookie_jar/yaml_saver.rb

@@ -1,8 +1,5 @@
 require 'http/cookie_jar'
-begin
-  require 'psych'
-rescue LoadError
-end
+require 'psych' if !defined?(YAML) && RUBY_VERSION == "1.9.2"
 require 'yaml'
 
 # YAMLSaver saves and loads cookies in the YAML format.

data/lib/http/cookie_jar.rb

@@ -10,6 +10,9 @@ class HTTP::CookieJar
 
   attr_reader :store
 
+  # Generates a new cookie jar.  The default store class is `:hash`,
+  # which maps to `HTTP::CookieJar::HashStore`.  Any given options are
+  # passed through to the initializer of the specified store class.
   def initialize(store = :hash, options = nil)
     case store
     when Symbol
@@ -27,7 +30,9 @@ class HTTP::CookieJar
     @store = other.instance_eval { @store.dup }
   end
 
-  # Add a +cookie+ to the jar and return self.
+  # Adds a +cookie+ to the jar and return self.  If a given cookie has
+  # no domain or path attribute values and the origin is unknown,
+  # ArgumentError is raised.
   def add(cookie, *_)
     _.empty? or
       raise ArgumentError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add(uri, cookie) is #add(cookie) after setting cookie.origin = uri.'
@@ -46,7 +51,7 @@ class HTTP::CookieJar
     raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add!() is #add().'
   end
 
-  # Fetch the cookies that should be used for the URL/URI.
+  # Gets an array of cookies that should be sent for the URL/URI.
   def cookies(url)
     now = Time.now
     each(url).select { |cookie|
@@ -54,8 +59,8 @@ class HTTP::CookieJar
     }.sort
   end
 
-  # Tests if the jar is empty.  If url is given, tests if there is no
-  # cookie for the URL.
+  # Tests if the jar is empty.  If +url+ is given, tests if there is
+  # no cookie for the URL.
   def empty?(url = nil)
     if url
       each(url) { return false }
@@ -94,9 +99,9 @@ class HTTP::CookieJar
   #   jar.save(filename_or_io, **options)
   #   jar.save(filename_or_io, format = :yaml, **options)
   #
-  # Save the cookie jar into a file or an IO in the format specified
-  # and return self.  If the given object responds to #write it is
-  # taken as an IO, or taken as a filename otherwise.
+  # Saves the cookie jar into a file or an IO in the format specified
+  # and return self.  If a given object responds to #write it is taken
+  # as an IO, or taken as a filename otherwise.
   #
   # Available option keywords are below:
   #
@@ -160,9 +165,9 @@ class HTTP::CookieJar
   #   jar.load(filename_or_io, **options)
   #   jar.load(filename_or_io, format = :yaml, **options)
   #
-  # Load cookies recorded in a file or an IO in the format specified
-  # into the jar and return self.  If the given object responds to
-  # #read it is taken as an IO, or taken as a filename otherwise.
+  # Loads cookies recorded in a file or an IO in the format specified
+  # into the jar and return self.  If a given object responds to #read
+  # it is taken as an IO, or taken as a filename otherwise.
   #
   # Available option keywords are below:
   #
@@ -212,7 +217,7 @@ class HTTP::CookieJar
     self
   end
 
-  # Clear the cookie jar and return self.
+  # Clears the cookie jar and return self.
   def clear
     @store.clear
     self
@@ -223,7 +228,7 @@ class HTTP::CookieJar
     raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#clear!() is #clear().'
   end
 
-  # Remove expired cookies and return self.
+  # Removes expired cookies and return self.
   def cleanup(session = false)
     @store.cleanup session
     self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http-cookie
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors: