Class: HTTP::CookieJar

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

Overview

:markup: markdown

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.



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

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.



13
14
15
 
# File 'lib/http/cookie_jar.rb', line 13

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



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

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.



323
324
325
326
 
# File 'lib/http/cookie_jar.rb', line 323

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

#clear ⇒ Object

Clears the cookie jar and returns self.



316
317
318
319
 
# File 'lib/http/cookie_jar.rb', line 316

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.



113
114
115
 
# File 'lib/http/cookie_jar.rb', line 113

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.



105
106
107
108
 
# File 'lib/http/cookie_jar.rb', line 105

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.



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

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) 


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

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.



61
62
63
 
# File 'lib/http/cookie_jar.rb', line 61

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.



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
312
313
 
# File 'lib/http/cookie_jar.rb', line 277

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.



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

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.



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
249
250
 
# File 'lib/http/cookie_jar.rb', line 214

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