Ruby » Ruby master

# 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

# )

#

# cgi.out("cookie" => [cookie1, cookie2]) { "string" }

#

# name = cookie1.name

# values = cookie1.value

# path = cookie1.path

# domain = cookie1.domain

# expires = cookie1.expires

# secure = cookie1.secure

#

# cookie1.name = 'name'

# cookie1.value = ['value1', 'value2', ...]

# cookie1.path = 'path'

# cookie1.domain = 'domain'

# cookie1.expires = Time.now + 30

# cookie1.secure = true

# :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.

# <tt>*value</tt>:: 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.

# These keywords correspond to attributes of the cookie object.

# Name of this cookie, as a +String+

attr_accessor :name

# Path for which this cookie applies, as a +String+

attr_accessor :path

# Domain for which this cookie applies, as a +String+

attr_accessor :domain

# Time at which this cookie expires, as a +Time+

attr_accessor :expires

# True if this cookie is secure; false otherwise

# Methods for generating HTML, parsing CGI-related parameters, and

# generating HTTP responses.

# :call-seq:

# headers(content_type_string="text/html")

# headers(headers_hash)

#

# +content_type_string+:: If this form is used, this string is the <tt>Content-Type</tt>

# +headers_hash+:: A Hash of header values. The following header keys are recognized:

# type:: the Content-Type header. Defaults to "text/html"

# charset:: the charset of the body, appended to the Content-Type header.

# nph:: a boolean value. If true, prepend protocol string and status code, and

# date; and sets default values for "server" and "connection" if not

# explicitly set.

# status:: the HTTP status code as a String, returned as the Status header. The

# values are:

# OK:: 200 OK

# PARTIAL_CONTENT:: 206 Partial Content

# MULTIPLE_CHOICES:: 300 Multiple Choices

# MOVED:: 301 Moved Permanently

# REDIRECT:: 302 Found

# NOT_MODIFIED:: 304 Not Modified

# BAD_REQUEST:: 400 Bad Request

# AUTH_REQUIRED:: 401 Authorization Required

# FORBIDDEN:: 403 Forbidden

# NOT_FOUND:: 404 Not Found

# METHOD_NOT_ALLOWED:: 405 Method Not Allowed

# NOT_ACCEPTABLE:: 406 Not Acceptable

# LENGTH_REQUIRED:: 411 Length Required

# PRECONDITION_FAILED:: 412 Precondition Failed

# SERVER_ERROR:: 500 Internal Server Error

# NOT_IMPLEMENTED:: 501 Method Not Implemented

# BAD_GATEWAY:: 502 Bad Gateway

# VARIANT_ALSO_VARIES:: 506 Variant Also Negotiates

#

# server:: the server software, returned as the Server header.

# connection:: the connection type, returned as the Connection header (for

# instance, "close".

# length:: the length of the content that will be sent, returned as the

# Content-Length header.

# language:: the language of the content, returned as the Content-Language

# header.

# expires:: the time on which the current content expires, as a +Time+

# object, returned as the Expires header.

# cookie:: a cookie or cookies, returned as one or more Set-Cookie headers.

# The value can be the literal string of the cookie; a CGI::Cookie

# object; an Array of literal cookie strings or Cookie objects; or a

# hash all of whose values are literal cookie strings or Cookie objects.

# These cookies are in addition to the cookies held in the

# @output_cookies field.

# Other headers can also be set; they are appended as key: value.

# Examples:

# :call-seq:

# out(content_type_string='text/html')

# out(headers_hash)

#

# +content_type_string+:: If a string is passed, it is assumed to

# be the content type.

# +headers_hash+:: This is a Hash of headers, similar to that used by #header.

# cgi = CGI.new

# cgi.out{ "string" }

# # Content-Type: text/html

# # Content-Length: 6

# #

# # string

#

# cgi.out("text/plain") { "string" }

# # Content-Type: text/plain

# # Content-Length: 6

# #

# # string

#

# cgi.out("nph" => true,

# "status" => "OK", # == "200 OK"

# "server" => ENV['SERVER_SOFTWARE'],

# "connection" => "close",

# "type" => "text/html",

# "charset" => "iso-2022-jp",

# # Content-Type: text/html; charset=iso-2022-jp

# "language" => "ja",

# "expires" => Time.now + (3600 * 24 * 30),

# "cookie" => [cookie1, cookie2],

# "my_header1" => "my_value",

# "my_header2" => "my_value") { "string" }

# # HTTP/1.1 200 OK

# # Date: Sun, 15 May 2011 17:35:54 GMT

# # Server: Apache 2.2.0

# # Connection: close

# # Content-Type: text/html; charset=iso-2022-jp

# # Content-Length: 6

# # Content-Language: ja

# # Expires: Tue, 14 Jun 2011 17:35:54 GMT

# # Set-Cookie: foo

# # Set-Cookie: bar

# # my_header1: my_value

# # my_header2: my_value

# #

# # string

#

# +block+:: A block is required and should evaluate to the body of the response.

#

# <tt>Content-Length</tt> is automatically calculated from the size of

# If <tt>ENV['REQUEST_METHOD'] == "HEAD"</tt>, then only the header

# is output (the content block is still required, but it

# Mixin module that provides the following:

# 1. Access to the CGI environment variables as methods. See

# documentation to the CGI class for a list of these variables. The methods

# are exposed by removing the leading +HTTP_+ (if it exists) and

# downcasing the name. For example, +auth_type+ will return the

# environment variable +AUTH_TYPE+, and +accept+ will return the

# value for +HTTP_ACCEPT+.

# #[] to perform parameter value lookup by key.

# 4. The initialize_query method, for initializing the above

# retrieved; use #params to get the array of values.

# Return all query parameter names as an array of String.

# Returns true if a given query string parameter exists.

# Exception raised when there is an invalid encoding detected

attr_reader :accept_charset

# :call-seq:

# CGI.new(tag_maker,&block)

# CGI.new(options_hash = {},&block)

#

#

# <tt>tag_maker</tt>:: This is the same as using the +options_hash+ form

# with the value <tt>{ :tag_maker => tag_maker }</tt>

# Note that it is recommended to use the +options_hash+ form,

# since it also allows you specify the charset you will accept.

# <tt>options_hash</tt>:: A Hash that recognizes two options:

# <tt>:accept_charset</tt>:: specifies encoding of received query string. If omitted,

# <tt>@@accept_charset</tt> is used. If the encoding is not

# valid, a CGI::InvalidEncoding will be raised.

#

# Example. Suppose <tt>@@accept_charset</tt> # => "UTF-8"

#

# when not specified:

#

# cgi=CGI.new # @accept_charset # => "UTF-8"

#

# when specified as "EUC-JP":

#

# cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP"

# <tt>:tag_maker</tt>:: a String that specifies which version of the HTML generation methods to use.

# If not specified, no HTML generation methods will be loaded.

# The following values are supported:

# "html3":: HTML 3.x

# "html4":: HTML 4.0

# "html4Tr":: HTML 4.0 Transitional

# "html4Fr":: HTML 4.0 with Framesets

#

# <tt>&block</tt>:: If provided, the block is called when an invalid

# encoding is encountered. For example:

#

# encoding_errors={}

# cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value|

# encoding_errors[name] = value

# end

#

# Finally, if the CGI object is not created in a standard CGI call environment

# CGI locations, which varies according to the REQUEST_METHOD.

def initialize(options = {},&block) # :yields: name,value

class CGI