From 1a514ab4d9825e720c072db2dacd9373df72d472 Mon Sep 17 00:00:00 2001 From: Dave Copeland Date: Sun, 15 May 2011 14:10:17 -0400 Subject: [PATCH 2/6] cleaned up CGI documentation --- lib/cgi/cookie.rb | 108 ++++++++++--------- lib/cgi/core.rb | 308 +++++++++++++++++++++++++++------------------------- lib/cgi/html.rb | 2 +- 3 files changed, 220 insertions(+), 198 deletions(-) diff --git a/lib/cgi/cookie.rb b/lib/cgi/cookie.rb index 97a92ef..98ddae4 100644 --- a/lib/cgi/cookie.rb +++ b/lib/cgi/cookie.rb @@ -1,58 +1,60 @@ -# 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: - # - # 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. + # :call-seq: + # Cookie.new(name_string,*value) + # Cookie.new(options_hash) # - # These keywords correspond to attributes of the 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. + # These keywords correspond to attributes of the cookie object. def initialize(name = "", *value) @domain = nil @expires = nil @@ -85,7 +87,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 diff --git a/lib/cgi/core.rb b/lib/cgi/core.rb index 41efea9..4853bed 100644 --- a/lib/cgi/core.rb +++ b/lib/cgi/core.rb @@ -1,3 +1,5 @@ +# Methods for generating HTML, parsing CGI-related parameters, and +# generating HTTP responses. class CGI $CGI_ENV = ENV # for FCGI support @@ -59,36 +61,57 @@ class CGI # 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: - # - # 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. - # - # Other header lines can also be set; they are appended as key: value. + # +content_type_string+:: If this form is used, this string is the Content-Type + # +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: # # header # # Content-Type: text/html @@ -111,27 +134,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) @@ -261,41 +263,60 @@ class CGI # 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. - # - # 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" } - # - # Content-Length is automatically calculated from the size of + # :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. + # + # 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 + # If ENV['REQUEST_METHOD'] == "HEAD", 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 @@ -350,17 +371,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 +648,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 +667,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 +681,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 +702,56 @@ 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. - # - # CGI.new("html3") #=> CGI.new(:tag_maker=>"html3") - # - # And, if you specify string, @accept_charset cannot be changed. - # Instead, please use hash parameter. - # - # == accept_charset - # - # :accept_charset specifies encoding of received query string. - # ( Default value is @@accept_charset. ) - # If not valid, raise CGI::InvalidEncoding - # - # Example. Suppose @@accept_charset # => "UTF-8" - # - # when not specified: - # - # cgi=CGI.new # @accept_charset # => "UTF-8" - # - # when specified "EUC-JP": - # - # cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP" - # - # == block - # - # When you use a block, you can write a process - # that query encoding is invalid. Example: - # - # encoding_error={} - # cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value| - # encoding_error[key] = value - # end - # - # == tag_maker - # - # :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 + # :call-seq: + # CGI.new(tag_maker,&block) + # CGI.new(options_hash = {},&block) + # + # + # tag_maker:: This is the same as using the +options_hash+ form + # with the value { :tag_maker => tag_maker } + # Note that it is recommended to use the +options_hash+ form, + # since it also allows you specify the charset you will accept. + # options_hash:: A Hash that recognizes two options: + # :accept_charset:: specifies encoding of received query string. If omitted, + # @@accept_charset is used. If the encoding is not + # valid, a CGI::InvalidEncoding will be raised. + # + # Example. Suppose @@accept_charset # => "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" + # :tag_maker:: 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 + # + # &block:: 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 # (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 diff --git a/lib/cgi/html.rb b/lib/cgi/html.rb index 2864219..04e2431 100644 --- a/lib/cgi/html.rb +++ b/lib/cgi/html.rb @@ -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. -- 1.7.3.4