Class: HTTP::CookieJar

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/http/cookie_jar/hash_store.rb,
lib/http/cookie_jar/mozilla_store.rb,
lib/http/cookie_jar.rb

Overview

This class is used to manage the Cookies that have been returned from any particular website.

Defined Under Namespace

Classes: AbstractSaver, AbstractStore, CookiestxtSaver, HashStore, MozillaStore, YAMLSaver

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = nil) ⇒ CookieJar

Generates a new cookie jar.

Available option keywords are as below:

:store : The store class that backs this jar. (default: ‘:hash`) 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` (HTTP::CookieJar::MozillaStore) store class requires a `:filename` option. See individual store classes for details.



50
51
52
53
54
55
56
 
# File 'lib/http/cookie_jar.rb', line 50

def initialize(options = nil)
  opthash = {
    :store => :hash,
  }
  opthash.update(options) if options
  @store = get_impl(AbstractStore, opthash[:store], opthash)
end

Instance Attribute Details

#store ⇒ Object (readonly)

Returns the value of attribute store.



11
12
13
 
# File 'lib/http/cookie_jar.rb', line 11

def store
  @store
end

Instance Method Details

#add(cookie) ⇒ Object Also known as: <<

Adds a cookie to the jar if it is acceptable, and returns self in any case. A given cookie must have domain and path attributes set, or ArgumentError is raised.

Whether a cookie with the ‘for_domain` flag on overwrites another with the flag off or vice versa depends on the store used. See individual store classes for that matter.

### Compatibility Note for Mechanize::Cookie users

In HTTP::Cookie, each cookie object can store its origin URI (cf. #origin). While the origin URI of a cookie can be set manually by #origin=, one is typically given in its generation. To be more specific, HTTP::Cookie.new takes an ‘:origin` option and HTTP::Cookie.parse takes one via the second argument.

# Mechanize::Cookie
jar.add(origin, cookie)
jar.add!(cookie)    # no acceptance check is performed

# HTTP::Cookie
jar.origin = origin
jar.add(cookie)     # acceptance check is performed



86
87
88
89
90
91
92
93
94
 
# File 'lib/http/cookie_jar.rb', line 86

def add(cookie)
  @store.add(cookie) if
    begin
      cookie.acceptable?
    rescue RuntimeError => e
      raise ArgumentError, e.message
    end
  self
end

#cleanup(session = false) ⇒ Object

Removes expired cookies and returns self. If ‘session` is true, all session cookies are removed as well.



321
322
323
324
 
# File 'lib/http/cookie_jar.rb', line 321

def cleanup(session = false)
  @store.cleanup session
  self
end

#clear ⇒ Object

Clears the cookie jar and returns self.



314
315
316
317
 
# File 'lib/http/cookie_jar.rb', line 314

def clear
  @store.clear
  self
end

#cookies(url = nil) ⇒ Object

Gets an array of cookies sorted by the path and creation time. If ‘url` is given, only ones that should be sent to the URL/URI are selected, with the access time of each of them updated.



111
112
113
 
# File 'lib/http/cookie_jar.rb', line 111

def cookies(url = nil)
  each(url).sort
end

#delete(cookie) ⇒ Object

Deletes a cookie that has the same name, domain and path as a given cookie from the jar and returns self.

How the ‘for_domain` flag value affects the set of deleted cookies depends on the store used. See individual store classes for that matter.



103
104
105
106
 
# File 'lib/http/cookie_jar.rb', line 103

def delete(cookie)
  @store.delete(cookie)
  self
end

#each(uri = nil, &block) ⇒ Object

Iterates over all cookies that are not expired in no particular order.

An optional argument ‘uri` specifies a URI/URL indicating the destination of the cookies being selected. Every cookie yielded should be good to send to the given URI, i.e. cookie.valid_for_uri?(uri) evaluates to true.

If (and only if) the ‘uri` option is given, last access time of each cookie is updated to the current time.



136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/http/cookie_jar.rb', line 136

def each(uri = nil, &block) # :yield: cookie
  block_given? or return enum_for(__method__, uri)

  if uri
    uri = HTTP::Cookie::URIParser.parse(uri)
    return self unless URI::HTTP === uri && uri.host
  end

  @store.each(uri, &block)
  self
end

#empty?(url = nil) ⇒ Boolean

Tests if the jar is empty. If ‘url` is given, tests if there is no cookie for the URL.

Returns:

  • (Boolean) 


117
118
119
120
121
122
123
124
 
# File 'lib/http/cookie_jar.rb', line 117

def empty?(url = nil)
  if url
    each(url) { return false }
    return true
  else
    @store.empty?
  end
end

#initialize_copy(other) ⇒ Object

The copy constructor. Not all backend store classes support cloning.



59
60
61
 
# File 'lib/http/cookie_jar.rb', line 59

def initialize_copy(other)
  @store = other.instance_eval { @store.dup }
end

#load(readable, *options) ⇒ Object

call-seq:

jar.load(filename_or_io, **options)
jar.load(filename_or_io, format = :yaml, **options)

Loads cookies recorded in a file or an IO in the format specified into the jar and returns 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:

  • ‘: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>
  <dt>:cookiestxt</dt>
  <dd>Mozilla's cookies.txt format</dd>
</dl>

All options given are passed through to the underlying cookie saver module’s constructor.



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/http/cookie_jar.rb', line 275

def load(readable, *options)
  opthash = {
    :format => :yaml,
    :session => false,
  }
  case options.size
  when 0
  when 1
    case options = options.first
    when Symbol
      opthash[:format] = options
    else
      if hash = Hash.try_convert(options)
        opthash.update(hash)
      end
    end
  when 2
    opthash[:format], options = 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

  saver = get_impl(AbstractSaver, opthash[:format], opthash)

  if readable.respond_to?(:write)
    saver.load(readable, self)
  else
    File.open(readable, 'r') { |io|
      saver.load(io, self)
    }
  end

  self
end

#parse(set_cookie, origin, options = nil) ⇒ Object

Parses a Set-Cookie field value ‘set_cookie` assuming that it is sent from a source URL/URI `origin`, and adds the cookies parsed as valid and considered acceptable to the jar. Returns an array of cookies that have been added.

If a block is given, it is called for each cookie and the cookie is added only if the block returns a true value.

‘jar.parse(set_cookie, origin)` is a shorthand for this:

HTTP::Cookie.parse(set_cookie, origin) { |cookie|
  jar.add(cookie)
}

See HTTP::Cookie.parse for available options.



164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/http/cookie_jar.rb', line 164

def parse(set_cookie, origin, options = nil) # :yield: cookie
  if block_given?
    HTTP::Cookie.parse(set_cookie, origin, options).tap { |cookies|
      cookies.select! { |cookie|
        yield(cookie) && add(cookie)
      }
    }
  else
    HTTP::Cookie.parse(set_cookie, origin, options) { |cookie|
      add(cookie)
    }
  end
end

#save(writable, *options) ⇒ Object

call-seq:

jar.save(filename_or_io, **options)
jar.save(filename_or_io, format = :yaml, **options)

Saves the cookie jar into a file or an IO in the format specified and returns 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:

  • ‘: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>
  <dt>:cookiestxt</dt>
  <dd>Mozilla's cookies.txt format</dd>
</dl>

  • ‘:session`

    <dl class="rdoc-list note-list">
  <dt>true</dt>
  <dd>Save session cookies as well.</dd>
  <dt>false</dt>
  <dd>Do not save session cookies. (default)</dd>
</dl>

All options given are passed through to the underlying cookie saver module’s constructor.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/http/cookie_jar.rb', line 212

def save(writable, *options)
  opthash = {
    :format => :yaml,
    :session => false,
  }
  case options.size
  when 0
  when 1
    case options = options.first
    when Symbol
      opthash[:format] = options
    else
      if hash = Hash.try_convert(options)
        opthash.update(hash)
      end
    end
  when 2
    opthash[:format], options = 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

  saver = get_impl(AbstractSaver, opthash[:format], opthash)

  if writable.respond_to?(:write)
    saver.save(writable, self)
  else
    File.open(writable, 'w') { |io|
      saver.save(io, self)
    }
  end

  self
end