Maintenance of Ruby 2.0.0 ended on February 24, 2016. Read more
Object
The Common Gateway Interface (CGI) is a simple protocol for passing an HTTP request from a web server to a standalone program, and returning the output to the web browser. Basically, a CGI program is called with the parameters of the request passed in either in the environment (GET) or via $stdin (POST), and everything it prints to $stdout is returned to the client.
This file holds the CGI class. This class provides functionality for retrieving HTTP request parameters, managing cookies, and generating HTML output.
The file CGI::Session provides session management functionality; see that class for more details.
See www.w3.org/CGI/ for more information on the CGI protocol.
CGI is a large class, providing several categories of methods, many of which are mixed in from other modules. Some of the documentation is in this class, some in the modules CGI::QueryExtension and CGI::HtmlExtension. See CGI::Cookie for specific information on handling cookies, and cgi/session.rb (CGI::Session) for information on sessions.
For queries, CGI provides methods to get at environmental variables, parameters, cookies, and multipart request data. For responses, CGI provides methods for writing output and generating HTML.
Read on for more details. Examples are provided at the bottom.
The CGI class dynamically mixes in parameter and cookie-parsing functionality, environmental variable access, and support for parsing multipart requests (including uploaded files) from the CGI::QueryExtension module.
The standard CGI environmental variables are available as read-only attributes of a CGI object. The following is a list of these variables:
AUTH_TYPE HTTP_HOST REMOTE_IDENT CONTENT_LENGTH HTTP_NEGOTIATE REMOTE_USER CONTENT_TYPE HTTP_PRAGMA REQUEST_METHOD GATEWAY_INTERFACE HTTP_REFERER SCRIPT_NAME HTTP_ACCEPT HTTP_USER_AGENT SERVER_NAME HTTP_ACCEPT_CHARSET PATH_INFO SERVER_PORT HTTP_ACCEPT_ENCODING PATH_TRANSLATED SERVER_PROTOCOL HTTP_ACCEPT_LANGUAGE QUERY_STRING SERVER_SOFTWARE HTTP_CACHE_CONTROL REMOTE_ADDR HTTP_FROM REMOTE_HOST
For each of these variables, there is a corresponding attribute with the
same name, except all lower case and without a preceding HTTP_.
content_length
and server_port
are integers; the
rest are strings.
The method params() returns a hash of all parameters in the request as name/value-list pairs, where the value-list is an Array of one or more values. The CGI object itself also behaves as a hash of parameter names to values, but only returns a single value (as a String) for each parameter name.
For instance, suppose the request contains the parameter “favourite_colours” with the multiple values “blue” and “green”. The following behaviour would occur:
cgi.params["favourite_colours"] # => ["blue", "green"] cgi["favourite_colours"] # => "blue"
If a parameter does not exist, the former method will return an empty array, the latter an empty string. The simplest way to test for existence of a parameter is by the has_key? method.
HTTP Cookies are automatically parsed from the request. They are available from the cookies() accessor, which returns a hash from cookie name to CGI::Cookie object.
If a request's method is POST and its content type is multipart/form-data, then it may contain uploaded files. These are stored by the QueryExtension module in the parameters of the request. The parameter name is the name attribute of the file input field, as usual. However, the value is not a string, but an IO object, either an IOString for small files, or a Tempfile for larger ones. This object also has the additional singleton methods:
the path of the uploaded file on the local filesystem
the name of the file on the client computer
the content type of the file
The CGI class provides methods for sending header and content output to the HTTP client, and mixes in methods for programmatic HTML generation from CGI::HtmlExtension and CGI::TagMaker modules. The precise version of HTML to use for HTML generation is specified at object creation time.
The simplest way to send output to the HTTP client is using the out() method. This takes the HTTP headers as a hash parameter, and the body content via a block. The headers can be generated as a string using the http_header() method. The output stream can be written directly to using the print() method.
Each HTML element has a corresponding method for generating that element as a String. The name of this method is the same as that of the element, all lowercase. The attributes of the element are passed in as a hash, and the body as a no-argument block that evaluates to a String. The HTML generation module knows which elements are always empty, and silently drops any passed-in body. It also knows which elements require matching closing tags and which don't. However, it does not know what attributes are legal for which elements.
There are also some additional HTML generation methods mixed in from the CGI::HtmlExtension module. These include individual methods for the different types of form inputs, and methods for elements that commonly take particular attributes where the attributes can be directly specified as arguments, rather than via a hash.
require "cgi" cgi = CGI.new value = cgi['field_name'] # <== value string for 'field_name' # if not 'field_name' included, then return "". fields = cgi.keys # <== array of field names # returns true if form has 'field_name' cgi.has_key?('field_name') cgi.has_key?('field_name') cgi.include?('field_name')
CAUTION! cgi returned an Array with the old cgi.rb(included in ruby 1.6)
require "cgi" cgi = CGI.new params = cgi.params
cgi.params is a hash.
cgi.params['new_field_name'] = ["value"] # add new param cgi.params['field_name'] = ["new_value"] # change value cgi.params.delete('field_name') # delete param cgi.params.clear # delete all params
require "pstore" db = PStore.new("query.db") db.transaction do db["params"] = cgi.params end
require "pstore" db = PStore.new("query.db") db.transaction do cgi.params = db["params"] end
require "cgi" cgi = CGI.new value = cgi['field_name'] # <== value string for 'field_name' value.read # <== body of value value.local_path # <== path to local file of value value.original_filename # <== original filename of value value.content_type # <== content_type of value
and value has StringIO or Tempfile class methods.
require "cgi" cgi = CGI.new values = cgi.cookies['name'] # <== array of 'name' # if not 'name' included, then return []. names = cgi.cookies.keys # <== array of cookie names
and cgi.cookies is a hash.
require "cgi" cgi = CGI.new for name, cookie in cgi.cookies cookie.expires = Time.now + 30 end cgi.out("cookie" => cgi.cookies) {"string"} cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... } require "cgi" cgi = CGI.new cgi.cookies['name'].expires = Time.now + 30 cgi.out("cookie" => cgi.cookies['name']) {"string"}
require "cgi" cgi = CGI.new("html4") # add HTML generation methods cgi.out do cgi.html do cgi.head do cgi.title { "TITLE" } end + cgi.body do cgi.form("ACTION" => "uri") do cgi.p do cgi.textarea("get_text") + cgi.br + cgi.submit end end + cgi.pre do CGI::escapeHTML( "params: #{cgi.params.inspect}\n" + "cookies: #{cgi.cookies.inspect}\n" + ENV.collect do |key, value| "#{key} --> #{value}\n" end.join("") ) end end end end # add HTML generation methods CGI.new("html3") # html3.2 CGI.new("html4") # html4.01 (Strict) CGI.new("html4Tr") # html4.01 Transitional CGI.new("html4Fr") # html4.01 Frameset CGI.new("html5") # html5
String for carriage return
Standard internet newline sequence
HTTP status codes.
String for linefeed
Maximum number of request parameters when multipart
Maximum content length of multipart data
Whether processing will be required in binary vs text
Path separators in different environments.
Abbreviated day-of-week names specified by RFC 822
Abbreviated month names specified by RFC 822
The set of special characters and their escaped values
Return the accept character set for all new CGI instances.
# File cgi/core.rb, line 742 def self.accept_charset @@accept_charset end
Set the accept character set for all new CGI instances.
# File cgi/core.rb, line 747 def self.accept_charset=(accept_charset) @@accept_charset=accept_charset end
URL-encode a string.
url_encoded_string = CGI::escape("'Stop!' said Fred") # => "%27Stop%21%27+said+Fred"
# File cgi/util.rb, line 6 def CGI::escape(string) encoding = string.encoding string.dup.force_encoding('ASCII-8BIT').gsub(/([^ a-zA-Z0-9_.-]+)/) do '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase end.tr(' ', '+').force_encoding(encoding) end
Escape only the tags of certain HTML elements in string
.
Takes an element or elements or array of elements. Each element is specified by the name of the element, without angle brackets. This matches both the start and the end tag of that element. The attribute list of the open tag will also be escaped (for instance, the double-quotes surrounding attribute values).
print CGI::escapeElement('<BR><A HREF="url"></A>', "A", "IMG") # "<BR><A HREF="url"></A>" print CGI::escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"]) # "<BR><A HREF="url"></A>"
# File cgi/util.rb, line 113 def CGI::escapeElement(string, *elements) elements = elements[0] if elements[0].kind_of?(Array) unless elements.empty? string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/i) do CGI::escapeHTML($&) end else string end end
Escape special characters in HTML, namely &"<>
CGI::escapeHTML('Usage: foo "bar" <baz>') # => "Usage: foo "bar" <baz>"
# File cgi/util.rb, line 35 def CGI::escapeHTML(string) string.gsub(/['&\"<>]/, TABLE_FOR_ESCAPE_HTML__) end
Synonym for ::escapeElement
# File cgi/util.rb, line 145 def CGI::escape_element(str) escapeElement(str) end
Synonym for ::escapeHTML
# File cgi/util.rb, line 91 def CGI::escape_html(str) escapeHTML(str) end
Create a new CGI instance.
tag_maker
This is the same as using the options_hash
form with the value
{ :tag_maker => tag_maker }
Note that it is recommended to
use the options_hash
form, since it also allows you specify
the charset you will accept.
options_hash
A Hash that recognizes two options:
:accept_charset
specifies encoding of received query string. If omitted,
@@accept_charset
is used. If the encoding is not valid, a CGI::InvalidEncoding will be raised.
Example. Suppose @@accept_charset
is “UTF-8”
when not specified:
cgi=CGI.new # @accept_charset # => "UTF-8"
when specified as “EUC-JP”:
cgi=CGI.new(:accept_charset => "EUC-JP") # => "EUC-JP"
:tag_maker
String that specifies which version of the HTML generation methods to use. If not specified, no HTML generation methods will be loaded.
The following values are supported:
HTML 3.x
HTML 4.0
HTML 4.0 Transitional
HTML 4.0 with Framesets
HTML 5
block
If provided, the block is called when an invalid encoding is encountered. For example:
encoding_errors={} cgi=CGI.new(:accept_charset=>"EUC-JP") do |name,value| encoding_errors[name] = value end
Finally, if the CGI object is not created in a standard CGI call environment (that is, it can't locate REQUEST_METHOD in its environment), then it will run in “offline” mode. In this mode, it reads its parameters from the command line or (failing that) from standard input. Otherwise, cookies and other parameters are parsed automatically from the standard CGI locations, which varies according to the REQUEST_METHOD.
# File cgi/core.rb, line 811 def initialize(options = {}, &block) # :yields: name, value @accept_charset_error_block = block_given? ? block : nil @options={:accept_charset=>@@accept_charset} case options when Hash @options.merge!(options) when String @options[:tag_maker]=options end @accept_charset=@options[:accept_charset] if defined?(MOD_RUBY) && !ENV.key?("GATEWAY_INTERFACE") Apache.request.setup_cgi_env end extend QueryExtension @multipart = false initialize_query() # set @params, @cookies @output_cookies = nil @output_hidden = nil case @options[:tag_maker] when "html3" require 'cgi/html' extend Html3 element_init() extend HtmlExtension when "html4" require 'cgi/html' extend Html4 element_init() extend HtmlExtension when "html4Tr" require 'cgi/html' extend Html4Tr element_init() extend HtmlExtension when "html4Fr" require 'cgi/html' extend Html4Tr element_init() extend Html4Fr element_init() extend HtmlExtension when "html5" require 'cgi/html' extend Html5 element_init() extend HtmlExtension end end
Parse an HTTP query string into a hash of key=>value pairs.
params = CGI::parse("query_string") # {"name1" => ["value1", "value2", ...], # "name2" => ["value1", "value2", ...], ... }
# File cgi/core.rb, line 374 def CGI::parse(query) params = {} query.split(/[&;]/).each do |pairs| key, value = pairs.split('=',2).collect{|v| CGI::unescape(v) } next unless key params[key] ||= [] params[key].push(value) if value end params.default=[].freeze params end
Prettify (indent) an HTML string.
string
is the HTML string to indent. shift
is
the indentation unit to use; it defaults to two spaces.
print CGI::pretty("<HTML><BODY></BODY></HTML>") # <HTML> # <BODY> # </BODY> # </HTML> print CGI::pretty("<HTML><BODY></BODY></HTML>", "\t") # <HTML> # <BODY> # </BODY> # </HTML>
# File cgi/util.rb, line 188 def CGI::pretty(string, shift = " ") lines = string.gsub(/(?!\A)<.*?>/m, "\n\\0").gsub(/<.*?>(?!\n)/m, "\\0\n") end_pos = 0 while end_pos = lines.index(/^<\/(\w+)/, end_pos) element = $1.dup start_pos = lines.rindex(/^\s*<#{element}/i, end_pos) lines[start_pos ... end_pos] = "__" + lines[start_pos ... end_pos].gsub(/\n(?!\z)/, "\n" + shift) + "__" end lines.gsub(/^((?:#{Regexp::quote(shift)})*)__(?=<\/?\w)/, '\1') end
Format a Time
object as a String using the format specified by
RFC 1123.
CGI::rfc1123_date(Time.now) # Sat, 01 Jan 2000 00:00:00 GMT
# File cgi/util.rb, line 164 def CGI::rfc1123_date(time) t = time.clone.gmtime return format("%s, %.2d %s %.4d %.2d:%.2d:%.2d GMT", RFC822_DAYS[t.wday], t.day, RFC822_MONTHS[t.month-1], t.year, t.hour, t.min, t.sec) end
URL-decode a string with encoding(optional).
string = CGI::unescape("%27Stop%21%27+said+Fred") # => "'Stop!' said Fred"
# File cgi/util.rb, line 16 def CGI::unescape(string,encoding=@@accept_charset) str=string.tr('+', ' ').force_encoding(Encoding::ASCII_8BIT).gsub(/((?:%[0-9a-fA-F]{2})+)/) do [$1.delete('%')].pack('H*') end.force_encoding(encoding) str.valid_encoding? ? str : str.force_encoding(string.encoding) end
Undo escaping such as that done by ::escapeElement
print CGI::unescapeElement( CGI::escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG") # "<BR><A HREF="url"></A>" print CGI::unescapeElement( CGI::escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"]) # "<BR><A HREF="url"></A>"
# File cgi/util.rb, line 133 def CGI::unescapeElement(string, *elements) elements = elements[0] if elements[0].kind_of?(Array) unless elements.empty? string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/i) do CGI::unescapeHTML($&) end else string end end
Unescape a string that has been HTML-escaped
CGI::unescapeHTML("Usage: foo "bar" <baz>") # => "Usage: foo \"bar\" <baz>"
# File cgi/util.rb, line 42 def CGI::unescapeHTML(string) enc = string.encoding if [Encoding::UTF_16BE, Encoding::UTF_16LE, Encoding::UTF_32BE, Encoding::UTF_32LE].include?(enc) return string.gsub(Regexp.new('&(apos|amp|quot|gt|lt|#[0-9]+|#x[0-9A-Fa-f]+);'.encode(enc))) do case $1.encode("US-ASCII") when 'apos' then "'".encode(enc) when 'amp' then '&'.encode(enc) when 'quot' then '"'.encode(enc) when 'gt' then '>'.encode(enc) when 'lt' then '<'.encode(enc) when /\A#0*(\d+)\z/ then $1.to_i.chr(enc) when /\A#x([0-9a-f]+)\z/i then $1.hex.chr(enc) end end end asciicompat = Encoding.compatible?(string, "a") string.gsub(/&(apos|amp|quot|gt|lt|\#[0-9]+|\#[xX][0-9A-Fa-f]+);/) do match = $1.dup case match when 'apos' then "'" when 'amp' then '&' when 'quot' then '"' when 'gt' then '>' when 'lt' then '<' when /\A#0*(\d+)\z/ n = $1.to_i if enc == Encoding::UTF_8 or enc == Encoding::ISO_8859_1 && n < 256 or asciicompat && n < 128 n.chr(enc) else "&##{$1};" end when /\A#x([0-9a-f]+)\z/i n = $1.hex if enc == Encoding::UTF_8 or enc == Encoding::ISO_8859_1 && n < 256 or asciicompat && n < 128 n.chr(enc) else "&#x#{$1};" end else "&#{match};" end end end
Synonym for ::unescapeElement
# File cgi/util.rb, line 150 def CGI::unescape_element(str) unescapeElement(str) end
Synonym for ::unescapeHTML
# File cgi/util.rb, line 96 def CGI::unescape_html(str) unescapeHTML(str) end
This method is an alias for http_header, when HTML5 tag maker is inactive.
NOTE: use http_header to create HTTP header blocks, this alias is only provided for backwards compatibility.
Using header with the HTML5 tag maker will create a <header> element.
Create an HTTP header block as a string.
Includes the empty line that ends the header block.
content_type_string
If this form is used, this string is the Content-Type
headers_hash
A Hash of header values. The following header keys are recognized:
The Content-Type header. Defaults to “text/html”
The charset of the body, appended to the Content-Type header.
A boolean value. If true, prepend protocol string and status code, and date; and sets default values for “server” and “connection” if not explicitly set.
The HTTP status code as a String, returned as the Status header. The values are:
200 OK
206 Partial Content
300 Multiple Choices
301 Moved Permanently
302 Found
304 Not Modified
400 Bad Request
401 Authorization Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
411 Length Required
412 Precondition Failed
500 Internal Server Error
501 Method Not Implemented
502 Bad Gateway
506 Variant Also Negotiates
The server software, returned as the Server header.
The connection type, returned as the Connection header (for instance, “close”.
The length of the content that will be sent, returned as the Content-Length header.
The language of the content, returned as the Content-Language header.
The time on which the current content expires, as a Time
object, returned as the Expires header.
A cookie or cookies, returned as one or more Set-Cookie headers. The value can be the literal string of the cookie; a CGI::Cookie object; an Array of literal cookie strings or Cookie objects; or a hash all of whose values are literal cookie strings or Cookie objects.
These cookies are in addition to the cookies held in the @output_cookies field.
Other headers can also be set; they are appended as key: value.
Examples:
http_header # Content-Type: text/html http_header("text/plain") # Content-Type: text/plain http_header("nph" => true, "status" => "OK", # == "200 OK" # "status" => "200 GOOD", "server" => ENV['SERVER_SOFTWARE'], "connection" => "close", "type" => "text/html", "charset" => "iso-2022-jp", # Content-Type: text/html; charset=iso-2022-jp "length" => 103, "language" => "ja", "expires" => Time.now + 30, "cookie" => [cookie1, cookie2], "my_header1" => "my_value" "my_header2" => "my_value")
This method does not perform charset conversion.
# File cgi/core.rb, line 152 def http_header(options='text/html') if options.is_a?(String) content_type = options buf = _header_for_string(content_type) elsif options.is_a?(Hash) if options.size == 1 && options.has_key?('type') content_type = options['type'] buf = _header_for_string(content_type) else buf = _header_for_hash(options.dup) end else raise ArgumentError.new("expected String or Hash but got #{options.class}") end if defined?(MOD_RUBY) _header_for_modruby(buf) return '' else buf << EOL # empty line of separator return buf end end
Print an HTTP header and body to $DEFAULT_OUTPUT ($>)
content_type_string
If a string is passed, it is assumed to be the content type.
headers_hash
This is a Hash of headers, similar to that used by http_header.
block
A block is required and should evaluate to the body of the response.
Content-Length
is automatically calculated from the size of
the String returned by the content block.
If ENV['REQUEST_METHOD'] == "HEAD"
, then only the
header is output (the content block is still required, but it is ignored).
If the charset is “iso-2022-jp” or “euc-jp” or “shift_jis” then the content is converted to this charset, and the language is set to “ja”.
Example:
cgi = CGI.new cgi.out{ "string" } # Content-Type: text/html # Content-Length: 6 # # string cgi.out("text/plain") { "string" } # Content-Type: text/plain # Content-Length: 6 # # string cgi.out("nph" => true, "status" => "OK", # == "200 OK" "server" => ENV['SERVER_SOFTWARE'], "connection" => "close", "type" => "text/html", "charset" => "iso-2022-jp", # Content-Type: text/html; charset=iso-2022-jp "language" => "ja", "expires" => Time.now + (3600 * 24 * 30), "cookie" => [cookie1, cookie2], "my_header1" => "my_value", "my_header2" => "my_value") { "string" } # HTTP/1.1 200 OK # Date: Sun, 15 May 2011 17:35:54 GMT # Server: Apache 2.2.0 # Connection: close # Content-Type: text/html; charset=iso-2022-jp # Content-Length: 6 # Content-Language: ja # Expires: Tue, 14 Jun 2011 17:35:54 GMT # Set-Cookie: foo # Set-Cookie: bar # my_header1: my_value # my_header2: my_value # # string
# File cgi/core.rb, line 348 def out(options = "text/html") # :yield: options = { "type" => options } if options.kind_of?(String) content = yield options["length"] = content.bytesize.to_s output = stdoutput output.binmode if defined? output.binmode output.print http_header(options) output.print content unless "HEAD" == env_table['REQUEST_METHOD'] end