class CGI::Cookie
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
Constants
- DOMAIN_VALUE_RE
- PATH_VALUE_RE
- TOKEN_RE
Attributes
Domain for which this cookie applies, as a String
Time at which this cookie expires, as a Time
True if this cookie is httponly; false otherwise
Name of this cookie, as a String
Path for which this cookie applies, as a String
True if this cookie is secure; false otherwise
Public Class Methods
Create a new CGI::Cookie
object.
name_string
-
The name of the cookie; in this form, there is no
domain
or expiration. Thepath
is gleaned from theSCRIPT_NAME
environment variable, andsecure
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.
# File 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
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 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
Public Instance Methods
Set domain for which this cookie applies
# File 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
Set whether the Cookie
is a httponly cookie or not.
val
must be a boolean.
# File cgi/cookie.rb, line 161 def httponly=(val) @httponly = !!val end
A summary of cookie string.
# File cgi/cookie.rb, line 202 def inspect "#<CGI::Cookie: #{self.to_s.inspect}>" end
Set name of this cookie
# File 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
Set path for which this cookie applies
# File 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
Set whether the Cookie
is a secure cookie or not.
val
must be a boolean.
# File cgi/cookie.rb, line 153 def secure=(val) @secure = val if val == true or val == false @secure end
Convert the Cookie
to its string representation.
# File 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
Returns the value or list of values for this cookie.
# File cgi/cookie.rb, line 141 def value self end
Replaces the value of this cookie with a new value or list of values.
# File cgi/cookie.rb, line 146 def value=(val) replace(Array(val)) end