Class: CGI::Cookie

Inherits:
Array show all
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 collapse

TOKEN_RE = 
%r"\A[[!-~]&&[^()<>@,;:\\\"/?=\[\]{}]]+\z"
PATH_VALUE_RE = 
%r"\A[[ -~]&&[^;]]*\z"
DOMAIN_VALUE_RE = 
%r"\A\.?(?<label>(?!-)[-A-Za-z0-9]+(?<!-))(?:\.\g<label>)*\z"
@@accept_charset = 
"UTF-8"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Array

#pretty_print, #pretty_print_cycle, #quote, #shelljoin

Constructor Details

#initialize(name = "", *value) ⇒ Cookie

Create a new CGI::Cookie object.

:call-seq:

Cookie.new(name_string,*value)
Cookie.new(options_hash)
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.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# 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

Instance Attribute Details

#domain ⇒ Object

Domain for which this cookie applies, as a String



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

def domain
  @domain
end

#expires ⇒ Object

Time at which this cookie expires, as a Time



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

def expires
  @expires
end

#httponly ⇒ Object

True if this cookie is httponly; false otherwise



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

def httponly
  @httponly
end

#name ⇒ Object

Name of this cookie, as a String



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

def name
  @name
end

#path ⇒ Object

Path for which this cookie applies, as a String



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

def path
  @path
end

#secure ⇒ Object

True if this cookie is secure; false otherwise



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

def secure
  @secure
end

Class Method Details

.parse(raw_cookie) ⇒ Object

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

cookies = CGI::Cookie.parse("raw_cookie_string")
  # { "name1" => cookie1, "name2" => cookie2, ... }



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# 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 Method Details

#inspect ⇒ Object

A summary of cookie string.



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

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

#to_s ⇒ Object

Convert the Cookie to its string representation.



166
167
168
169
170
171
172
173
174
175
 
# 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

#value ⇒ Object

Returns the value or list of values for this cookie.



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

def value
  self
end

#value=(val) ⇒ Object

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



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

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