1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

* lib/cgi.rb: Add toplevel documentation to class CGI

* lib/cgi/session.rb: Add overview documentation to CGI::Cookie
	* lib/cgi/html.rb:  Don't add CGI::TagMaker documentation to CGI.
	  Patch by David Copeland.  [Ruby 1.9 - Bug #4704]
	* lib/cgi/core.rb:  Clean up CGI documentation.  Patch by David
	  Copeland.  [Ruby 1.9 - Bug #4704]
	* lib/cgi/cookie.rb:  Clean up CGI::Cookie documentation.  Patch by
	  David Copeland.  [Ruby 1.9 - Bug #4704]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31595 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain 2011-05-16 21:21:35 +00:00
parent c648243c3d
commit e60f744e9a
6 changed files with 255 additions and 205 deletions

View file

@ -1,3 +1,14 @@
Tue May 17 06:21:15 2011 Eric Hodel <drbrain@segment7.net>
* lib/cgi.rb: Add toplevel documentation to class CGI
* lib/cgi/session.rb: Add overview documentation to CGI::Cookie
* lib/cgi/html.rb: Don't add CGI::TagMaker documentation to CGI.
Patch by David Copeland. [Ruby 1.9 - Bug #4704]
* lib/cgi/core.rb: Clean up CGI documentation. Patch by David
Copeland. [Ruby 1.9 - Bug #4704]
* lib/cgi/cookie.rb: Clean up CGI::Cookie documentation. Patch by
David Copeland. [Ruby 1.9 - Bug #4704]
Tue May 17 05:52:30 2011 Eric Hodel <drbrain@segment7.net>
* ext/digest: Improve documentation of Digest, Digest::HMAC and

View file

@ -9,31 +9,25 @@
#
# Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber)
#
# == Overview
#
# The Common Gateway Interface (CGI) is a simple protocol
# for passing an HTTP request from a web server to a
# standalone program, and returning the output to the web
# browser. Basically, a CGI program is called with the
# parameters of the request passed in either in the
# environment (GET) or via $stdin (POST), and everything
# it prints to $stdout is returned to the client.
#
# This file holds the +CGI+ class. This class provides
# functionality for retrieving HTTP request parameters,
# managing cookies, and generating HTML output. See the
# class documentation for more details and examples of use.
#
# The file cgi/session.rb provides session management
# functionality; see that file for more details.
#
# See http://www.w3.org/CGI/ for more information on the CGI
# protocol.
raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0"
# CGI class. See documentation for the file cgi.rb for an overview
# of the CGI protocol.
# == Overview
#
# The Common Gateway Interface (CGI) is a simple protocol for passing an HTTP
# request from a web server to a standalone program, and returning the output
# to the web browser. Basically, a CGI program is called with the parameters
# of the request passed in either in the environment (GET) or via $stdin
# (POST), and everything it prints to $stdout is returned to the client.
#
# This file holds the CGI class. This class provides functionality for
# retrieving HTTP request parameters, managing cookies, and generating HTML
# output.
#
# The file CGI::Session provides session management functionality; see that
# class for more details.
#
# See http://www.w3.org/CGI/ for more information on the CGI protocol.
#
# == Introduction
#
@ -269,6 +263,10 @@ raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0"
# CGI.new("html4Tr") # html4.01 Transitional
# CGI.new("html4Fr") # html4.01 Frameset
#
class CGI
end
require 'cgi/core'
require 'cgi/cookie'
require 'cgi/util'

View file

@ -1,58 +1,66 @@
# 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
class CGI
@@accept_charset="UTF-8" unless defined?(@@accept_charset)
# 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
class Cookie < Array
# Create a new CGI::Cookie object.
#
# The contents of the cookie can be specified as a +name+ and one
# or more +value+ arguments. Alternatively, the contents can
# be specified as a single hash argument. The possible keywords of
# this hash are as follows:
# :call-seq:
# Cookie.new(name_string,*value)
# Cookie.new(options_hash)
#
# 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
# base directory of the CGI script.
# 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.
# +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:
#
# These keywords correspond to attributes of the cookie object.
# 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.
def initialize(name = "", *value)
@domain = nil
@expires = nil
@ -85,7 +93,15 @@ class CGI
super(value)
end
attr_accessor("name", "path", "domain", "expires")
# 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
attr_reader("secure")
def value
@ -117,7 +133,6 @@ class CGI
end # class Cookie
# Parse a raw cookie string into a hash of cookie-name=>Cookie
# pairs.
#

View file

@ -1,3 +1,7 @@
#--
# Methods for generating HTML, parsing CGI-related parameters, and
# generating HTTP responses.
#++
class CGI
$CGI_ENV = ENV # for FCGI support
@ -56,39 +60,68 @@ class CGI
private :env_table, :stdinput, :stdoutput
# Create an HTTP header block as a string.
#
# :call-seq:
# headers(content_type_string="text/html")
# headers(headers_hash)
#
# Includes the empty line that ends the header block.
#
# +options+ can be a string specifying the Content-Type (defaults
# to text/html), or a hash of header key/value pairs. The following
# header keys are recognized:
# +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, returned as the Status header. See the
# list of available status codes below.
# 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.
# 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:
#
# Other header lines can also be set; they are appended as key: value.
# 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:
#
# header
# # Content-Type: text/html
@ -111,27 +144,6 @@ class CGI
# "my_header1" => "my_value"
# "my_header2" => "my_value")
#
# The status codes 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"
#
# This method does not perform charset conversion.
def header(options='text/html')
if options.is_a?(String)
@ -257,13 +269,30 @@ class CGI
return ''
end
private :_header_for_modruby
#
# Print an HTTP header and body to $DEFAULT_OUTPUT ($>)
#
# The header is provided by +options+, as for #header().
# The body of the document is that returned by the passed-
# in block. This block takes no arguments. It is required.
# :call-seq:
# cgi.out(content_type_string='text/html')
# cgi.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.
# +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
# the String returned by the content block.
#
# If <tt>ENV['REQUEST_METHOD'] == "HEAD"</tt>, then only the header
# is output (the content block is still required, but it is ignored).
#
# If the charset is "iso-2022-jp" or "euc-jp" or "shift_jis" then the
# content is converted to this charset, and the language is set to "ja".
#
# Example:
#
# cgi = CGI.new
# cgi.out{ "string" }
@ -290,17 +319,20 @@ class CGI
# "cookie" => [cookie1, cookie2],
# "my_header1" => "my_value",
# "my_header2" => "my_value") { "string" }
#
# Content-Length is automatically calculated from the size of
# the String returned by the content block.
#
# If ENV['REQUEST_METHOD'] == "HEAD", then only the header
# is outputted (the content block is still required, but it
# is ignored).
#
# If the charset is "iso-2022-jp" or "euc-jp" or "shift_jis" then
# the content is converted to this charset, and the language is set
# to "ja".
# # 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
def out(options = "text/html") # :yield:
options = { "type" => options } if options.kind_of?(String)
@ -350,17 +382,21 @@ class CGI
# Maximum number of request parameters when multipart
MAX_MULTIPART_COUNT = 128
# Mixin module. It provides the follow functionality groups:
# Mixin module that provides the following:
#
# 1. Access to CGI environment variables as methods. See
# documentation to the CGI class for a list of these variables.
# 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+.
#
# 2. Access to cookies, including the cookies attribute.
#
# 3. Access to parameters, including the params attribute, and overloading
# [] to perform parameter value lookup by key.
# #[] to perform parameter value lookup by key.
#
# 4. The initialize_query method, for initialising the above
# 4. The initialize_query method, for initializing the above
# mechanisms, handling multipart forms, and allowing the
# class to be used in "offline" mode.
#
@ -623,7 +659,7 @@ class CGI
# Get the value for the parameter with a given key.
#
# If the parameter has multiple values, only the first will be
# retrieved; use #params() to get the array of values.
# retrieved; use #params to get the array of values.
def [](key)
params = @params[key]
return '' unless params
@ -642,12 +678,12 @@ class CGI
end
end
# Return all parameter keys as an array.
# Return all query parameter names as an array of String.
def keys(*args)
@params.keys(*args)
end
# Returns true if a given parameter key exists in the query.
# Returns true if a given query string parameter exists.
def has_key?(*args)
@params.has_key?(*args)
end
@ -656,7 +692,7 @@ class CGI
end # QueryExtension
# InvalidEncoding Exception class
# Exception raised when there is an invalid encoding detected
class InvalidEncoding < Exception; end
# @@accept_charset is default accept character set.
@ -677,69 +713,65 @@ class CGI
@@accept_charset=accept_charset
end
attr_reader :accept_charset
# Create a new CGI instance.
#
# CGI accept constructor parameters either in a hash, string as a block.
# But string is as same as using :tag_maker of hash.
# :call-seq:
# CGI.new(tag_maker) { block }
# CGI.new(options_hash = {}) { block }
#
# CGI.new("html3") #=> CGI.new(:tag_maker=>"html3")
#
# And, if you specify string, @accept_charset cannot be changed.
# Instead, please use hash parameter.
# <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:
#
# == accept_charset
# <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.
#
# :accept_charset specifies encoding of received query string.
# ( Default value is @@accept_charset. )
# If not valid, raise CGI::InvalidEncoding
# Example. Suppose <tt>@@accept_charset</tt> is "UTF-8"
#
# Example. Suppose @@accept_charset # => "UTF-8"
# when not specified:
#
# when not specified:
# cgi=CGI.new # @accept_charset # => "UTF-8"
#
# cgi=CGI.new # @accept_charset # => "UTF-8"
# when specified as "EUC-JP":
#
# when specified "EUC-JP":
# cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP"
#
# cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP"
# <tt>:tag_maker</tt>::
# String that specifies which version of the HTML generation methods to
# use. If not specified, no HTML generation methods will be loaded.
#
# == block
# The following values are supported:
#
# When you use a block, you can write a process
# that query encoding is invalid. Example:
# "html3":: HTML 3.x
# "html4":: HTML 4.0
# "html4Tr":: HTML 4.0 Transitional
# "html4Fr":: HTML 4.0 with Framesets
#
# encoding_error={}
# cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value|
# encoding_error[key] = value
# end
# <tt>block</tt>::
# If provided, the block is called when an invalid encoding is
# encountered. For example:
#
# == tag_maker
# encoding_errors={}
# cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value|
# encoding_errors[name] = value
# end
#
# :tag_maker specifies which version of HTML to load the HTML generation
# methods for. The following versions of HTML are supported:
#
# html3:: HTML 3.x
# html4:: HTML 4.0
# html4Tr:: HTML 4.0 Transitional
# html4Fr:: HTML 4.0 with Framesets
#
# If not specified, no HTML generation methods will be loaded.
#
# If the CGI object is not created in a standard CGI call environment
# (that is, it can't locate REQUEST_METHOD in its environment), then
# it will run in "offline" mode. In this mode, it reads its parameters
# Finally, if the CGI object is not created in a standard CGI call
# environment (that is, it can't locate REQUEST_METHOD in its environment),
# then it will run in "offline" mode. In this mode, it reads its parameters
# from the command line or (failing that) from standard input. Otherwise,
# cookies and other parameters are parsed automatically from the standard
# CGI locations, which varies according to the REQUEST_METHOD. It works this:
#
# CGI.new(:tag_maker=>"html3")
#
# This will be obsolete:
#
# CGI.new("html3")
#
attr_reader :accept_charset
def initialize(options = {},&block)
# CGI locations, which varies according to the REQUEST_METHOD.
def initialize(options = {}, &block) # :yields: name, value
@accept_charset_error_block=block if block_given?
@options={:accept_charset=>@@accept_charset}
case options

View file

@ -1,8 +1,8 @@
class CGI
# Base module for HTML-generation mixins.
#
# Provides methods for code generation for tags following
# the various DTD element types.
class CGI
module TagMaker # :nodoc:
# Generate code for an element with required start and end tags.

View file

@ -8,28 +8,22 @@
# Author: Yukihiro "Matz" Matsumoto
#
# Documentation: William Webber (william@williamwebber.com)
#
# == Overview
#
# This file provides the +CGI::Session+ class, which provides session
# support for CGI scripts. A session is a sequence of HTTP requests
# and responses linked together and associated with a single client.
# Information associated with the session is stored
# on the server between requests. A session id is passed between client
# and server with every request and response, transparently
# to the user. This adds state information to the otherwise stateless
# HTTP request/response protocol.
#
# See the documentation to the +CGI::Session+ class for more details
# and examples of usage. See cgi.rb for the +CGI+ class itself.
require 'cgi'
require 'tmpdir'
class CGI
# Class representing an HTTP session. See documentation for the file
# cgi/session.rb for an introduction to HTTP sessions.
# == Overview
#
# This file provides the CGI::Session class, which provides session
# support for CGI scripts. A session is a sequence of HTTP requests
# and responses linked together and associated with a single client.
# Information associated with the session is stored
# on the server between requests. A session id is passed between client
# and server with every request and response, transparently
# to the user. This adds state information to the otherwise stateless
# HTTP request/response protocol.
#
# == Lifecycle
#