class CGI
Overview¶ ↑
The Common Gateway Interface (CGI
) is a simple protocol for passing an HTTP request from a web server to a standalone program, and returning the output to the web browser. Basically, a CGI
program is called with the parameters of the request passed in either in the environment (GET) or via $stdin (POST), and everything it prints to $stdout is returned to the client.
This file holds the CGI
class. This class provides functionality for retrieving HTTP request parameters, managing cookies, and generating HTML output.
The file CGI::Session
provides session management functionality; see that class for more details.
See www.w3.org/CGI/ for more information on the CGI
protocol.
Introduction¶ ↑
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.
Queries¶ ↑
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.
Environmental Variables¶ ↑
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.
Parameters¶ ↑
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 behavior 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.
Cookies¶ ↑
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.
Multipart requests¶ ↑
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:
- local_path()
-
the path of the uploaded file on the local filesystem
- original_filename()
-
the name of the file on the client computer
- content_type()
-
the content type of the file
Responses¶ ↑
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.
Writing output¶ ↑
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.
Generating HTML¶ ↑
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.
Utility HTML escape and other methods like a function.¶ ↑
There are some utility tool defined in cgi/util.rb . And when include, you can use utility methods like a function.
Examples of use¶ ↑
Get form values¶ ↑
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['field_name']
returned an Array
with the old cgi.rb(included in Ruby 1.6)
Get form values as hash¶ ↑
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
Save form values to file¶ ↑
require "pstore" db = PStore.new("query.db") db.transaction do db["params"] = cgi.params end
Restore form values from file¶ ↑
require "pstore" db = PStore.new("query.db") db.transaction do cgi.params = db["params"] end
Get multipart form values¶ ↑
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.
Get cookie values¶ ↑
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.
Get cookie objects¶ ↑
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"}
Print http header and html string to $DEFAULT_OUTPUT ($>)¶ ↑
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
Some utility methods¶ ↑
require 'cgi/util' CGI.escapeHTML('Usage: foo "bar" <baz>')
Some utility methods like a function¶ ↑
require 'cgi/util' include CGI::Util escapeHTML('Usage: foo "bar" <baz>') h('Usage: foo "bar" <baz>') # alias
Constants
- CR
String
for carriage return- EOL
Standard internet newline sequence
- HTTP_STATUS
HTTP status codes.
- LF
String
for linefeed- MAX_MULTIPART_COUNT
Maximum number of request parameters when multipart
- NEEDS_BINMODE
Whether processing will be required in binary vs text
- PATH_SEPARATOR
Path separators in different environments.
- VERSION
Attributes
Return the accept character set for this CGI
instance.
Public Class Methods
Return the accept character set for all new CGI
instances.
# File lib/cgi/core.rb, line 759 def self.accept_charset @@accept_charset 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 theoptions_hash
form, since it also allows you specify the charset you will accept. options_hash
-
A
Hash
that recognizes three options::accept_charset
-
specifies encoding of received query string. If omitted,
@@accept_charset
is used. If the encoding is not valid, aCGI::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:
- “html3”
-
HTML 3.x
- “html4”
-
HTML 4.0
- “html4Tr”
-
HTML 4.0 Transitional
- “html4Fr”
-
HTML 4.0 with Framesets
- “html5”
-
HTML 5
:max_multipart_length
-
Specifies maximum length of multipart data. Can be an
Integer
scalar or a lambda, that will be evaluated when the request is parsed. This allows more complex logic to be set when determining whether to accept multipart data (e.g. consult a registered users upload allowance)Default is 128 * 1024 * 1024 bytes
cgi=CGI.new(:max_multipart_length => 268435456) # simple scalar cgi=CGI.new(:max_multipart_length => -> {check_filesystem}) # lambda
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 lib/cgi/core.rb, line 850 def initialize(options = {}, &block) # :yields: name, value @accept_charset_error_block = block_given? ? block : nil @options={ :accept_charset=>@@accept_charset, :max_multipart_length=>@@max_multipart_length } case options when Hash @options.merge!(options) when String @options[:tag_maker]=options end @accept_charset=@options[:accept_charset] @max_multipart_length=@options[:max_multipart_length] 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_relative 'html' extend Html3 extend HtmlExtension when "html4" require_relative 'html' extend Html4 extend HtmlExtension when "html4Tr" require_relative 'html' extend Html4Tr extend HtmlExtension when "html4Fr" require_relative 'html' extend Html4Tr extend Html4Fr extend HtmlExtension when "html5" require_relative 'html' extend Html5 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 lib/cgi/core.rb, line 393 def self.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
Public Instance Methods
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 byhttp_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 lib/cgi/core.rb, line 367 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
Print an argument or list of arguments to the default output stream
cgi = CGI.new cgi.print # default: cgi.print == $DEFAULT_OUTPUT.print
# File lib/cgi/core.rb, line 383 def print(*options) stdoutput.print(*options) end