class CGI::Cookie - RDoc Documentation

# 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[R]

Domain for which this cookie applies, as a `String`

expires[RW]

`Time` at which this cookie expires, as a `Time`

httponly[R]

True if this cookie is httponly; false otherwise

name[R]

Name of this cookie, as a `String`

path[R]

Path for which this cookie applies, as a `String`

secure[R]

True if this cookie is secure; false otherwise

### Public Class Methods

new(name_string,*value) click to toggle source
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 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.

Calls superclass method `Array::new`

    # 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

parse(raw_cookie) click to toggle source

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

domain=(str) click to toggle source

`Set` domain for which this cookie applies

    # 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

httponly=(val) click to toggle source

`Set` whether the `Cookie` is a httponly cookie or not.

`val` must be a boolean.

    # File lib/cgi/cookie.rb, line 161
    def httponly=(val)
      @httponly = !!val
    end

inspect() click to toggle source

A summary of cookie string.

    # File lib/cgi/cookie.rb, line 202
    def inspect
      "#<CGI::Cookie: #{self.to_s.inspect}>"
    end

name=(str) click to toggle source

`Set` name of this cookie

    # 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=(str) click to toggle source

`Set` path for which this cookie applies

    # 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=(val) click to toggle source

`Set` whether the `Cookie` is a secure cookie or not.

`val` must be a boolean.

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

to_s() click to toggle source

Convert the `Cookie` to its string representation.

    # 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() click to toggle source

Returns the value or list of values for this cookie.

    # File lib/cgi/cookie.rb, line 141
    def value
      self
    end

value=(val) click to toggle source

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

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