Class: CGI::Cookie

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Array
Instance Chain: self, Array
Inherits:	Array `::Object` Array CGI::Cookie
Defined in:	lib/cgi/cookie.rb

Overview

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
                          'httponly' => 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

httponly = cookie1.httponly

cookie1.name     = 'name'
cookie1.value    = ['value1', 'value2', ...]
cookie1.path     = 'path'
cookie1.domain   = 'domain'
cookie1.expires  = Time.now + 30
cookie1.secure   = true
cookie1.httponly = true

Constant Summary

DOMAIN_VALUE_RE =
# File 'lib/cgi/cookie.rb', line 45

%r"\A(?<label>(?!-)[-A-Za-z0-9]+(?<!-))(?:\.\g<label>)*\z"

PATH_VALUE_RE =
# File 'lib/cgi/cookie.rb', line 44
```
%r"\A[[ -~]&&[^;]]*\z"
```
TOKEN_RE =
# File 'lib/cgi/cookie.rb', line 43
```
%r"\A[[!-~]&&[^()<>@,;:\\\"/?=\[\]{}]]+\z"
```

Class Method Summary

.new(name_string, *value) ⇒ Cookie constructor

Create a new Cookie object.
.parse(raw_cookie)

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

Instance Attribute Summary

#domain rw

Domain for which this cookie applies, as a String
#domain=(str) rw

Set domain for which this cookie applies.
#expires rw

Time at which this cookie expires, as a Time
#httponly rw

True if this cookie is httponly; false otherwise.
#httponly=(val) rw

Set whether the Cookie is a httponly cookie or not.
#name rw

Name of this cookie, as a String
#name=(str) rw

Set name of this cookie.
#path rw

Path for which this cookie applies, as a String
#path=(str) rw

Set path for which this cookie applies.
#secure rw

True if this cookie is secure; false otherwise.
#secure=(val) rw

Set whether the Cookie is a secure cookie or not.
#value rw

Returns the value or list of values for this cookie.
#value=(val) rw

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

Instance Method Summary

#inspect

A summary of cookie string.
#to_s

Convert the Cookie to its string representation.

Constructor Details

.new(name_string, *value) ⇒ `Cookie` .new(options_hash) ⇒ `Cookie`

Create a new 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 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.

httponly

whether this cookie is a HttpOnly cookie or not (default to false). HttpOnly cookies are not available to javascript.

These keywords correspond to attributes of the cookie object.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 75


def initialize(name = "", *value)
  @domain = nil
  @expires = nil
  if name.kind_of?(String)
    self.name = name
    self.path = (%r|\A(.*/)| =~ ENV["SCRIPT_NAME"] ? $1 : "")
    @secure = false
    @httponly = false
    return super(value)
  end

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

  self.name = options["name"]
  value = Array(options["value"])
  # simple support for IE
  self.path = options["path"] || (%r|\A(.*/)| =~ ENV["SCRIPT_NAME"] ? $1 : "")
  self.domain = options["domain"]
  @expires = options["expires"]
  @secure = options["secure"] == true
  @httponly = options["httponly"] == true

  super(value)
end

Class Method Details

.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, ... }

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 183


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
    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 Attribute Details

#domain (rw)

Domain for which this cookie applies, as a String

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 124


attr_reader :domain

#domain=(str) (rw)

Set domain for which this cookie applies

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 126


def domain=(str)
  if str and ((str = str.b).bytesize > 255 or !DOMAIN_VALUE_RE.match?(str))
    raise ArgumentError, "invalid domain: #{str.dump}"
  end
  @domain = str
end

#expires (rw)

Time at which this cookie expires, as a Time

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 134


attr_accessor :expires

#httponly (rw)

True if this cookie is httponly; false otherwise

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 138


attr_reader :httponly

#httponly=(val) (rw)

Set whether the Cookie is a httponly cookie or not.

val must be a boolean.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 161


def httponly=(val)
  @httponly = !!val
end

#name (rw)

Name of this cookie, as a String

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 104


attr_reader :name

#name=(str) (rw)

Set name of this cookie

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 106


def name=(str)
  if str and !TOKEN_RE.match?(str)
    raise ArgumentError, "invalid name: #{str.dump}"
  end
  @name = str
end

#path (rw)

Path for which this cookie applies, as a String

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 114


attr_reader :path

#path=(str) (rw)

Set path for which this cookie applies

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 116


def path=(str)
  if str and !PATH_VALUE_RE.match?(str)
    raise ArgumentError, "invalid path: #{str.dump}"
  end
  @path = str
end

#secure (rw)

True if this cookie is secure; false otherwise

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 136


attr_reader :secure

#secure=(val) (rw)

Set whether the Cookie is a secure cookie or not.

val must be a boolean.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 153


def secure=(val)
  @secure = val if val == true or val == false
  @secure
end

#value (rw)

Returns the value or list of values for this cookie.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 141


def value
  self
end

#value=(val) (rw)

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

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 146


def value=(val)
  replace(Array(val))
end

Instance Method Details

#inspect

A summary of cookie string.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 202


def inspect
  "#<CGI::Cookie: #{self.to_s.inspect}>"
end

#to_s

Convert the Cookie to its string representation.

[ GitHub ]

# File 'lib/cgi/cookie.rb', line 166


def to_s
  val = collect{|v| CGI.escape(v) }.join("&")
  buf = "#{@name}=#{val}".dup
  buf << "; domain=#{@domain}" if @domain
  buf << "; path=#{@path}"     if @path
  buf << "; expires=#{CGI.rfc1123_date(@expires)}" if @expires
  buf << "; secure"            if @secure
  buf << "; HttpOnly"          if @httponly
  buf
end

Class: CGI::Cookie

Overview

Examples of use

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(name_string, *value) ⇒ Cookie .new(options_hash) ⇒ Cookie

Class Method Details

.parse(raw_cookie)

Instance Attribute Details

#domain (rw)

#domain=(str) (rw)

#expires (rw)

#httponly (rw)

#httponly=(val) (rw)

#name (rw)

#name=(str) (rw)

#path (rw)

#path=(str) (rw)

#secure (rw)

#secure=(val) (rw)

#value (rw)

#value=(val) (rw)

Instance Method Details

#inspect

#to_s

.new(name_string, *value) ⇒ `Cookie` .new(options_hash) ⇒ `Cookie`