Class representing an HTTP cookie.

In addition to its specific fields and methods, a Cookie instance is a delegator to the array of its values.

See RFC 2965.

Examples of use

cookie1 = CGI::Cookie.new("name", "value1", "value2", ...)
cookie1 = CGI::Cookie.new("name" => "name", "value" => "value")
cookie1 = CGI::Cookie.new('name'    => 'name',
                           'value'   => ['value1', 'value2', ...],
                           'path'    => 'path',   # optional
                           'domain'  => 'domain', # optional
                           'expires' => Time.now, # optional
                           'secure'  => true      # optional
                          )

cgi.out("cookie" => [cookie1, cookie2]) { "string" }

name    = cookie1.name
values  = cookie1.value
path    = cookie1.path
domain  = cookie1.domain
expires = cookie1.expires
secure  = cookie1.secure

cookie1.name    = 'name'
cookie1.value   = ['value1', 'value2', ...]
cookie1.path    = 'path'
cookie1.domain  = 'domain'
cookie1.expires = Time.now + 30
cookie1.secure  = true
Methods
I
N
P
S
T
V
Attributes
[RW] domain

Domain for which this cookie applies, as a String

[RW] expires

Time at which this cookie expires, as a Time

[RW] name

Name of this cookie, as a String

[RW] path

Path for which this cookie applies, as a String

[R] secure

True if this cookie is secure; false otherwise

Class Public methods
Cookie.new(name_string,*value)
Cookie.new(options_hash)

Create a new CGI::Cookie object.

name_string

The name of the cookie; in this form, there is no domain or expiration. The path is gleaned from the SCRIPT_NAME environment variable, and secure is false.

*value

value or list of values of the cookie

options_hash

A Hash of options to initialize this Cookie. Possible options are:

name

the name of the cookie. Required.

value

the cookie's value or list of values.

path

the path for which this cookie applies. Defaults to the the value of the SCRIPT_NAME environment variable.

domain

the domain for which this cookie applies.

expires

the time at which this cookie expires, as a Time object.

secure

whether this cookie is a secure cookie or not (default to false). Secure cookies are only transmitted to HTTPS servers.

These keywords correspond to attributes of the cookie object.

# File lib/cgi/cookie.rb, line 65
def initialize(name = "", *value)
  @domain = nil
  @expires = nil
  if name.kind_of?(String)
    @name = name
    %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
    @path = ($1 or "")
    @secure = false
    return super(value)
  end

  options = name
  unless options.has_key?("name")
    raise ArgumentError, "`name' required"
  end

  @name = options["name"]
  value = Array(options["value"])
  # simple support for IE
  if options["path"]
    @path = options["path"]
  else
    %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
    @path = ($1 or "")
  end
  @domain = options["domain"]
  @expires = options["expires"]
  @secure = options["secure"] == true ? true : false

  super(value)
end
parse(raw_cookie)

Parse a raw cookie string into a hash of cookie-name=>Cookie pairs.

cookies = CGI::Cookie.parse("raw_cookie_string")
  # { "name1" => cookie1, "name2" => cookie2, ... }
# File lib/cgi/cookie.rb, line 143
def self.parse(raw_cookie)
  cookies = Hash.new([])
  return cookies unless raw_cookie

  raw_cookie.split(/[;,]\s?/).each do |pairs|
    name, values = pairs.split('=',2)
    next unless name and values
    name = CGI.unescape(name)
    values ||= ""
    values = values.split('&').collect{|v| CGI.unescape(v,@@accept_charset) }
    if cookies.has_key?(name)
      values = cookies[name].value + values
    end
    cookies[name] = Cookie.new(name, *values)
  end

  cookies
end
Instance Public methods
inspect()

A summary of cookie string.

# File lib/cgi/cookie.rb, line 163
def inspect
  "#<CGI::Cookie: #{self.to_s.inspect}>"
end
secure=(val)

Set whether the Cookie is a secure cookie or not.

val must be a boolean.

# File lib/cgi/cookie.rb, line 121
def secure=(val)
  @secure = val if val == true or val == false
  @secure
end
to_s()

Convert the Cookie to its string representation.

# File lib/cgi/cookie.rb, line 127
def to_s
  val = collect{|v| CGI.escape(v) }.join("&")
  buf = "#{@name}=#{val}"
  buf << "; domain=#{@domain}" if @domain
  buf << "; path=#{@path}"     if @path
  buf << "; expires=#{CGI::rfc1123_date(@expires)}" if @expires
  buf << "; secure"            if @secure == true
  buf
end
value()

Returns the value or list of values for this cookie.

# File lib/cgi/cookie.rb, line 109
def value
  self
end
value=(val)

Replaces the value of this cookie with a new value or list of values.

# File lib/cgi/cookie.rb, line 114
def value=(val)
  replace(Array(val))
end