ruby-changes:19554
From: drbrain <ko1@a...>
Date: Tue, 17 May 2011 06:25:50 +0900 (JST)
Subject: [ruby-changes:19554] drbrain:r31595 (trunk): * lib/cgi.rb: Add toplevel documentation to class CGI
drbrain 2011-05-17 06:21:35 +0900 (Tue, 17 May 2011) New Revision: 31595 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31595 Log: * 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] Modified files: trunk/ChangeLog trunk/lib/cgi/cookie.rb trunk/lib/cgi/core.rb trunk/lib/cgi/html.rb trunk/lib/cgi/session.rb trunk/lib/cgi.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 31594) +++ ChangeLog (revision 31595) @@ -1,3 +1,14 @@ +Tue May 17 06:21:15 2011 Eric Hodel <drbrain@s...> + + * 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@s...> * ext/digest: Improve documentation of Digest, Digest::HMAC and Index: lib/cgi.rb =================================================================== --- lib/cgi.rb (revision 31594) +++ lib/cgi.rb (revision 31595) @@ -9,31 +9,25 @@ # # Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber) # + +raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0" + # == 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. +# 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. +# 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.rb provides session management -# functionality; see that file for more details. +# 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. - -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. +# See http://www.w3.org/CGI/ for more information on the CGI protocol. # # == Introduction # @@ -269,6 +263,10 @@ # CGI.new("html4Tr") # html4.01 Transitional # CGI.new("html4Fr") # html4.01 Frameset # + +class CGI +end + require 'cgi/core' require 'cgi/cookie' require 'cgi/util' Index: lib/cgi/session.rb =================================================================== --- lib/cgi/session.rb (revision 31594) +++ lib/cgi/session.rb (revision 31595) @@ -8,29 +8,23 @@ # Author: Yukihiro "Matz" Matsumoto # # Documentation: William Webber (william@w...) -# -# == 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 # # A CGI::Session instance is created from a CGI object. By default, Index: lib/cgi/html.rb =================================================================== --- lib/cgi/html.rb (revision 31594) +++ lib/cgi/html.rb (revision 31595) @@ -1,3 +1,4 @@ +class CGI # Base module for HTML-generation mixins. # # Provides methods for code generation for tags following @@ -2,3 +3,2 @@ # the various DTD element types. -class CGI module TagMaker # :nodoc: Index: lib/cgi/core.rb =================================================================== --- lib/cgi/core.rb (revision 31594) +++ lib/cgi/core.rb (revision 31595) @@ -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,40 +60,69 @@ 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 @@ # "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,14 +269,31 @@ 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" } # # Content-Type: text/html @@ -290,17 +319,20 @@ # "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 @@ # 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 @@ # 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 @@ 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 @@ 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 @@ @@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 Index: lib/cgi/cookie.rb =================================================================== --- lib/cgi/cookie.rb (revision 31594) +++ lib/cgi/cookie.rb (revision 31595) @@ -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 @@ 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 @@ end # class Cookie - # Parse a raw cookie string into a hash of cookie-name=>Cookie # pairs. # -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/