From 0d5e6666425537689963fffb464a2dd5d5a5e69e Mon Sep 17 00:00:00 2001 From: Akinori MUSHA Date: Tue, 16 Apr 2013 22:37:19 +0900 Subject: [PATCH] Improve rdoc. --- lib/http/cookie.rb | 18 +++++++-------- lib/http/cookie_jar.rb | 10 +++++---- lib/http/cookie_jar/abstract_saver.rb | 18 +++++++++++++-- lib/http/cookie_jar/abstract_store.rb | 29 ++++++++++++++++++++++--- lib/http/cookie_jar/cookiestxt_saver.rb | 25 +++++++++++++++++++-- lib/http/cookie_jar/hash_store.rb | 7 +++++- lib/http/cookie_jar/mozilla_store.rb | 8 +++++-- lib/http/cookie_jar/yaml_saver.rb | 13 ++++++++++- 8 files changed, 104 insertions(+), 24 deletions(-) diff --git a/lib/http/cookie.rb b/lib/http/cookie.rb index 5916a7f..0bb3ac8 100644 --- a/lib/http/cookie.rb +++ b/lib/http/cookie.rb @@ -87,7 +87,7 @@ class HTTP::Cookie # The Expires attribute value as a Time object. # # The setter method accepts a Time object, a string representation - # of date/time, or `nil`. + # of date/time that Time.parse can understand, or `nil`. # # Setting this value resets #max_age to nil. When #max_age is # non-nil, #expires returns `created_at + max_age`. @@ -340,7 +340,7 @@ class HTTP::Cookie attr_reader :name # See #name. - def name=(name) + def name= name name = (String.try_convert(name) or raise TypeError, "#{name.class} is not a String") if name.empty? @@ -357,7 +357,7 @@ class HTTP::Cookie attr_reader :value # See #value. - def value=(value) + def value= value if value.nil? self.expires = UNIX_EPOCH return @value = '' @@ -376,7 +376,7 @@ class HTTP::Cookie attr_reader :domain # See #domain. - def domain=(domain) + def domain= domain case domain when nil @for_domain = false @@ -434,7 +434,7 @@ class HTTP::Cookie attr_reader :path # See #path. - def path=(path) + def path= path path = (String.try_convert(path) or raise TypeError, "#{path.class} is not a String") @path = path.start_with?('/') ? path : '/' @@ -443,7 +443,7 @@ class HTTP::Cookie attr_reader :origin # See #origin. - def origin=(origin) + def origin= origin return origin if origin == @origin @origin.nil? or raise ArgumentError, "origin cannot be changed once it is set" @@ -479,7 +479,7 @@ class HTTP::Cookie end # See #expires. - def expires=(t) + def expires= t case t when nil, Time else @@ -496,7 +496,7 @@ class HTTP::Cookie attr_reader :max_age # See #max_age. - def max_age=(sec) + def max_age= sec @expires = nil case sec when Integer, nil @@ -632,7 +632,7 @@ class HTTP::Cookie # Compares the cookie with another. When there are many cookies with # the same name for a URL, the value of the smallest must be used. - def <=>(other) + def <=> other # RFC 6265 5.4 # Precedence: 1. longer path 2. older creation (@name <=> other.name).nonzero? || diff --git a/lib/http/cookie_jar.rb b/lib/http/cookie_jar.rb index a944c25..9e0851f 100644 --- a/lib/http/cookie_jar.rb +++ b/lib/http/cookie_jar.rb @@ -59,6 +59,7 @@ class HTTP::CookieJar end end + # The copy constructor. Not all backend store classes support cloning. def initialize_copy(other) @store = other.instance_eval { @store.dup } end @@ -136,7 +137,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 @@ -207,7 +208,7 @@ class HTTP::CookieJar # # # All options given are passed through to the underlying cookie - # saver module. + # saver module's constructor. def save(writable, *options) opthash = { :format => :yaml, @@ -266,7 +267,7 @@ class HTTP::CookieJar # # # All options given are passed through to the underlying cookie - # saver module. + # saver module's constructor. def load(readable, *options) opthash = { :format => :yaml, @@ -311,7 +312,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 diff --git a/lib/http/cookie_jar/abstract_saver.rb b/lib/http/cookie_jar/abstract_saver.rb index 2508995..9d82873 100644 --- a/lib/http/cookie_jar/abstract_saver.rb +++ b/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 diff --git a/lib/http/cookie_jar/abstract_store.rb b/lib/http/cookie_jar/abstract_store.rb index d24cdfe..35d0b94 100644 --- a/lib/http/cookie_jar/abstract_store.rb +++ b/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 @@ -20,20 +22,25 @@ class HTTP::CookieJar::AbstractStore 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,15 +94,22 @@ class HTTP::CookieJar::AbstractStore end include Enumerable + # Implements HTTP::CookieJar#empty?(). def empty? 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? } diff --git a/lib/http/cookie_jar/cookiestxt_saver.rb b/lib/http/cookie_jar/cookiestxt_saver.rb index aba0123..df0ca01 100644 --- a/lib/http/cookie_jar/cookiestxt_saver.rb +++ b/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) diff --git a/lib/http/cookie_jar/hash_store.rb b/lib/http/cookie_jar/hash_store.rb index 2909eb3..08e4a18 100644 --- a/lib/http/cookie_jar/hash_store.rb +++ b/lib/http/cookie_jar/hash_store.rb @@ -1,3 +1,4 @@ +# :markup: markdown require 'http/cookie_jar' class HTTP::CookieJar @@ -18,6 +19,9 @@ class HTTP::CookieJar } end + # :call-seq: + # new(**options) + # # Generates a hash based cookie store. # # Available option keywords are as below: @@ -42,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 @@ -59,7 +64,7 @@ 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) diff --git a/lib/http/cookie_jar/mozilla_store.rb b/lib/http/cookie_jar/mozilla_store.rb index feb5ca4..090eeae 100644 --- a/lib/http/cookie_jar/mozilla_store.rb +++ b/lib/http/cookie_jar/mozilla_store.rb @@ -68,6 +68,9 @@ class HTTP::CookieJar end # :startdoc: + # :call-seq: + # new(**options) + # # Generates a Mozilla cookie store. If the file does not exist, # it is created. If it does and its schema is old, it is # automatically upgraded with a new schema keeping the existing @@ -109,6 +112,7 @@ class HTTP::CookieJar @gc_index = 0 end + # Raises TypeError. Cloning is inhibited in this store class. def initialize_copy(other) raise TypeError, 'can\'t clone %s' % self.class end @@ -138,7 +142,7 @@ class HTTP::CookieJar protected - def schema_version=(version) + def schema_version= version @db.execute("PRAGMA user_version = %d" % version) @schema_version = version end @@ -329,7 +333,7 @@ class HTTP::CookieJar expiry >= :expiry SQL - def each(uri = nil, &block) + def each(uri = nil, &block) # :yield: cookie now = Time.now if uri thost = DomainName.new(uri.host) diff --git a/lib/http/cookie_jar/yaml_saver.rb b/lib/http/cookie_jar/yaml_saver.rb index 490d6b4..7062f43 100644 --- a/lib/http/cookie_jar/yaml_saver.rb +++ b/lib/http/cookie_jar/yaml_saver.rb @@ -1,9 +1,20 @@ +# :markup: markdown require 'http/cookie_jar' require 'psych' if !defined?(YAML) && RUBY_VERSION == "1.9.2" require 'yaml' -# YAMLSaver saves and loads cookies in the YAML format. +# YAMLSaver saves and loads cookies in the YAML format. It can load a +# YAML file saved by Mechanize, but the saving format is not +# compatible with older versions of Mechanize (< 2.7). class HTTP::CookieJar::YAMLSaver < HTTP::CookieJar::AbstractSaver + # :singleton-method: new + # :call-seq: + # new(**options) + # + # There is no option keyword supported at the moment. + + ## + def save(io, jar) YAML.dump(@session ? jar.to_a : jar.reject(&:session?), io) end