home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / lib / ruby / 1.8 / cgi.rb < prev    next >
Encoding:
Ruby Source  |  2007-03-07  |  73.5 KB  |  2,302 lines
  1. # 
  2. # cgi.rb - cgi support library
  3. # 
  4. # Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
  5. # 
  6. # Copyright (C) 2000  Information-technology Promotion Agency, Japan
  7. #
  8. # Author: Wakou Aoyama <wakou@ruby-lang.org>
  9. #
  10. # Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber) 
  11. # 
  12. # == Overview
  13. #
  14. # The Common Gateway Interface (CGI) is a simple protocol
  15. # for passing an HTTP request from a web server to a
  16. # standalone program, and returning the output to the web
  17. # browser.  Basically, a CGI program is called with the
  18. # parameters of the request passed in either in the
  19. # environment (GET) or via $stdin (POST), and everything
  20. # it prints to $stdout is returned to the client.
  21. # 
  22. # This file holds the +CGI+ class.  This class provides
  23. # functionality for retrieving HTTP request parameters,
  24. # managing cookies, and generating HTML output.  See the
  25. # class documentation for more details and examples of use.
  26. #
  27. # The file cgi/session.rb provides session management
  28. # functionality; see that file for more details.
  29. #
  30. # See http://www.w3.org/CGI/ for more information on the CGI
  31. # protocol.
  32.  
  33. raise "Please, use ruby 1.5.4 or later." if RUBY_VERSION < "1.5.4"
  34.  
  35. require 'English'
  36.  
  37. # CGI class.  See documentation for the file cgi.rb for an overview
  38. # of the CGI protocol.
  39. #
  40. # == Introduction
  41. #
  42. # CGI is a large class, providing several categories of methods, many of which
  43. # are mixed in from other modules.  Some of the documentation is in this class,
  44. # some in the modules CGI::QueryExtension and CGI::HtmlExtension.  See
  45. # CGI::Cookie for specific information on handling cookies, and cgi/session.rb
  46. # (CGI::Session) for information on sessions.
  47. #
  48. # For queries, CGI provides methods to get at environmental variables,
  49. # parameters, cookies, and multipart request data.  For responses, CGI provides
  50. # methods for writing output and generating HTML.
  51. #
  52. # Read on for more details.  Examples are provided at the bottom.
  53. #
  54. # == Queries
  55. #
  56. # The CGI class dynamically mixes in parameter and cookie-parsing
  57. # functionality,  environmental variable access, and support for
  58. # parsing multipart requests (including uploaded files) from the
  59. # CGI::QueryExtension module.
  60. #
  61. # === Environmental Variables
  62. #
  63. # The standard CGI environmental variables are available as read-only
  64. # attributes of a CGI object.  The following is a list of these variables:
  65. #
  66. #
  67. #   AUTH_TYPE               HTTP_HOST          REMOTE_IDENT
  68. #   CONTENT_LENGTH          HTTP_NEGOTIATE     REMOTE_USER
  69. #   CONTENT_TYPE            HTTP_PRAGMA        REQUEST_METHOD
  70. #   GATEWAY_INTERFACE       HTTP_REFERER       SCRIPT_NAME
  71. #   HTTP_ACCEPT             HTTP_USER_AGENT    SERVER_NAME
  72. #   HTTP_ACCEPT_CHARSET     PATH_INFO          SERVER_PORT
  73. #   HTTP_ACCEPT_ENCODING    PATH_TRANSLATED    SERVER_PROTOCOL
  74. #   HTTP_ACCEPT_LANGUAGE    QUERY_STRING       SERVER_SOFTWARE
  75. #   HTTP_CACHE_CONTROL      REMOTE_ADDR
  76. #   HTTP_FROM               REMOTE_HOST
  77. #
  78. #
  79. # For each of these variables, there is a corresponding attribute with the
  80. # same name, except all lower case and without a preceding HTTP_.  
  81. # +content_length+ and +server_port+ are integers; the rest are strings.
  82. #
  83. # === Parameters
  84. #
  85. # The method #params() returns a hash of all parameters in the request as
  86. # name/value-list pairs, where the value-list is an Array of one or more
  87. # values.  The CGI object itself also behaves as a hash of parameter names 
  88. # to values, but only returns a single value (as a String) for each 
  89. # parameter name.
  90. #
  91. # For instance, suppose the request contains the parameter 
  92. # "favourite_colours" with the multiple values "blue" and "green".  The
  93. # following behaviour would occur:
  94. #
  95. #   cgi.params["favourite_colours"]  # => ["blue", "green"]
  96. #   cgi["favourite_colours"]         # => "blue"
  97. #
  98. # If a parameter does not exist, the former method will return an empty
  99. # array, the latter an empty string.  The simplest way to test for existence
  100. # of a parameter is by the #has_key? method.
  101. #
  102. # === Cookies
  103. #
  104. # HTTP Cookies are automatically parsed from the request.  They are available
  105. # from the #cookies() accessor, which returns a hash from cookie name to
  106. # CGI::Cookie object.
  107. #
  108. # === Multipart requests
  109. #
  110. # If a request's method is POST and its content type is multipart/form-data, 
  111. # then it may contain uploaded files.  These are stored by the QueryExtension
  112. # module in the parameters of the request.  The parameter name is the name
  113. # attribute of the file input field, as usual.  However, the value is not
  114. # a string, but an IO object, either an IOString for small files, or a
  115. # Tempfile for larger ones.  This object also has the additional singleton
  116. # methods:
  117. #
  118. # #local_path():: the path of the uploaded file on the local filesystem
  119. # #original_filename():: the name of the file on the client computer
  120. # #content_type():: the content type of the file
  121. #
  122. # == Responses
  123. #
  124. # The CGI class provides methods for sending header and content output to
  125. # the HTTP client, and mixes in methods for programmatic HTML generation
  126. # from CGI::HtmlExtension and CGI::TagMaker modules.  The precise version of HTML
  127. # to use for HTML generation is specified at object creation time.
  128. #
  129. # === Writing output
  130. #
  131. # The simplest way to send output to the HTTP client is using the #out() method.
  132. # This takes the HTTP headers as a hash parameter, and the body content
  133. # via a block.  The headers can be generated as a string using the #header()
  134. # method.  The output stream can be written directly to using the #print()
  135. # method.
  136. #
  137. # === Generating HTML
  138. #
  139. # Each HTML element has a corresponding method for generating that
  140. # element as a String.  The name of this method is the same as that
  141. # of the element, all lowercase.  The attributes of the element are 
  142. # passed in as a hash, and the body as a no-argument block that evaluates
  143. # to a String.  The HTML generation module knows which elements are
  144. # always empty, and silently drops any passed-in body.  It also knows
  145. # which elements require matching closing tags and which don't.  However,
  146. # it does not know what attributes are legal for which elements.
  147. #
  148. # There are also some additional HTML generation methods mixed in from
  149. # the CGI::HtmlExtension module.  These include individual methods for the
  150. # different types of form inputs, and methods for elements that commonly
  151. # take particular attributes where the attributes can be directly specified
  152. # as arguments, rather than via a hash.
  153. #
  154. # == Examples of use
  155. # 
  156. # === Get form values
  157. # 
  158. #   require "cgi"
  159. #   cgi = CGI.new
  160. #   value = cgi['field_name']   # <== value string for 'field_name'
  161. #     # if not 'field_name' included, then return "".
  162. #   fields = cgi.keys            # <== array of field names
  163. # 
  164. #   # returns true if form has 'field_name'
  165. #   cgi.has_key?('field_name')
  166. #   cgi.has_key?('field_name')
  167. #   cgi.include?('field_name')
  168. # 
  169. # CAUTION! cgi['field_name'] returned an Array with the old 
  170. # cgi.rb(included in ruby 1.6)
  171. # 
  172. # === Get form values as hash
  173. # 
  174. #   require "cgi"
  175. #   cgi = CGI.new
  176. #   params = cgi.params
  177. # 
  178. # cgi.params is a hash.
  179. # 
  180. #   cgi.params['new_field_name'] = ["value"]  # add new param
  181. #   cgi.params['field_name'] = ["new_value"]  # change value
  182. #   cgi.params.delete('field_name')           # delete param
  183. #   cgi.params.clear                          # delete all params
  184. # 
  185. # 
  186. # === Save form values to file
  187. # 
  188. #   require "pstore"
  189. #   db = PStore.new("query.db")
  190. #   db.transaction do
  191. #     db["params"] = cgi.params
  192. #   end
  193. # 
  194. # 
  195. # === Restore form values from file
  196. # 
  197. #   require "pstore"
  198. #   db = PStore.new("query.db")
  199. #   db.transaction do
  200. #     cgi.params = db["params"]
  201. #   end
  202. # 
  203. # 
  204. # === Get multipart form values
  205. # 
  206. #   require "cgi"
  207. #   cgi = CGI.new
  208. #   value = cgi['field_name']   # <== value string for 'field_name'
  209. #   value.read                  # <== body of value
  210. #   value.local_path            # <== path to local file of value
  211. #   value.original_filename     # <== original filename of value
  212. #   value.content_type          # <== content_type of value
  213. # 
  214. # and value has StringIO or Tempfile class methods.
  215. # 
  216. # === Get cookie values
  217. # 
  218. #   require "cgi"
  219. #   cgi = CGI.new
  220. #   values = cgi.cookies['name']  # <== array of 'name'
  221. #     # if not 'name' included, then return [].
  222. #   names = cgi.cookies.keys      # <== array of cookie names
  223. # 
  224. # and cgi.cookies is a hash.
  225. # 
  226. # === Get cookie objects
  227. # 
  228. #   require "cgi"
  229. #   cgi = CGI.new
  230. #   for name, cookie in cgi.cookies
  231. #     cookie.expires = Time.now + 30
  232. #   end
  233. #   cgi.out("cookie" => cgi.cookies) {"string"}
  234. # 
  235. #   cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
  236. # 
  237. #   require "cgi"
  238. #   cgi = CGI.new
  239. #   cgi.cookies['name'].expires = Time.now + 30
  240. #   cgi.out("cookie" => cgi.cookies['name']) {"string"}
  241. # 
  242. # === Print http header and html string to $DEFAULT_OUTPUT ($>)
  243. # 
  244. #   require "cgi"
  245. #   cgi = CGI.new("html3")  # add HTML generation methods
  246. #   cgi.out() do
  247. #     cgi.html() do
  248. #       cgi.head{ cgi.title{"TITLE"} } +
  249. #       cgi.body() do
  250. #         cgi.form() do
  251. #           cgi.textarea("get_text") +
  252. #           cgi.br +
  253. #           cgi.submit
  254. #         end +
  255. #         cgi.pre() do
  256. #           CGI::escapeHTML(
  257. #             "params: " + cgi.params.inspect + "\n" +
  258. #             "cookies: " + cgi.cookies.inspect + "\n" +
  259. #             ENV.collect() do |key, value|
  260. #               key + " --> " + value + "\n"
  261. #             end.join("")
  262. #           )
  263. #         end
  264. #       end
  265. #     end
  266. #   end
  267. # 
  268. #   # add HTML generation methods
  269. #   CGI.new("html3")    # html3.2
  270. #   CGI.new("html4")    # html4.01 (Strict)
  271. #   CGI.new("html4Tr")  # html4.01 Transitional
  272. #   CGI.new("html4Fr")  # html4.01 Frameset
  273. #
  274. class CGI
  275.  
  276.   # :stopdoc:
  277.  
  278.   # String for carriage return
  279.   CR  = "\015"
  280.  
  281.   # String for linefeed
  282.   LF  = "\012"
  283.  
  284.   # Standard internet newline sequence
  285.   EOL = CR + LF
  286.  
  287.   REVISION = '$Id: cgi.rb,v 1.68.2.17 2006/09/04 07:36:49 matz Exp $' #:nodoc:
  288.  
  289.   NEEDS_BINMODE = true if /WIN/ni.match(RUBY_PLATFORM) 
  290.  
  291.   # Path separators in different environments.
  292.   PATH_SEPARATOR = {'UNIX'=>'/', 'WINDOWS'=>'\\', 'MACINTOSH'=>':'}
  293.  
  294.   # HTTP status codes.
  295.   HTTP_STATUS = {
  296.     "OK"                  => "200 OK",
  297.     "PARTIAL_CONTENT"     => "206 Partial Content",
  298.     "MULTIPLE_CHOICES"    => "300 Multiple Choices",
  299.     "MOVED"               => "301 Moved Permanently",
  300.     "REDIRECT"            => "302 Found",
  301.     "NOT_MODIFIED"        => "304 Not Modified",
  302.     "BAD_REQUEST"         => "400 Bad Request",
  303.     "AUTH_REQUIRED"       => "401 Authorization Required",
  304.     "FORBIDDEN"           => "403 Forbidden",
  305.     "NOT_FOUND"           => "404 Not Found",
  306.     "METHOD_NOT_ALLOWED"  => "405 Method Not Allowed",
  307.     "NOT_ACCEPTABLE"      => "406 Not Acceptable",
  308.     "LENGTH_REQUIRED"     => "411 Length Required",
  309.     "PRECONDITION_FAILED" => "412 Rrecondition Failed",
  310.     "SERVER_ERROR"        => "500 Internal Server Error",
  311.     "NOT_IMPLEMENTED"     => "501 Method Not Implemented",
  312.     "BAD_GATEWAY"         => "502 Bad Gateway",
  313.     "VARIANT_ALSO_VARIES" => "506 Variant Also Negotiates"
  314.   }
  315.  
  316.   # Abbreviated day-of-week names specified by RFC 822
  317.   RFC822_DAYS = %w[ Sun Mon Tue Wed Thu Fri Sat ]
  318.  
  319.   # Abbreviated month names specified by RFC 822
  320.   RFC822_MONTHS = %w[ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ]
  321.  
  322.   # :startdoc:
  323.  
  324.   def env_table 
  325.     ENV
  326.   end
  327.  
  328.   def stdinput
  329.     $stdin
  330.   end
  331.  
  332.   def stdoutput
  333.     $DEFAULT_OUTPUT
  334.   end
  335.  
  336.   private :env_table, :stdinput, :stdoutput
  337.  
  338.   # URL-encode a string.
  339.   #   url_encoded_string = CGI::escape("'Stop!' said Fred")
  340.   #      # => "%27Stop%21%27+said+Fred"
  341.   def CGI::escape(string)
  342.     string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
  343.       '%' + $1.unpack('H2' * $1.size).join('%').upcase
  344.     end.tr(' ', '+')
  345.   end
  346.  
  347.  
  348.   # URL-decode a string.
  349.   #   string = CGI::unescape("%27Stop%21%27+said+Fred")
  350.   #      # => "'Stop!' said Fred"
  351.   def CGI::unescape(string)
  352.     string.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
  353.       [$1.delete('%')].pack('H*')
  354.     end
  355.   end
  356.  
  357.  
  358.   # Escape special characters in HTML, namely &\"<>
  359.   #   CGI::escapeHTML('Usage: foo "bar" <baz>')
  360.   #      # => "Usage: foo "bar" <baz>"
  361.   def CGI::escapeHTML(string)
  362.     string.gsub(/&/n, '&').gsub(/\"/n, '"').gsub(/>/n, '>').gsub(/</n, '<')
  363.   end
  364.  
  365.  
  366.   # Unescape a string that has been HTML-escaped
  367.   #   CGI::unescapeHTML("Usage: foo "bar" <baz>")
  368.   #      # => "Usage: foo \"bar\" <baz>"
  369.   def CGI::unescapeHTML(string)
  370.     string.gsub(/&(.*?);/n) do
  371.       match = $1.dup
  372.       case match
  373.       when /\Aamp\z/ni           then '&'
  374.       when /\Aquot\z/ni          then '"'
  375.       when /\Agt\z/ni            then '>'
  376.       when /\Alt\z/ni            then '<'
  377.       when /\A#0*(\d+)\z/n       then
  378.         if Integer($1) < 256
  379.           Integer($1).chr
  380.         else
  381.           if Integer($1) < 65536 and ($KCODE[0] == ?u or $KCODE[0] == ?U)
  382.             [Integer($1)].pack("U")
  383.           else
  384.             "&##{$1};"
  385.           end
  386.         end
  387.       when /\A#x([0-9a-f]+)\z/ni then
  388.         if $1.hex < 256
  389.           $1.hex.chr
  390.         else
  391.           if $1.hex < 65536 and ($KCODE[0] == ?u or $KCODE[0] == ?U)
  392.             [$1.hex].pack("U")
  393.           else
  394.             "&#x#{$1};"
  395.           end
  396.         end
  397.       else
  398.         "&#{match};"
  399.       end
  400.     end
  401.   end
  402.  
  403.  
  404.   # Escape only the tags of certain HTML elements in +string+.
  405.   #
  406.   # Takes an element or elements or array of elements.  Each element
  407.   # is specified by the name of the element, without angle brackets.
  408.   # This matches both the start and the end tag of that element.
  409.   # The attribute list of the open tag will also be escaped (for
  410.   # instance, the double-quotes surrounding attribute values).
  411.   #
  412.   #   print CGI::escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
  413.   #     # "<BR><A HREF="url"></A>"
  414.   #
  415.   #   print CGI::escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
  416.   #     # "<BR><A HREF="url"></A>"
  417.   def CGI::escapeElement(string, *elements)
  418.     elements = elements[0] if elements[0].kind_of?(Array)
  419.     unless elements.empty?
  420.       string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/ni) do
  421.         CGI::escapeHTML($&)
  422.       end
  423.     else
  424.       string
  425.     end
  426.   end
  427.  
  428.  
  429.   # Undo escaping such as that done by CGI::escapeElement()
  430.   #
  431.   #   print CGI::unescapeElement(
  432.   #           CGI::escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
  433.   #     # "<BR><A HREF="url"></A>"
  434.   # 
  435.   #   print CGI::unescapeElement(
  436.   #           CGI::escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
  437.   #     # "<BR><A HREF="url"></A>"
  438.   def CGI::unescapeElement(string, *elements)
  439.     elements = elements[0] if elements[0].kind_of?(Array)
  440.     unless elements.empty?
  441.       string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/ni) do
  442.         CGI::unescapeHTML($&)
  443.       end
  444.     else
  445.       string
  446.     end
  447.   end
  448.  
  449.  
  450.   # Format a +Time+ object as a String using the format specified by RFC 1123.
  451.   #
  452.   #   CGI::rfc1123_date(Time.now)
  453.   #     # Sat, 01 Jan 2000 00:00:00 GMT
  454.   def CGI::rfc1123_date(time)
  455.     t = time.clone.gmtime
  456.     return format("%s, %.2d %s %.4d %.2d:%.2d:%.2d GMT",
  457.                 RFC822_DAYS[t.wday], t.day, RFC822_MONTHS[t.month-1], t.year,
  458.                 t.hour, t.min, t.sec)
  459.   end
  460.  
  461.  
  462.   # Create an HTTP header block as a string.
  463.   #
  464.   # Includes the empty line that ends the header block.
  465.   #
  466.   # +options+ can be a string specifying the Content-Type (defaults
  467.   # to text/html), or a hash of header key/value pairs.  The following
  468.   # header keys are recognized:
  469.   #
  470.   # type:: the Content-Type header.  Defaults to "text/html"
  471.   # charset:: the charset of the body, appended to the Content-Type header.
  472.   # nph:: a boolean value.  If true, prepend protocol string and status code, and
  473.   #       date; and sets default values for "server" and "connection" if not
  474.   #       explicitly set.
  475.   # status:: the HTTP status code, returned as the Status header.  See the
  476.   #          list of available status codes below.
  477.   # server:: the server software, returned as the Server header.
  478.   # connection:: the connection type, returned as the Connection header (for 
  479.   #              instance, "close".
  480.   # length:: the length of the content that will be sent, returned as the
  481.   #          Content-Length header.
  482.   # language:: the language of the content, returned as the Content-Language
  483.   #            header.
  484.   # expires:: the time on which the current content expires, as a +Time+
  485.   #           object, returned as the Expires header.
  486.   # cookie:: a cookie or cookies, returned as one or more Set-Cookie headers.
  487.   #          The value can be the literal string of the cookie; a CGI::Cookie
  488.   #          object; an Array of literal cookie strings or Cookie objects; or a 
  489.   #          hash all of whose values are literal cookie strings or Cookie objects.
  490.   #          These cookies are in addition to the cookies held in the
  491.   #          @output_cookies field.
  492.   #
  493.   # Other header lines can also be set; they are appended as key: value.
  494.   # 
  495.   #   header
  496.   #     # Content-Type: text/html
  497.   # 
  498.   #   header("text/plain")
  499.   #     # Content-Type: text/plain
  500.   # 
  501.   #   header("nph"        => true,
  502.   #          "status"     => "OK",  # == "200 OK"
  503.   #            # "status"     => "200 GOOD",
  504.   #          "server"     => ENV['SERVER_SOFTWARE'],
  505.   #          "connection" => "close",
  506.   #          "type"       => "text/html",
  507.   #          "charset"    => "iso-2022-jp",
  508.   #            # Content-Type: text/html; charset=iso-2022-jp
  509.   #          "length"     => 103,
  510.   #          "language"   => "ja",
  511.   #          "expires"    => Time.now + 30,
  512.   #          "cookie"     => [cookie1, cookie2],
  513.   #          "my_header1" => "my_value"
  514.   #          "my_header2" => "my_value")
  515.   # 
  516.   # The status codes are:
  517.   # 
  518.   #   "OK"                  --> "200 OK"
  519.   #   "PARTIAL_CONTENT"     --> "206 Partial Content"
  520.   #   "MULTIPLE_CHOICES"    --> "300 Multiple Choices"
  521.   #   "MOVED"               --> "301 Moved Permanently"
  522.   #   "REDIRECT"            --> "302 Found"
  523.   #   "NOT_MODIFIED"        --> "304 Not Modified"
  524.   #   "BAD_REQUEST"         --> "400 Bad Request"
  525.   #   "AUTH_REQUIRED"       --> "401 Authorization Required"
  526.   #   "FORBIDDEN"           --> "403 Forbidden"
  527.   #   "NOT_FOUND"           --> "404 Not Found"
  528.   #   "METHOD_NOT_ALLOWED"  --> "405 Method Not Allowed"
  529.   #   "NOT_ACCEPTABLE"      --> "406 Not Acceptable"
  530.   #   "LENGTH_REQUIRED"     --> "411 Length Required"
  531.   #   "PRECONDITION_FAILED" --> "412 Precondition Failed"
  532.   #   "SERVER_ERROR"        --> "500 Internal Server Error"
  533.   #   "NOT_IMPLEMENTED"     --> "501 Method Not Implemented"
  534.   #   "BAD_GATEWAY"         --> "502 Bad Gateway"
  535.   #   "VARIANT_ALSO_VARIES" --> "506 Variant Also Negotiates"
  536.   # 
  537.   # This method does not perform charset conversion. 
  538.   #
  539.   def header(options = "text/html")
  540.  
  541.     buf = ""
  542.  
  543.     case options
  544.     when String
  545.       options = { "type" => options }
  546.     when Hash
  547.       options = options.dup
  548.     end
  549.  
  550.     unless options.has_key?("type")
  551.       options["type"] = "text/html"
  552.     end
  553.  
  554.     if options.has_key?("charset")
  555.       options["type"] += "; charset=" + options.delete("charset")
  556.     end
  557.  
  558.     options.delete("nph") if defined?(MOD_RUBY)
  559.     if options.delete("nph") or /IIS/n.match(env_table['SERVER_SOFTWARE'])
  560.       buf += (env_table["SERVER_PROTOCOL"] or "HTTP/1.0")  + " " +
  561.              (HTTP_STATUS[options["status"]] or options["status"] or "200 OK") +
  562.              EOL +
  563.              "Date: " + CGI::rfc1123_date(Time.now) + EOL
  564.  
  565.       unless options.has_key?("server")
  566.         options["server"] = (env_table['SERVER_SOFTWARE'] or "")
  567.       end
  568.  
  569.       unless options.has_key?("connection")
  570.         options["connection"] = "close"
  571.       end
  572.  
  573.       options.delete("status")
  574.     end
  575.  
  576.     if options.has_key?("status")
  577.       buf += "Status: " +
  578.              (HTTP_STATUS[options["status"]] or options["status"]) + EOL
  579.       options.delete("status")
  580.     end
  581.  
  582.     if options.has_key?("server")
  583.       buf += "Server: " + options.delete("server") + EOL
  584.     end
  585.  
  586.     if options.has_key?("connection")
  587.       buf += "Connection: " + options.delete("connection") + EOL
  588.     end
  589.  
  590.     buf += "Content-Type: " + options.delete("type") + EOL
  591.  
  592.     if options.has_key?("length")
  593.       buf += "Content-Length: " + options.delete("length").to_s + EOL
  594.     end
  595.  
  596.     if options.has_key?("language")
  597.       buf += "Content-Language: " + options.delete("language") + EOL
  598.     end
  599.  
  600.     if options.has_key?("expires")
  601.       buf += "Expires: " + CGI::rfc1123_date( options.delete("expires") ) + EOL
  602.     end
  603.  
  604.     if options.has_key?("cookie")
  605.       if options["cookie"].kind_of?(String) or
  606.            options["cookie"].kind_of?(Cookie)
  607.         buf += "Set-Cookie: " + options.delete("cookie").to_s + EOL
  608.       elsif options["cookie"].kind_of?(Array)
  609.         options.delete("cookie").each{|cookie|
  610.           buf += "Set-Cookie: " + cookie.to_s + EOL
  611.         }
  612.       elsif options["cookie"].kind_of?(Hash)
  613.         options.delete("cookie").each_value{|cookie|
  614.           buf += "Set-Cookie: " + cookie.to_s + EOL
  615.         }
  616.       end
  617.     end
  618.     if @output_cookies
  619.       for cookie in @output_cookies
  620.         buf += "Set-Cookie: " + cookie.to_s + EOL
  621.       end
  622.     end
  623.  
  624.     options.each{|key, value|
  625.       buf += key + ": " + value.to_s + EOL
  626.     }
  627.  
  628.     if defined?(MOD_RUBY)
  629.       table = Apache::request.headers_out
  630.       buf.scan(/([^:]+): (.+)#{EOL}/n){ |name, value|
  631.         warn sprintf("name:%s value:%s\n", name, value) if $DEBUG
  632.         case name
  633.         when 'Set-Cookie'
  634.           table.add(name, value)
  635.         when /^status$/ni
  636.           Apache::request.status_line = value
  637.           Apache::request.status = value.to_i
  638.         when /^content-type$/ni
  639.           Apache::request.content_type = value
  640.         when /^content-encoding$/ni
  641.           Apache::request.content_encoding = value
  642.         when /^location$/ni
  643.       if Apache::request.status == 200
  644.         Apache::request.status = 302
  645.       end
  646.           Apache::request.headers_out[name] = value
  647.         else
  648.           Apache::request.headers_out[name] = value
  649.         end
  650.       }
  651.       Apache::request.send_http_header
  652.       ''
  653.     else
  654.       buf + EOL
  655.     end
  656.  
  657.   end # header()
  658.  
  659.  
  660.   # Print an HTTP header and body to $DEFAULT_OUTPUT ($>)
  661.   #
  662.   # The header is provided by +options+, as for #header().
  663.   # The body of the document is that returned by the passed-
  664.   # in block.  This block takes no arguments.  It is required.
  665.   #
  666.   #   cgi = CGI.new
  667.   #   cgi.out{ "string" }
  668.   #     # Content-Type: text/html
  669.   #     # Content-Length: 6
  670.   #     #
  671.   #     # string
  672.   # 
  673.   #   cgi.out("text/plain") { "string" }
  674.   #     # Content-Type: text/plain
  675.   #     # Content-Length: 6
  676.   #     #
  677.   #     # string
  678.   # 
  679.   #   cgi.out("nph"        => true,
  680.   #           "status"     => "OK",  # == "200 OK"
  681.   #           "server"     => ENV['SERVER_SOFTWARE'],
  682.   #           "connection" => "close",
  683.   #           "type"       => "text/html",
  684.   #           "charset"    => "iso-2022-jp",
  685.   #             # Content-Type: text/html; charset=iso-2022-jp
  686.   #           "language"   => "ja",
  687.   #           "expires"    => Time.now + (3600 * 24 * 30),
  688.   #           "cookie"     => [cookie1, cookie2],
  689.   #           "my_header1" => "my_value",
  690.   #           "my_header2" => "my_value") { "string" }
  691.   # 
  692.   # Content-Length is automatically calculated from the size of
  693.   # the String returned by the content block.
  694.   #
  695.   # If ENV['REQUEST_METHOD'] == "HEAD", then only the header
  696.   # is outputted (the content block is still required, but it
  697.   # is ignored).
  698.   # 
  699.   # If the charset is "iso-2022-jp" or "euc-jp" or "shift_jis" then
  700.   # the content is converted to this charset, and the language is set 
  701.   # to "ja".
  702.   def out(options = "text/html") # :yield:
  703.  
  704.     options = { "type" => options } if options.kind_of?(String)
  705.     content = yield
  706.  
  707.     if options.has_key?("charset")
  708.       require "nkf"
  709.       case options["charset"]
  710.       when /iso-2022-jp/ni
  711.         content = NKF::nkf('-m0 -x -j', content)
  712.         options["language"] = "ja" unless options.has_key?("language")
  713.       when /euc-jp/ni
  714.         content = NKF::nkf('-m0 -x -e', content)
  715.         options["language"] = "ja" unless options.has_key?("language")
  716.       when /shift_jis/ni
  717.         content = NKF::nkf('-m0 -x -s', content)
  718.         options["language"] = "ja" unless options.has_key?("language")
  719.       end
  720.     end
  721.  
  722.     options["length"] = content.length.to_s
  723.     output = stdoutput
  724.     output.binmode if defined? output.binmode
  725.     output.print header(options)
  726.     output.print content unless "HEAD" == env_table['REQUEST_METHOD']
  727.   end
  728.  
  729.  
  730.   # Print an argument or list of arguments to the default output stream
  731.   #
  732.   #   cgi = CGI.new
  733.   #   cgi.print    # default:  cgi.print == $DEFAULT_OUTPUT.print
  734.   def print(*options)
  735.     stdoutput.print(*options)
  736.   end
  737.  
  738.   require "delegate"
  739.  
  740.   # Class representing an HTTP cookie.
  741.   #
  742.   # In addition to its specific fields and methods, a Cookie instance
  743.   # is a delegator to the array of its values.
  744.   #
  745.   # See RFC 2965.
  746.   #
  747.   # == Examples of use
  748.   #   cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
  749.   #   cookie1 = CGI::Cookie::new("name" => "name", "value" => "value")
  750.   #   cookie1 = CGI::Cookie::new('name'    => 'name',
  751.   #                              'value'   => ['value1', 'value2', ...],
  752.   #                              'path'    => 'path',   # optional
  753.   #                              'domain'  => 'domain', # optional
  754.   #                              'expires' => Time.now, # optional
  755.   #                              'secure'  => true      # optional
  756.   #                             )
  757.   # 
  758.   #   cgi.out("cookie" => [cookie1, cookie2]) { "string" }
  759.   # 
  760.   #   name    = cookie1.name
  761.   #   values  = cookie1.value
  762.   #   path    = cookie1.path
  763.   #   domain  = cookie1.domain
  764.   #   expires = cookie1.expires
  765.   #   secure  = cookie1.secure
  766.   # 
  767.   #   cookie1.name    = 'name'
  768.   #   cookie1.value   = ['value1', 'value2', ...]
  769.   #   cookie1.path    = 'path'
  770.   #   cookie1.domain  = 'domain'
  771.   #   cookie1.expires = Time.now + 30
  772.   #   cookie1.secure  = true
  773.   class Cookie < DelegateClass(Array)
  774.  
  775.     # Create a new CGI::Cookie object.
  776.     #
  777.     # The contents of the cookie can be specified as a +name+ and one
  778.     # or more +value+ arguments.  Alternatively, the contents can
  779.     # be specified as a single hash argument.  The possible keywords of
  780.     # this hash are as follows:
  781.     #
  782.     # name:: the name of the cookie.  Required.
  783.     # value:: the cookie's value or list of values.
  784.     # path:: the path for which this cookie applies.  Defaults to the
  785.     #        base directory of the CGI script.
  786.     # domain:: the domain for which this cookie applies.
  787.     # expires:: the time at which this cookie expires, as a +Time+ object.
  788.     # secure:: whether this cookie is a secure cookie or not (default to
  789.     #          false).  Secure cookies are only transmitted to HTTPS 
  790.     #          servers.
  791.     #
  792.     # These keywords correspond to attributes of the cookie object.
  793.     def initialize(name = "", *value)
  794.       options = if name.kind_of?(String)
  795.                   { "name" => name, "value" => value }
  796.                 else
  797.                   name
  798.                 end
  799.       unless options.has_key?("name")
  800.         raise ArgumentError, "`name' required"
  801.       end
  802.  
  803.       @name = options["name"]
  804.       @value = Array(options["value"])
  805.       # simple support for IE
  806.       if options["path"]
  807.         @path = options["path"]
  808.       else
  809.         %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
  810.         @path = ($1 or "")
  811.       end
  812.       @domain = options["domain"]
  813.       @expires = options["expires"]
  814.       @secure = options["secure"] == true ? true : false
  815.  
  816.       super(@value)
  817.     end
  818.  
  819.     attr_accessor("name", "value", "path", "domain", "expires")
  820.     attr_reader("secure")
  821.  
  822.     # Set whether the Cookie is a secure cookie or not.
  823.     #
  824.     # +val+ must be a boolean.
  825.     def secure=(val)
  826.       @secure = val if val == true or val == false
  827.       @secure
  828.     end
  829.  
  830.     # Convert the Cookie to its string representation.
  831.     def to_s
  832.       buf = ""
  833.       buf += @name + '='
  834.  
  835.       if @value.kind_of?(String)
  836.         buf += CGI::escape(@value)
  837.       else
  838.         buf += @value.collect{|v| CGI::escape(v) }.join("&")
  839.       end
  840.  
  841.       if @domain
  842.         buf += '; domain=' + @domain
  843.       end
  844.  
  845.       if @path
  846.         buf += '; path=' + @path
  847.       end
  848.  
  849.       if @expires
  850.         buf += '; expires=' + CGI::rfc1123_date(@expires)
  851.       end
  852.  
  853.       if @secure == true
  854.         buf += '; secure'
  855.       end
  856.  
  857.       buf
  858.     end
  859.  
  860.   end # class Cookie
  861.  
  862.  
  863.   # Parse a raw cookie string into a hash of cookie-name=>Cookie
  864.   # pairs.
  865.   #
  866.   #   cookies = CGI::Cookie::parse("raw_cookie_string")
  867.   #     # { "name1" => cookie1, "name2" => cookie2, ... }
  868.   #
  869.   def Cookie::parse(raw_cookie)
  870.     cookies = Hash.new([])
  871.     return cookies unless raw_cookie
  872.  
  873.     raw_cookie.split(/[;,]\s?/).each do |pairs|
  874.       name, values = pairs.split('=',2)
  875.       next unless name and values
  876.       name = CGI::unescape(name)
  877.       values ||= ""
  878.       values = values.split('&').collect{|v| CGI::unescape(v) }
  879.       if cookies.has_key?(name)
  880.         values = cookies[name].value + values
  881.       end
  882.       cookies[name] = Cookie::new({ "name" => name, "value" => values })
  883.     end
  884.  
  885.     cookies
  886.   end
  887.  
  888.   # Parse an HTTP query string into a hash of key=>value pairs.
  889.   #
  890.   #   params = CGI::parse("query_string")
  891.   #     # {"name1" => ["value1", "value2", ...],
  892.   #     #  "name2" => ["value1", "value2", ...], ... }
  893.   #
  894.   def CGI::parse(query)
  895.     params = Hash.new([].freeze)
  896.  
  897.     query.split(/[&;]/n).each do |pairs|
  898.       key, value = pairs.split('=',2).collect{|v| CGI::unescape(v) }
  899.       if params.has_key?(key)
  900.         params[key].push(value)
  901.       else
  902.         params[key] = [value]
  903.       end
  904.     end
  905.  
  906.     params
  907.   end
  908.  
  909.   # Mixin module. It provides the follow functionality groups:
  910.   #
  911.   # 1. Access to CGI environment variables as methods.  See 
  912.   #    documentation to the CGI class for a list of these variables.
  913.   #
  914.   # 2. Access to cookies, including the cookies attribute.
  915.   #
  916.   # 3. Access to parameters, including the params attribute, and overloading
  917.   #    [] to perform parameter value lookup by key.
  918.   #
  919.   # 4. The initialize_query method, for initialising the above
  920.   #    mechanisms, handling multipart forms, and allowing the
  921.   #    class to be used in "offline" mode.
  922.   #
  923.   module QueryExtension
  924.  
  925.     %w[ CONTENT_LENGTH SERVER_PORT ].each do |env|
  926.       define_method(env.sub(/^HTTP_/n, '').downcase) do
  927.         (val = env_table[env]) && Integer(val)
  928.       end
  929.     end
  930.  
  931.     %w[ AUTH_TYPE CONTENT_TYPE GATEWAY_INTERFACE PATH_INFO
  932.         PATH_TRANSLATED QUERY_STRING REMOTE_ADDR REMOTE_HOST
  933.         REMOTE_IDENT REMOTE_USER REQUEST_METHOD SCRIPT_NAME
  934.         SERVER_NAME SERVER_PROTOCOL SERVER_SOFTWARE
  935.  
  936.         HTTP_ACCEPT HTTP_ACCEPT_CHARSET HTTP_ACCEPT_ENCODING
  937.         HTTP_ACCEPT_LANGUAGE HTTP_CACHE_CONTROL HTTP_FROM HTTP_HOST
  938.         HTTP_NEGOTIATE HTTP_PRAGMA HTTP_REFERER HTTP_USER_AGENT ].each do |env|
  939.       define_method(env.sub(/^HTTP_/n, '').downcase) do
  940.         env_table[env]
  941.       end
  942.     end
  943.  
  944.     # Get the raw cookies as a string.
  945.     def raw_cookie
  946.       env_table["HTTP_COOKIE"]
  947.     end
  948.  
  949.     # Get the raw RFC2965 cookies as a string.
  950.     def raw_cookie2
  951.       env_table["HTTP_COOKIE2"]
  952.     end
  953.  
  954.     # Get the cookies as a hash of cookie-name=>Cookie pairs.
  955.     attr_accessor("cookies")
  956.  
  957.     # Get the parameters as a hash of name=>values pairs, where
  958.     # values is an Array.
  959.     attr("params")
  960.  
  961.     # Set all the parameters.
  962.     def params=(hash)
  963.       @params.clear
  964.       @params.update(hash)
  965.     end
  966.  
  967.     def read_multipart(boundary, content_length)
  968.       params = Hash.new([])
  969.       boundary = "--" + boundary
  970.       quoted_boundary = Regexp.quote(boundary, "n")
  971.       buf = ""
  972.       bufsize = 10 * 1024
  973.       boundary_end=""
  974.  
  975.       # start multipart/form-data
  976.       stdinput.binmode if defined? stdinput.binmode
  977.       boundary_size = boundary.size + EOL.size
  978.       content_length -= boundary_size
  979.       status = stdinput.read(boundary_size)
  980.       if nil == status
  981.         raise EOFError, "no content body"
  982.       elsif boundary + EOL != status
  983.         raise EOFError, "bad content body"
  984.       end
  985.  
  986.       loop do
  987.         head = nil
  988.         if 10240 < content_length
  989.           require "tempfile"
  990.           body = Tempfile.new("CGI")
  991.         else
  992.           begin
  993.             require "stringio"
  994.             body = StringIO.new
  995.           rescue LoadError
  996.             require "tempfile"
  997.             body = Tempfile.new("CGI")
  998.           end
  999.         end
  1000.         body.binmode if defined? body.binmode
  1001.  
  1002.         until head and /#{quoted_boundary}(?:#{EOL}|--)/n.match(buf)
  1003.  
  1004.           if (not head) and /#{EOL}#{EOL}/n.match(buf)
  1005.             buf = buf.sub(/\A((?:.|\n)*?#{EOL})#{EOL}/n) do
  1006.               head = $1.dup
  1007.               ""
  1008.             end
  1009.             next
  1010.           end
  1011.  
  1012.           if head and ( (EOL + boundary + EOL).size < buf.size )
  1013.             body.print buf[0 ... (buf.size - (EOL + boundary + EOL).size)]
  1014.             buf[0 ... (buf.size - (EOL + boundary + EOL).size)] = ""
  1015.           end
  1016.  
  1017.           c = if bufsize < content_length
  1018.                 stdinput.read(bufsize)
  1019.               else
  1020.                 stdinput.read(content_length)
  1021.               end
  1022.           if c.nil? || c.empty?
  1023.             raise EOFError, "bad content body"
  1024.           end
  1025.           buf.concat(c)
  1026.           content_length -= c.size
  1027.         end
  1028.  
  1029.         buf = buf.sub(/\A((?:.|\n)*?)(?:[\r\n]{1,2})?#{quoted_boundary}([\r\n]{1,2}|--)/n) do
  1030.           body.print $1
  1031.           if "--" == $2
  1032.             content_length = -1
  1033.           end
  1034.          boundary_end = $2.dup
  1035.           ""
  1036.         end
  1037.  
  1038.         body.rewind
  1039.  
  1040.         /Content-Disposition:.* filename="?([^\";]*)"?/ni.match(head)
  1041.     filename = ($1 or "")
  1042.     if /Mac/ni.match(env_table['HTTP_USER_AGENT']) and
  1043.         /Mozilla/ni.match(env_table['HTTP_USER_AGENT']) and
  1044.         (not /MSIE/ni.match(env_table['HTTP_USER_AGENT']))
  1045.       filename = CGI::unescape(filename)
  1046.     end
  1047.         
  1048.         /Content-Type: (.*)/ni.match(head)
  1049.         content_type = ($1 or "")
  1050.  
  1051.         (class << body; self; end).class_eval do
  1052.           alias local_path path
  1053.           define_method(:original_filename) {filename.dup.taint}
  1054.           define_method(:content_type) {content_type.dup.taint}
  1055.         end
  1056.  
  1057.         /Content-Disposition:.* name="?([^\";]*)"?/ni.match(head)
  1058.         name = $1.dup
  1059.  
  1060.         if params.has_key?(name)
  1061.           params[name].push(body)
  1062.         else
  1063.           params[name] = [body]
  1064.         end
  1065.         break if buf.size == 0
  1066.         break if content_length === -1
  1067.       end
  1068.       raise EOFError, "bad boundary end of body part" unless boundary_end=~/--/
  1069.  
  1070.       params
  1071.     end # read_multipart
  1072.     private :read_multipart
  1073.  
  1074.     # offline mode. read name=value pairs on standard input.
  1075.     def read_from_cmdline
  1076.       require "shellwords"
  1077.  
  1078.       string = unless ARGV.empty?
  1079.         ARGV.join(' ')
  1080.       else
  1081.         if STDIN.tty?
  1082.           STDERR.print(
  1083.             %|(offline mode: enter name=value pairs on standard input)\n|
  1084.           )
  1085.         end
  1086.         readlines.join(' ').gsub(/\n/n, '')
  1087.       end.gsub(/\\=/n, '%3D').gsub(/\\&/n, '%26')
  1088.  
  1089.       words = Shellwords.shellwords(string)
  1090.  
  1091.       if words.find{|x| /=/n.match(x) }
  1092.         words.join('&')
  1093.       else
  1094.         words.join('+')
  1095.       end
  1096.     end
  1097.     private :read_from_cmdline
  1098.  
  1099.     # Initialize the data from the query.
  1100.     #
  1101.     # Handles multipart forms (in particular, forms that involve file uploads).
  1102.     # Reads query parameters in the @params field, and cookies into @cookies.
  1103.     def initialize_query()
  1104.       if ("POST" == env_table['REQUEST_METHOD']) and
  1105.          %r|\Amultipart/form-data.*boundary=\"?([^\";,]+)\"?|n.match(env_table['CONTENT_TYPE'])
  1106.         boundary = $1.dup
  1107.         @multipart = true
  1108.         @params = read_multipart(boundary, Integer(env_table['CONTENT_LENGTH']))
  1109.       else
  1110.         @multipart = false
  1111.         @params = CGI::parse(
  1112.                     case env_table['REQUEST_METHOD']
  1113.                     when "GET", "HEAD"
  1114.                       if defined?(MOD_RUBY)
  1115.                         Apache::request.args or ""
  1116.                       else
  1117.                         env_table['QUERY_STRING'] or ""
  1118.                       end
  1119.                     when "POST"
  1120.                       stdinput.binmode if defined? stdinput.binmode
  1121.                       stdinput.read(Integer(env_table['CONTENT_LENGTH'])) or ''
  1122.                     else
  1123.                       read_from_cmdline
  1124.                     end
  1125.                   )
  1126.       end
  1127.  
  1128.       @cookies = CGI::Cookie::parse((env_table['HTTP_COOKIE'] or env_table['COOKIE']))
  1129.     end
  1130.     private :initialize_query
  1131.  
  1132.     def multipart?
  1133.       @multipart
  1134.     end
  1135.  
  1136.     module Value    # :nodoc:
  1137.       def set_params(params)
  1138.         @params = params
  1139.       end
  1140.       def [](idx, *args)
  1141.         if args.size == 0
  1142.           warn "#{caller(1)[0]}:CAUTION! cgi['key'] == cgi.params['key'][0]; if want Array, use cgi.params['key']"
  1143.           @params[idx]
  1144.         else
  1145.           super[idx,*args]
  1146.         end
  1147.       end
  1148.       def first
  1149.         warn "#{caller(1)[0]}:CAUTION! cgi['key'] == cgi.params['key'][0]; if want Array, use cgi.params['key']"
  1150.         self
  1151.       end
  1152.       alias last first
  1153.       def to_a
  1154.         @params || [self]
  1155.       end
  1156.       alias to_ary to_a       # to be rhs of multiple assignment
  1157.     end
  1158.  
  1159.     # Get the value for the parameter with a given key.
  1160.     #
  1161.     # If the parameter has multiple values, only the first will be 
  1162.     # retrieved; use #params() to get the array of values.
  1163.     def [](key)
  1164.       params = @params[key]
  1165.       value = params[0]
  1166.       if @multipart
  1167.         if value
  1168.           return value
  1169.         elsif defined? StringIO
  1170.           StringIO.new("")
  1171.         else
  1172.           Tempfile.new("CGI")
  1173.         end
  1174.       else
  1175.         str = if value then value.dup else "" end
  1176.         str.extend(Value)
  1177.         str.set_params(params)
  1178.         str
  1179.       end
  1180.     end
  1181.  
  1182.     # Return all parameter keys as an array.
  1183.     def keys(*args)
  1184.       @params.keys(*args)
  1185.     end
  1186.  
  1187.     # Returns true if a given parameter key exists in the query.
  1188.     def has_key?(*args)
  1189.       @params.has_key?(*args)
  1190.     end
  1191.     alias key? has_key?
  1192.     alias include? has_key?
  1193.  
  1194.   end # QueryExtension
  1195.  
  1196.  
  1197.   # Prettify (indent) an HTML string.
  1198.   #
  1199.   # +string+ is the HTML string to indent.  +shift+ is the indentation
  1200.   # unit to use; it defaults to two spaces.
  1201.   #
  1202.   #   print CGI::pretty("<HTML><BODY></BODY></HTML>")
  1203.   #     # <HTML>
  1204.   #     #   <BODY>
  1205.   #     #   </BODY>
  1206.   #     # </HTML>
  1207.   # 
  1208.   #   print CGI::pretty("<HTML><BODY></BODY></HTML>", "\t")
  1209.   #     # <HTML>
  1210.   #     #         <BODY>
  1211.   #     #         </BODY>
  1212.   #     # </HTML>
  1213.   #
  1214.   def CGI::pretty(string, shift = "  ")
  1215.     lines = string.gsub(/(?!\A)<(?:.|\n)*?>/n, "\n\\0").gsub(/<(?:.|\n)*?>(?!\n)/n, "\\0\n")
  1216.     end_pos = 0
  1217.     while end_pos = lines.index(/^<\/(\w+)/n, end_pos)
  1218.       element = $1.dup
  1219.       start_pos = lines.rindex(/^\s*<#{element}/ni, end_pos)
  1220.       lines[start_pos ... end_pos] = "__" + lines[start_pos ... end_pos].gsub(/\n(?!\z)/n, "\n" + shift) + "__"
  1221.     end
  1222.     lines.gsub(/^((?:#{Regexp::quote(shift)})*)__(?=<\/?\w)/n, '\1')
  1223.   end
  1224.  
  1225.  
  1226.   # Base module for HTML-generation mixins.
  1227.   #
  1228.   # Provides methods for code generation for tags following
  1229.   # the various DTD element types.
  1230.   module TagMaker # :nodoc:
  1231.  
  1232.     # Generate code for an element with required start and end tags.
  1233.     #
  1234.     #   - -
  1235.     def nn_element_def(element)
  1236.       nOE_element_def(element, <<-END)
  1237.           if block_given?
  1238.             yield.to_s
  1239.           else
  1240.             ""
  1241.           end +
  1242.           "</#{element.upcase}>"
  1243.       END
  1244.     end
  1245.  
  1246.     # Generate code for an empty element.
  1247.     #
  1248.     #   - O EMPTY
  1249.     def nOE_element_def(element, append = nil)
  1250.       s = <<-END
  1251.           "<#{element.upcase}" + attributes.collect{|name, value|
  1252.             next unless value
  1253.             " " + CGI::escapeHTML(name) +
  1254.             if true == value
  1255.               ""
  1256.             else
  1257.               '="' + CGI::escapeHTML(value) + '"'
  1258.             end
  1259.           }.to_s + ">"
  1260.       END
  1261.       s.sub!(/\Z/, " +") << append if append
  1262.       s
  1263.     end
  1264.  
  1265.     # Generate code for an element for which the end (and possibly the
  1266.     # start) tag is optional.
  1267.     #
  1268.     #   O O or - O
  1269.     def nO_element_def(element)
  1270.       nOE_element_def(element, <<-END)
  1271.           if block_given?
  1272.             yield.to_s + "</#{element.upcase}>"
  1273.           else
  1274.             ""
  1275.           end
  1276.       END
  1277.     end
  1278.  
  1279.   end # TagMaker
  1280.  
  1281.  
  1282.   #
  1283.   # Mixin module providing HTML generation methods.
  1284.   #
  1285.   # For example,
  1286.   #   cgi.a("http://www.example.com") { "Example" }
  1287.   #     # => "<A HREF=\"http://www.example.com\">Example</A>"
  1288.   #
  1289.   # Modules Http3, Http4, etc., contain more basic HTML-generation methods
  1290.   # (:title, :center, etc.).
  1291.   #
  1292.   # See class CGI for a detailed example. 
  1293.   #
  1294.   module HtmlExtension
  1295.  
  1296.  
  1297.     # Generate an Anchor element as a string.
  1298.     #
  1299.     # +href+ can either be a string, giving the URL
  1300.     # for the HREF attribute, or it can be a hash of
  1301.     # the element's attributes.
  1302.     #
  1303.     # The body of the element is the string returned by the no-argument
  1304.     # block passed in.
  1305.     #
  1306.     #   a("http://www.example.com") { "Example" }
  1307.     #     # => "<A HREF=\"http://www.example.com\">Example</A>"
  1308.     #
  1309.     #   a("HREF" => "http://www.example.com", "TARGET" => "_top") { "Example" }
  1310.     #     # => "<A HREF=\"http://www.example.com\" TARGET=\"_top\">Example</A>"
  1311.     #
  1312.     def a(href = "") # :yield:
  1313.       attributes = if href.kind_of?(String)
  1314.                      { "HREF" => href }
  1315.                    else
  1316.                      href
  1317.                    end
  1318.       if block_given?
  1319.         super(attributes){ yield }
  1320.       else
  1321.         super(attributes)
  1322.       end
  1323.     end
  1324.  
  1325.     # Generate a Document Base URI element as a String. 
  1326.     #
  1327.     # +href+ can either by a string, giving the base URL for the HREF
  1328.     # attribute, or it can be a has of the element's attributes.
  1329.     #
  1330.     # The passed-in no-argument block is ignored.
  1331.     #
  1332.     #   base("http://www.example.com/cgi")
  1333.     #     # => "<BASE HREF=\"http://www.example.com/cgi\">"
  1334.     def base(href = "") # :yield:
  1335.       attributes = if href.kind_of?(String)
  1336.                      { "HREF" => href }
  1337.                    else
  1338.                      href
  1339.                    end
  1340.       if block_given?
  1341.         super(attributes){ yield }
  1342.       else
  1343.         super(attributes)
  1344.       end
  1345.     end
  1346.  
  1347.     # Generate a BlockQuote element as a string.
  1348.     #
  1349.     # +cite+ can either be a string, give the URI for the source of
  1350.     # the quoted text, or a hash, giving all attributes of the element,
  1351.     # or it can be omitted, in which case the element has no attributes.
  1352.     #
  1353.     # The body is provided by the passed-in no-argument block
  1354.     #
  1355.     #   blockquote("http://www.example.com/quotes/foo.html") { "Foo!" }
  1356.     #     #=> "<BLOCKQUOTE CITE=\"http://www.example.com/quotes/foo.html\">Foo!</BLOCKQUOTE>
  1357.     def blockquote(cite = nil)  # :yield:
  1358.       attributes = if cite.kind_of?(String)
  1359.                      { "CITE" => cite }
  1360.                    else
  1361.                      cite or ""
  1362.                    end
  1363.       if block_given?
  1364.         super(attributes){ yield }
  1365.       else
  1366.         super(attributes)
  1367.       end
  1368.     end
  1369.  
  1370.  
  1371.     # Generate a Table Caption element as a string.
  1372.     #
  1373.     # +align+ can be a string, giving the alignment of the caption
  1374.     # (one of top, bottom, left, or right).  It can be a hash of
  1375.     # all the attributes of the element.  Or it can be omitted.
  1376.     #
  1377.     # The body of the element is provided by the passed-in no-argument block.
  1378.     #
  1379.     #   caption("left") { "Capital Cities" }
  1380.     #     # => <CAPTION ALIGN=\"left\">Capital Cities</CAPTION>
  1381.     def caption(align = nil) # :yield:
  1382.       attributes = if align.kind_of?(String)
  1383.                      { "ALIGN" => align }
  1384.                    else
  1385.                      align or ""
  1386.                    end
  1387.       if block_given?
  1388.         super(attributes){ yield }
  1389.       else
  1390.         super(attributes)
  1391.       end
  1392.     end
  1393.  
  1394.  
  1395.     # Generate a Checkbox Input element as a string.
  1396.     #
  1397.     # The attributes of the element can be specified as three arguments,
  1398.     # +name+, +value+, and +checked+.  +checked+ is a boolean value;
  1399.     # if true, the CHECKED attribute will be included in the element.
  1400.     #
  1401.     # Alternatively, the attributes can be specified as a hash.
  1402.     #
  1403.     #   checkbox("name")
  1404.     #     # = checkbox("NAME" => "name")
  1405.     # 
  1406.     #   checkbox("name", "value")
  1407.     #     # = checkbox("NAME" => "name", "VALUE" => "value")
  1408.     # 
  1409.     #   checkbox("name", "value", true)
  1410.     #     # = checkbox("NAME" => "name", "VALUE" => "value", "CHECKED" => true)
  1411.     def checkbox(name = "", value = nil, checked = nil)
  1412.       attributes = if name.kind_of?(String)
  1413.                      { "TYPE" => "checkbox", "NAME" => name,
  1414.                        "VALUE" => value, "CHECKED" => checked }
  1415.                    else
  1416.                      name["TYPE"] = "checkbox"
  1417.                      name
  1418.                    end
  1419.       input(attributes)
  1420.     end
  1421.  
  1422.     # Generate a sequence of checkbox elements, as a String.
  1423.     #
  1424.     # The checkboxes will all have the same +name+ attribute.
  1425.     # Each checkbox is followed by a label.
  1426.     # There will be one checkbox for each value.  Each value
  1427.     # can be specified as a String, which will be used both
  1428.     # as the value of the VALUE attribute and as the label
  1429.     # for that checkbox.  A single-element array has the
  1430.     # same effect.
  1431.     #
  1432.     # Each value can also be specified as a three-element array.
  1433.     # The first element is the VALUE attribute; the second is the
  1434.     # label; and the third is a boolean specifying whether this
  1435.     # checkbox is CHECKED.
  1436.     #
  1437.     # Each value can also be specified as a two-element
  1438.     # array, by omitting either the value element (defaults
  1439.     # to the same as the label), or the boolean checked element
  1440.     # (defaults to false).
  1441.     #
  1442.     #   checkbox_group("name", "foo", "bar", "baz")
  1443.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  1444.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="bar">bar
  1445.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz
  1446.     # 
  1447.     #   checkbox_group("name", ["foo"], ["bar", true], "baz")
  1448.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  1449.     #     # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="bar">bar
  1450.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz
  1451.     # 
  1452.     #   checkbox_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1453.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="1">Foo
  1454.     #     # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="2">Bar
  1455.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="Baz">Baz
  1456.     # 
  1457.     #   checkbox_group("NAME" => "name",
  1458.     #                    "VALUES" => ["foo", "bar", "baz"])
  1459.     # 
  1460.     #   checkbox_group("NAME" => "name",
  1461.     #                    "VALUES" => [["foo"], ["bar", true], "baz"])
  1462.     # 
  1463.     #   checkbox_group("NAME" => "name",
  1464.     #                    "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1465.     def checkbox_group(name = "", *values)
  1466.       if name.kind_of?(Hash)
  1467.         values = name["VALUES"]
  1468.         name = name["NAME"]
  1469.       end
  1470.       values.collect{|value|
  1471.         if value.kind_of?(String)
  1472.           checkbox(name, value) + value
  1473.         else
  1474.           if value[value.size - 1] == true
  1475.             checkbox(name, value[0], true) +
  1476.             value[value.size - 2]
  1477.           else
  1478.             checkbox(name, value[0]) +
  1479.             value[value.size - 1]
  1480.           end
  1481.         end
  1482.       }.to_s
  1483.     end
  1484.  
  1485.  
  1486.     # Generate an File Upload Input element as a string.
  1487.     #
  1488.     # The attributes of the element can be specified as three arguments,
  1489.     # +name+, +size+, and +maxlength+.  +maxlength+ is the maximum length
  1490.     # of the file's _name_, not of the file's _contents_.
  1491.     #
  1492.     # Alternatively, the attributes can be specified as a hash.
  1493.     #
  1494.     # See #multipart_form() for forms that include file uploads.
  1495.     #
  1496.     #   file_field("name")
  1497.     #     # <INPUT TYPE="file" NAME="name" SIZE="20">
  1498.     # 
  1499.     #   file_field("name", 40)
  1500.     #     # <INPUT TYPE="file" NAME="name" SIZE="40">
  1501.     # 
  1502.     #   file_field("name", 40, 100)
  1503.     #     # <INPUT TYPE="file" NAME="name" SIZE="40" MAXLENGTH="100">
  1504.     # 
  1505.     #   file_field("NAME" => "name", "SIZE" => 40)
  1506.     #     # <INPUT TYPE="file" NAME="name" SIZE="40">
  1507.     def file_field(name = "", size = 20, maxlength = nil)
  1508.       attributes = if name.kind_of?(String)
  1509.                      { "TYPE" => "file", "NAME" => name,
  1510.                        "SIZE" => size.to_s }
  1511.                    else
  1512.                      name["TYPE"] = "file"
  1513.                      name
  1514.                    end
  1515.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  1516.       input(attributes)
  1517.     end
  1518.  
  1519.  
  1520.     # Generate a Form element as a string.
  1521.     #
  1522.     # +method+ should be either "get" or "post", and defaults to the latter.
  1523.     # +action+ defaults to the current CGI script name.  +enctype+
  1524.     # defaults to "application/x-www-form-urlencoded".  
  1525.     #
  1526.     # Alternatively, the attributes can be specified as a hash.
  1527.     #
  1528.     # See also #multipart_form() for forms that include file uploads.
  1529.     #
  1530.     #   form{ "string" }
  1531.     #     # <FORM METHOD="post" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1532.     # 
  1533.     #   form("get") { "string" }
  1534.     #     # <FORM METHOD="get" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1535.     # 
  1536.     #   form("get", "url") { "string" }
  1537.     #     # <FORM METHOD="get" ACTION="url" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1538.     # 
  1539.     #   form("METHOD" => "post", "ENCTYPE" => "enctype") { "string" }
  1540.     #     # <FORM METHOD="post" ENCTYPE="enctype">string</FORM>
  1541.     def form(method = "post", action = script_name, enctype = "application/x-www-form-urlencoded")
  1542.       attributes = if method.kind_of?(String)
  1543.                      { "METHOD" => method, "ACTION" => action,
  1544.                        "ENCTYPE" => enctype } 
  1545.                    else
  1546.                      unless method.has_key?("METHOD")
  1547.                        method["METHOD"] = "post"
  1548.                      end
  1549.                      unless method.has_key?("ENCTYPE")
  1550.                        method["ENCTYPE"] = enctype
  1551.                      end
  1552.                      method
  1553.                    end
  1554.       if block_given?
  1555.         body = yield
  1556.       else
  1557.         body = ""
  1558.       end
  1559.       if @output_hidden
  1560.         body += @output_hidden.collect{|k,v|
  1561.           "<INPUT TYPE=\"HIDDEN\" NAME=\"#{k}\" VALUE=\"#{v}\">"
  1562.         }.to_s
  1563.       end
  1564.       super(attributes){body}
  1565.     end
  1566.  
  1567.     # Generate a Hidden Input element as a string.
  1568.     #
  1569.     # The attributes of the element can be specified as two arguments,
  1570.     # +name+ and +value+.
  1571.     #
  1572.     # Alternatively, the attributes can be specified as a hash.
  1573.     #
  1574.     #   hidden("name")
  1575.     #     # <INPUT TYPE="hidden" NAME="name">
  1576.     # 
  1577.     #   hidden("name", "value")
  1578.     #     # <INPUT TYPE="hidden" NAME="name" VALUE="value">
  1579.     # 
  1580.     #   hidden("NAME" => "name", "VALUE" => "reset", "ID" => "foo")
  1581.     #     # <INPUT TYPE="hidden" NAME="name" VALUE="value" ID="foo">
  1582.     def hidden(name = "", value = nil)
  1583.       attributes = if name.kind_of?(String)
  1584.                      { "TYPE" => "hidden", "NAME" => name, "VALUE" => value }
  1585.                    else
  1586.                      name["TYPE"] = "hidden"
  1587.                      name
  1588.                    end
  1589.       input(attributes)
  1590.     end
  1591.  
  1592.     # Generate a top-level HTML element as a string.
  1593.     #
  1594.     # The attributes of the element are specified as a hash.  The
  1595.     # pseudo-attribute "PRETTY" can be used to specify that the generated
  1596.     # HTML string should be indented.  "PRETTY" can also be specified as
  1597.     # a string as the sole argument to this method.  The pseudo-attribute
  1598.     # "DOCTYPE", if given, is used as the leading DOCTYPE SGML tag; it
  1599.     # should include the entire text of this tag, including angle brackets.
  1600.     #
  1601.     # The body of the html element is supplied as a block.
  1602.     # 
  1603.     #   html{ "string" }
  1604.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML>string</HTML>
  1605.     # 
  1606.     #   html("LANG" => "ja") { "string" }
  1607.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML LANG="ja">string</HTML>
  1608.     # 
  1609.     #   html("DOCTYPE" => false) { "string" }
  1610.     #     # <HTML>string</HTML>
  1611.     # 
  1612.     #   html("DOCTYPE" => '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">') { "string" }
  1613.     #     # <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"><HTML>string</HTML>
  1614.     # 
  1615.     #   html("PRETTY" => "  ") { "<BODY></BODY>" }
  1616.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  1617.     #     # <HTML>
  1618.     #     #   <BODY>
  1619.     #     #   </BODY>
  1620.     #     # </HTML>
  1621.     # 
  1622.     #   html("PRETTY" => "\t") { "<BODY></BODY>" }
  1623.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  1624.     #     # <HTML>
  1625.     #     #         <BODY>
  1626.     #     #         </BODY>
  1627.     #     # </HTML>
  1628.     # 
  1629.     #   html("PRETTY") { "<BODY></BODY>" }
  1630.     #     # = html("PRETTY" => "  ") { "<BODY></BODY>" }
  1631.     # 
  1632.     #   html(if $VERBOSE then "PRETTY" end) { "HTML string" }
  1633.     #
  1634.     def html(attributes = {}) # :yield:
  1635.       if nil == attributes
  1636.         attributes = {}
  1637.       elsif "PRETTY" == attributes
  1638.         attributes = { "PRETTY" => true }
  1639.       end
  1640.       pretty = attributes.delete("PRETTY")
  1641.       pretty = "  " if true == pretty
  1642.       buf = ""
  1643.  
  1644.       if attributes.has_key?("DOCTYPE")
  1645.         if attributes["DOCTYPE"]
  1646.           buf += attributes.delete("DOCTYPE")
  1647.         else
  1648.           attributes.delete("DOCTYPE")
  1649.         end
  1650.       else
  1651.         buf += doctype
  1652.       end
  1653.  
  1654.       if block_given?
  1655.         buf += super(attributes){ yield }
  1656.       else
  1657.         buf += super(attributes)
  1658.       end
  1659.  
  1660.       if pretty
  1661.         CGI::pretty(buf, pretty)
  1662.       else
  1663.         buf
  1664.       end
  1665.  
  1666.     end
  1667.  
  1668.     # Generate an Image Button Input element as a string.
  1669.     #
  1670.     # +src+ is the URL of the image to use for the button.  +name+ 
  1671.     # is the input name.  +alt+ is the alternative text for the image.
  1672.     #
  1673.     # Alternatively, the attributes can be specified as a hash.
  1674.     # 
  1675.     #   image_button("url")
  1676.     #     # <INPUT TYPE="image" SRC="url">
  1677.     # 
  1678.     #   image_button("url", "name", "string")
  1679.     #     # <INPUT TYPE="image" SRC="url" NAME="name" ALT="string">
  1680.     # 
  1681.     #   image_button("SRC" => "url", "ATL" => "strng")
  1682.     #     # <INPUT TYPE="image" SRC="url" ALT="string">
  1683.     def image_button(src = "", name = nil, alt = nil)
  1684.       attributes = if src.kind_of?(String)
  1685.                      { "TYPE" => "image", "SRC" => src, "NAME" => name,
  1686.                        "ALT" => alt }
  1687.                    else
  1688.                      src["TYPE"] = "image"
  1689.                      src["SRC"] ||= ""
  1690.                      src
  1691.                    end
  1692.       input(attributes)
  1693.     end
  1694.  
  1695.  
  1696.     # Generate an Image element as a string.
  1697.     #
  1698.     # +src+ is the URL of the image.  +alt+ is the alternative text for
  1699.     # the image.  +width+ is the width of the image, and +height+ is
  1700.     # its height.
  1701.     #
  1702.     # Alternatively, the attributes can be specified as a hash.
  1703.     #
  1704.     #   img("src", "alt", 100, 50)
  1705.     #     # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">
  1706.     # 
  1707.     #   img("SRC" => "src", "ALT" => "alt", "WIDTH" => 100, "HEIGHT" => 50)
  1708.     #     # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">
  1709.     def img(src = "", alt = "", width = nil, height = nil)
  1710.       attributes = if src.kind_of?(String)
  1711.                      { "SRC" => src, "ALT" => alt }
  1712.                    else
  1713.                      src
  1714.                    end
  1715.       attributes["WIDTH"] = width.to_s if width
  1716.       attributes["HEIGHT"] = height.to_s if height
  1717.       super(attributes)
  1718.     end
  1719.  
  1720.  
  1721.     # Generate a Form element with multipart encoding as a String.
  1722.     #
  1723.     # Multipart encoding is used for forms that include file uploads.
  1724.     #
  1725.     # +action+ is the action to perform.  +enctype+ is the encoding
  1726.     # type, which defaults to "multipart/form-data".
  1727.     #
  1728.     # Alternatively, the attributes can be specified as a hash.
  1729.     #
  1730.     #   multipart_form{ "string" }
  1731.     #     # <FORM METHOD="post" ENCTYPE="multipart/form-data">string</FORM>
  1732.     # 
  1733.     #   multipart_form("url") { "string" }
  1734.     #     # <FORM METHOD="post" ACTION="url" ENCTYPE="multipart/form-data">string</FORM>
  1735.     def multipart_form(action = nil, enctype = "multipart/form-data")
  1736.       attributes = if action == nil
  1737.                      { "METHOD" => "post", "ENCTYPE" => enctype } 
  1738.                    elsif action.kind_of?(String)
  1739.                      { "METHOD" => "post", "ACTION" => action,
  1740.                        "ENCTYPE" => enctype } 
  1741.                    else
  1742.                      unless action.has_key?("METHOD")
  1743.                        action["METHOD"] = "post"
  1744.                      end
  1745.                      unless action.has_key?("ENCTYPE")
  1746.                        action["ENCTYPE"] = enctype
  1747.                      end
  1748.                      action
  1749.                    end
  1750.       if block_given?
  1751.         form(attributes){ yield }
  1752.       else
  1753.         form(attributes)
  1754.       end
  1755.     end
  1756.  
  1757.  
  1758.     # Generate a Password Input element as a string.
  1759.     #
  1760.     # +name+ is the name of the input field.  +value+ is its default
  1761.     # value.  +size+ is the size of the input field display.  +maxlength+
  1762.     # is the maximum length of the inputted password.
  1763.     #
  1764.     # Alternatively, attributes can be specified as a hash.
  1765.     #
  1766.     #   password_field("name")
  1767.     #     # <INPUT TYPE="password" NAME="name" SIZE="40">
  1768.     # 
  1769.     #   password_field("name", "value")
  1770.     #     # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="40">
  1771.     # 
  1772.     #   password_field("password", "value", 80, 200)
  1773.     #     # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">
  1774.     # 
  1775.     #   password_field("NAME" => "name", "VALUE" => "value")
  1776.     #     # <INPUT TYPE="password" NAME="name" VALUE="value">
  1777.     def password_field(name = "", value = nil, size = 40, maxlength = nil)
  1778.       attributes = if name.kind_of?(String)
  1779.                      { "TYPE" => "password", "NAME" => name,
  1780.                        "VALUE" => value, "SIZE" => size.to_s }
  1781.                    else
  1782.                      name["TYPE"] = "password"
  1783.                      name
  1784.                    end
  1785.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  1786.       input(attributes)
  1787.     end
  1788.  
  1789.     # Generate a Select element as a string.
  1790.     #
  1791.     # +name+ is the name of the element.  The +values+ are the options that
  1792.     # can be selected from the Select menu.  Each value can be a String or
  1793.     # a one, two, or three-element Array.  If a String or a one-element
  1794.     # Array, this is both the value of that option and the text displayed for
  1795.     # it.  If a three-element Array, the elements are the option value, displayed
  1796.     # text, and a boolean value specifying whether this option starts as selected.
  1797.     # The two-element version omits either the option value (defaults to the same
  1798.     # as the display text) or the boolean selected specifier (defaults to false).
  1799.     #
  1800.     # The attributes and options can also be specified as a hash.  In this
  1801.     # case, options are specified as an array of values as described above,
  1802.     # with the hash key of "VALUES".
  1803.     #
  1804.     #   popup_menu("name", "foo", "bar", "baz")
  1805.     #     # <SELECT NAME="name">
  1806.     #     #   <OPTION VALUE="foo">foo</OPTION>
  1807.     #     #   <OPTION VALUE="bar">bar</OPTION>
  1808.     #     #   <OPTION VALUE="baz">baz</OPTION>
  1809.     #     # </SELECT>
  1810.     # 
  1811.     #   popup_menu("name", ["foo"], ["bar", true], "baz")
  1812.     #     # <SELECT NAME="name">
  1813.     #     #   <OPTION VALUE="foo">foo</OPTION>
  1814.     #     #   <OPTION VALUE="bar" SELECTED>bar</OPTION>
  1815.     #     #   <OPTION VALUE="baz">baz</OPTION>
  1816.     #     # </SELECT>
  1817.     # 
  1818.     #   popup_menu("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1819.     #     # <SELECT NAME="name">
  1820.     #     #   <OPTION VALUE="1">Foo</OPTION>
  1821.     #     #   <OPTION SELECTED VALUE="2">Bar</OPTION>
  1822.     #     #   <OPTION VALUE="Baz">Baz</OPTION>
  1823.     #     # </SELECT>
  1824.     # 
  1825.     #   popup_menu("NAME" => "name", "SIZE" => 2, "MULTIPLE" => true,
  1826.     #               "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1827.     #     # <SELECT NAME="name" MULTIPLE SIZE="2">
  1828.     #     #   <OPTION VALUE="1">Foo</OPTION>
  1829.     #     #   <OPTION SELECTED VALUE="2">Bar</OPTION>
  1830.     #     #   <OPTION VALUE="Baz">Baz</OPTION>
  1831.     #     # </SELECT>
  1832.     def popup_menu(name = "", *values)
  1833.  
  1834.       if name.kind_of?(Hash)
  1835.         values   = name["VALUES"]
  1836.         size     = name["SIZE"].to_s if name["SIZE"]
  1837.         multiple = name["MULTIPLE"]
  1838.         name     = name["NAME"]
  1839.       else
  1840.         size = nil
  1841.         multiple = nil
  1842.       end
  1843.  
  1844.       select({ "NAME" => name, "SIZE" => size,
  1845.                "MULTIPLE" => multiple }){
  1846.         values.collect{|value|
  1847.           if value.kind_of?(String)
  1848.             option({ "VALUE" => value }){ value }
  1849.           else
  1850.             if value[value.size - 1] == true
  1851.               option({ "VALUE" => value[0], "SELECTED" => true }){
  1852.                 value[value.size - 2]
  1853.               }
  1854.             else
  1855.               option({ "VALUE" => value[0] }){
  1856.                 value[value.size - 1]
  1857.               }
  1858.             end
  1859.           end
  1860.         }.to_s
  1861.       }
  1862.  
  1863.     end
  1864.  
  1865.     # Generates a radio-button Input element.
  1866.     #
  1867.     # +name+ is the name of the input field.  +value+ is the value of
  1868.     # the field if checked.  +checked+ specifies whether the field
  1869.     # starts off checked.
  1870.     #
  1871.     # Alternatively, the attributes can be specified as a hash.
  1872.     #
  1873.     #   radio_button("name", "value")
  1874.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value">
  1875.     # 
  1876.     #   radio_button("name", "value", true)
  1877.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value" CHECKED>
  1878.     # 
  1879.     #   radio_button("NAME" => "name", "VALUE" => "value", "ID" => "foo")
  1880.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value" ID="foo">
  1881.     def radio_button(name = "", value = nil, checked = nil)
  1882.       attributes = if name.kind_of?(String)
  1883.                      { "TYPE" => "radio", "NAME" => name,
  1884.                        "VALUE" => value, "CHECKED" => checked }
  1885.                    else
  1886.                      name["TYPE"] = "radio"
  1887.                      name
  1888.                    end
  1889.       input(attributes)
  1890.     end
  1891.  
  1892.     # Generate a sequence of radio button Input elements, as a String.
  1893.     #
  1894.     # This works the same as #checkbox_group().  However, it is not valid
  1895.     # to have more than one radiobutton in a group checked.
  1896.     # 
  1897.     #   radio_group("name", "foo", "bar", "baz")
  1898.     #     # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  1899.     #     # <INPUT TYPE="radio" NAME="name" VALUE="bar">bar
  1900.     #     # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz
  1901.     # 
  1902.     #   radio_group("name", ["foo"], ["bar", true], "baz")
  1903.     #     # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  1904.     #     # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="bar">bar
  1905.     #     # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz
  1906.     # 
  1907.     #   radio_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1908.     #     # <INPUT TYPE="radio" NAME="name" VALUE="1">Foo
  1909.     #     # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="2">Bar
  1910.     #     # <INPUT TYPE="radio" NAME="name" VALUE="Baz">Baz
  1911.     # 
  1912.     #   radio_group("NAME" => "name",
  1913.     #                 "VALUES" => ["foo", "bar", "baz"])
  1914.     # 
  1915.     #   radio_group("NAME" => "name",
  1916.     #                 "VALUES" => [["foo"], ["bar", true], "baz"])
  1917.     # 
  1918.     #   radio_group("NAME" => "name",
  1919.     #                 "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1920.     def radio_group(name = "", *values)
  1921.       if name.kind_of?(Hash)
  1922.         values = name["VALUES"]
  1923.         name = name["NAME"]
  1924.       end
  1925.       values.collect{|value|
  1926.         if value.kind_of?(String)
  1927.           radio_button(name, value) + value
  1928.         else
  1929.           if value[value.size - 1] == true
  1930.             radio_button(name, value[0], true) +
  1931.             value[value.size - 2]
  1932.           else
  1933.             radio_button(name, value[0]) +
  1934.             value[value.size - 1]
  1935.           end
  1936.         end
  1937.       }.to_s
  1938.     end
  1939.  
  1940.     # Generate a reset button Input element, as a String.
  1941.     #
  1942.     # This resets the values on a form to their initial values.  +value+
  1943.     # is the text displayed on the button. +name+ is the name of this button.
  1944.     #
  1945.     # Alternatively, the attributes can be specified as a hash.
  1946.     #
  1947.     #   reset
  1948.     #     # <INPUT TYPE="reset">
  1949.     # 
  1950.     #   reset("reset")
  1951.     #     # <INPUT TYPE="reset" VALUE="reset">
  1952.     # 
  1953.     #   reset("VALUE" => "reset", "ID" => "foo")
  1954.     #     # <INPUT TYPE="reset" VALUE="reset" ID="foo">
  1955.     def reset(value = nil, name = nil)
  1956.       attributes = if (not value) or value.kind_of?(String)
  1957.                      { "TYPE" => "reset", "VALUE" => value, "NAME" => name }
  1958.                    else
  1959.                      value["TYPE"] = "reset"
  1960.                      value
  1961.                    end
  1962.       input(attributes)
  1963.     end
  1964.  
  1965.     alias scrolling_list popup_menu
  1966.  
  1967.     # Generate a submit button Input element, as a String.
  1968.     #
  1969.     # +value+ is the text to display on the button.  +name+ is the name
  1970.     # of the input.
  1971.     #
  1972.     # Alternatively, the attributes can be specified as a hash.
  1973.     #
  1974.     #   submit
  1975.     #     # <INPUT TYPE="submit">
  1976.     # 
  1977.     #   submit("ok")
  1978.     #     # <INPUT TYPE="submit" VALUE="ok">
  1979.     # 
  1980.     #   submit("ok", "button1")
  1981.     #     # <INPUT TYPE="submit" VALUE="ok" NAME="button1">
  1982.     # 
  1983.     #   submit("VALUE" => "ok", "NAME" => "button1", "ID" => "foo")
  1984.     #     # <INPUT TYPE="submit" VALUE="ok" NAME="button1" ID="foo">
  1985.     def submit(value = nil, name = nil)
  1986.       attributes = if (not value) or value.kind_of?(String)
  1987.                      { "TYPE" => "submit", "VALUE" => value, "NAME" => name }
  1988.                    else
  1989.                      value["TYPE"] = "submit"
  1990.                      value
  1991.                    end
  1992.       input(attributes)
  1993.     end
  1994.  
  1995.     # Generate a text field Input element, as a String.
  1996.     #
  1997.     # +name+ is the name of the input field.  +value+ is its initial
  1998.     # value.  +size+ is the size of the input area.  +maxlength+
  1999.     # is the maximum length of input accepted.
  2000.     #
  2001.     # Alternatively, the attributes can be specified as a hash.
  2002.     #
  2003.     #   text_field("name")
  2004.     #     # <INPUT TYPE="text" NAME="name" SIZE="40">
  2005.     # 
  2006.     #   text_field("name", "value")
  2007.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="40">
  2008.     # 
  2009.     #   text_field("name", "value", 80)
  2010.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80">
  2011.     # 
  2012.     #   text_field("name", "value", 80, 200)
  2013.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">
  2014.     # 
  2015.     #   text_field("NAME" => "name", "VALUE" => "value")
  2016.     #     # <INPUT TYPE="text" NAME="name" VALUE="value">
  2017.     def text_field(name = "", value = nil, size = 40, maxlength = nil)
  2018.       attributes = if name.kind_of?(String)
  2019.                      { "TYPE" => "text", "NAME" => name, "VALUE" => value,
  2020.                        "SIZE" => size.to_s }
  2021.                    else
  2022.                      name["TYPE"] = "text"
  2023.                      name
  2024.                    end
  2025.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  2026.       input(attributes)
  2027.     end
  2028.  
  2029.     # Generate a TextArea element, as a String.
  2030.     #
  2031.     # +name+ is the name of the textarea.  +cols+ is the number of
  2032.     # columns and +rows+ is the number of rows in the display.
  2033.     #
  2034.     # Alternatively, the attributes can be specified as a hash.
  2035.     #
  2036.     # The body is provided by the passed-in no-argument block
  2037.     #
  2038.     #   textarea("name")
  2039.     #      # = textarea("NAME" => "name", "COLS" => 70, "ROWS" => 10)
  2040.     #
  2041.     #   textarea("name", 40, 5)
  2042.     #      # = textarea("NAME" => "name", "COLS" => 40, "ROWS" => 5)
  2043.     def textarea(name = "", cols = 70, rows = 10)  # :yield:
  2044.       attributes = if name.kind_of?(String)
  2045.                      { "NAME" => name, "COLS" => cols.to_s,
  2046.                        "ROWS" => rows.to_s }
  2047.                    else
  2048.                      name
  2049.                    end
  2050.       if block_given?
  2051.         super(attributes){ yield }
  2052.       else
  2053.         super(attributes)
  2054.       end
  2055.     end
  2056.  
  2057.   end # HtmlExtension
  2058.  
  2059.  
  2060.   # Mixin module for HTML version 3 generation methods.
  2061.   module Html3 # :nodoc:
  2062.  
  2063.     # The DOCTYPE declaration for this version of HTML
  2064.     def doctype
  2065.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">|
  2066.     end
  2067.  
  2068.     # Initialise the HTML generation methods for this version.
  2069.     def element_init
  2070.       extend TagMaker
  2071.       methods = ""
  2072.       # - -
  2073.       for element in %w[ A TT I B U STRIKE BIG SMALL SUB SUP EM STRONG
  2074.           DFN CODE SAMP KBD VAR CITE FONT ADDRESS DIV center MAP
  2075.           APPLET PRE XMP LISTING DL OL UL DIR MENU SELECT table TITLE
  2076.           STYLE SCRIPT H1 H2 H3 H4 H5 H6 TEXTAREA FORM BLOCKQUOTE
  2077.           CAPTION ]
  2078.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2079.           def #{element.downcase}(attributes = {})
  2080.         BEGIN
  2081.           end
  2082.         END
  2083.       end
  2084.  
  2085.       # - O EMPTY
  2086.       for element in %w[ IMG BASE BASEFONT BR AREA LINK PARAM HR INPUT
  2087.           ISINDEX META ]
  2088.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2089.           def #{element.downcase}(attributes = {})
  2090.         BEGIN
  2091.           end
  2092.         END
  2093.       end
  2094.  
  2095.       # O O or - O
  2096.       for element in %w[ HTML HEAD BODY P PLAINTEXT DT DD LI OPTION tr
  2097.           th td ]
  2098.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2099.           def #{element.downcase}(attributes = {})
  2100.         BEGIN
  2101.           end
  2102.         END
  2103.       end
  2104.       eval(methods)
  2105.     end
  2106.  
  2107.   end # Html3
  2108.  
  2109.  
  2110.   # Mixin module for HTML version 4 generation methods.
  2111.   module Html4 # :nodoc:
  2112.  
  2113.     # The DOCTYPE declaration for this version of HTML
  2114.     def doctype
  2115.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">|
  2116.     end
  2117.  
  2118.     # Initialise the HTML generation methods for this version.
  2119.     def element_init
  2120.       extend TagMaker
  2121.       methods = ""
  2122.       # - -
  2123.       for element in %w[ TT I B BIG SMALL EM STRONG DFN CODE SAMP KBD
  2124.         VAR CITE ABBR ACRONYM SUB SUP SPAN BDO ADDRESS DIV MAP OBJECT
  2125.         H1 H2 H3 H4 H5 H6 PRE Q INS DEL DL OL UL LABEL SELECT OPTGROUP
  2126.         FIELDSET LEGEND BUTTON TABLE TITLE STYLE SCRIPT NOSCRIPT
  2127.         TEXTAREA FORM A BLOCKQUOTE CAPTION ]
  2128.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2129.           def #{element.downcase}(attributes = {})
  2130.         BEGIN
  2131.           end
  2132.         END
  2133.       end
  2134.  
  2135.       # - O EMPTY
  2136.       for element in %w[ IMG BASE BR AREA LINK PARAM HR INPUT COL META ]
  2137.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2138.           def #{element.downcase}(attributes = {})
  2139.         BEGIN
  2140.           end
  2141.         END
  2142.       end
  2143.  
  2144.       # O O or - O
  2145.       for element in %w[ HTML BODY P DT DD LI OPTION THEAD TFOOT TBODY
  2146.           COLGROUP TR TH TD HEAD]
  2147.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2148.           def #{element.downcase}(attributes = {})
  2149.         BEGIN
  2150.           end
  2151.         END
  2152.       end
  2153.       eval(methods)
  2154.     end
  2155.  
  2156.   end # Html4
  2157.  
  2158.  
  2159.   # Mixin module for HTML version 4 transitional generation methods.
  2160.   module Html4Tr # :nodoc:
  2161.  
  2162.     # The DOCTYPE declaration for this version of HTML
  2163.     def doctype
  2164.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">|
  2165.     end
  2166.  
  2167.     # Initialise the HTML generation methods for this version.
  2168.     def element_init
  2169.       extend TagMaker
  2170.       methods = ""
  2171.       # - -
  2172.       for element in %w[ TT I B U S STRIKE BIG SMALL EM STRONG DFN
  2173.           CODE SAMP KBD VAR CITE ABBR ACRONYM FONT SUB SUP SPAN BDO
  2174.           ADDRESS DIV CENTER MAP OBJECT APPLET H1 H2 H3 H4 H5 H6 PRE Q
  2175.           INS DEL DL OL UL DIR MENU LABEL SELECT OPTGROUP FIELDSET
  2176.           LEGEND BUTTON TABLE IFRAME NOFRAMES TITLE STYLE SCRIPT
  2177.           NOSCRIPT TEXTAREA FORM A BLOCKQUOTE CAPTION ]
  2178.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2179.           def #{element.downcase}(attributes = {})
  2180.         BEGIN
  2181.           end
  2182.         END
  2183.       end
  2184.  
  2185.       # - O EMPTY
  2186.       for element in %w[ IMG BASE BASEFONT BR AREA LINK PARAM HR INPUT
  2187.           COL ISINDEX META ]
  2188.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2189.           def #{element.downcase}(attributes = {})
  2190.         BEGIN
  2191.           end
  2192.         END
  2193.       end
  2194.  
  2195.       # O O or - O
  2196.       for element in %w[ HTML BODY P DT DD LI OPTION THEAD TFOOT TBODY
  2197.           COLGROUP TR TH TD HEAD ]
  2198.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2199.           def #{element.downcase}(attributes = {})
  2200.         BEGIN
  2201.           end
  2202.         END
  2203.       end
  2204.       eval(methods)
  2205.     end
  2206.  
  2207.   end # Html4Tr
  2208.  
  2209.  
  2210.   # Mixin module for generating HTML version 4 with framesets.
  2211.   module Html4Fr # :nodoc:
  2212.  
  2213.     # The DOCTYPE declaration for this version of HTML
  2214.     def doctype
  2215.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">|
  2216.     end
  2217.  
  2218.     # Initialise the HTML generation methods for this version.
  2219.     def element_init
  2220.       methods = ""
  2221.       # - -
  2222.       for element in %w[ FRAMESET ]
  2223.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2224.           def #{element.downcase}(attributes = {})
  2225.         BEGIN
  2226.           end
  2227.         END
  2228.       end
  2229.  
  2230.       # - O EMPTY
  2231.       for element in %w[ FRAME ]
  2232.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2233.           def #{element.downcase}(attributes = {})
  2234.         BEGIN
  2235.           end
  2236.         END
  2237.       end
  2238.       eval(methods)
  2239.     end
  2240.  
  2241.   end # Html4Fr
  2242.  
  2243.  
  2244.   # Creates a new CGI instance.
  2245.   #
  2246.   # +type+ specifies which version of HTML to load the HTML generation
  2247.   # methods for.  The following versions of HTML are supported:
  2248.   #
  2249.   # html3:: HTML 3.x
  2250.   # html4:: HTML 4.0
  2251.   # html4Tr:: HTML 4.0 Transitional
  2252.   # html4Fr:: HTML 4.0 with Framesets
  2253.   #
  2254.   # If not specified, no HTML generation methods will be loaded.
  2255.   #
  2256.   # If the CGI object is not created in a standard CGI call environment
  2257.   # (that is, it can't locate REQUEST_METHOD in its environment), then
  2258.   # it will run in "offline" mode.  In this mode, it reads its parameters
  2259.   # from the command line or (failing that) from standard input.  Otherwise,
  2260.   # cookies and other parameters are parsed automatically from the standard
  2261.   # CGI locations, which varies according to the REQUEST_METHOD.
  2262.   def initialize(type = "query")
  2263.     if defined?(MOD_RUBY) && !ENV.key?("GATEWAY_INTERFACE")
  2264.       Apache.request.setup_cgi_env
  2265.     end
  2266.  
  2267.     extend QueryExtension
  2268.     @multipart = false
  2269.     if defined?(CGI_PARAMS)
  2270.       warn "do not use CGI_PARAMS and CGI_COOKIES"
  2271.       @params = CGI_PARAMS.dup
  2272.       @cookies = CGI_COOKIES.dup
  2273.     else
  2274.       initialize_query()  # set @params, @cookies
  2275.     end
  2276.     @output_cookies = nil
  2277.     @output_hidden = nil
  2278.  
  2279.     case type
  2280.     when "html3"
  2281.       extend Html3
  2282.       element_init()
  2283.       extend HtmlExtension
  2284.     when "html4"
  2285.       extend Html4
  2286.       element_init()
  2287.       extend HtmlExtension
  2288.     when "html4Tr"
  2289.       extend Html4Tr
  2290.       element_init()
  2291.       extend HtmlExtension
  2292.     when "html4Fr"
  2293.       extend Html4Tr
  2294.       element_init()
  2295.       extend Html4Fr
  2296.       element_init()
  2297.       extend HtmlExtension
  2298.     end
  2299.   end
  2300.  
  2301. end   # class CGI
  2302.