123456789_123456789_123456789_123456789_123456789_

Class: CGI::Cookie

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Array
Instance Chain:
self, Array
Inherits: Array
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

Class Method Summary

Instance Attribute Summary

  • #domain rw

    Domain for which this cookie applies, as a String

  • #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

  • #path rw

    Path for which this cookie applies, as a String

  • #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 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 71

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
    @httponly = 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
  @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 161

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

#domain (rw)

Domain for which this cookie applies, as a String

[ GitHub ]

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

attr_accessor :domain

#expires (rw)

Time at which this cookie expires, as a Time

[ GitHub ]

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

attr_accessor :expires

#httponly (rw)

True if this cookie is httponly; false otherwise

[ GitHub ]

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

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 139

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

#name (rw)

Name of this cookie, as a String

[ GitHub ]

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

attr_accessor :name

#path (rw)

Path for which this cookie applies, as a String

[ GitHub ]

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

attr_accessor :path

#secure (rw)

True if this cookie is secure; false otherwise

[ GitHub ]

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

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 131

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 119

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 124

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

Instance Method Details

#inspect

A summary of cookie string.

[ GitHub ]

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

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 144

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
  buf << "; HttpOnly"          if @httponly
  buf
end