Class: CGI

Inherits:
Object
  • Object
show all
Extended by:
Util
Defined in:
lib/cgi.rb,
lib/cgi/core.rb,
lib/cgi/html.rb,
lib/cgi/util.rb,
lib/cgi/cookie.rb,
lib/cgi/session.rb,
lib/cgi/session/pstore.rb,
escape/escape.c

Overview

– Methods for generating HTML, parsing CGI-related parameters, and generating HTTP responses. ++

Defined Under Namespace

Modules: Escape, Html3, Html4, Html4Fr, Html4Tr, Html5, HtmlExtension, QueryExtension, TagMaker, Util Classes: Cookie, HTML3, HTML4, HTML4Fr, HTML4Tr, HTML5, InvalidEncoding, Session

Constant Summary collapse

CR =

String for carriage return

"\015"
LF =

String for linefeed

"\012"
EOL =

Standard internet newline sequence

CR + LF
REVISION =

:nodoc:

'$Id$'
NEEDS_BINMODE =

Whether processing will be required in binary vs text

File::BINARY != 0
PATH_SEPARATOR =

Path separators in different environments.

{'UNIX'=>'/', 'WINDOWS'=>'\\', 'MACINTOSH'=>':'}
HTTP_STATUS =

HTTP status codes.

{
  "OK"                  => "200 OK",
  "PARTIAL_CONTENT"     => "206 Partial Content",
  "MULTIPLE_CHOICES"    => "300 Multiple Choices",
  "MOVED"               => "301 Moved Permanently",
  "REDIRECT"            => "302 Found",
  "NOT_MODIFIED"        => "304 Not Modified",
  "BAD_REQUEST"         => "400 Bad Request",
  "AUTH_REQUIRED"       => "401 Authorization Required",
  "FORBIDDEN"           => "403 Forbidden",
  "NOT_FOUND"           => "404 Not Found",
  "METHOD_NOT_ALLOWED"  => "405 Method Not Allowed",
  "NOT_ACCEPTABLE"      => "406 Not Acceptable",
  "LENGTH_REQUIRED"     => "411 Length Required",
  "PRECONDITION_FAILED" => "412 Precondition Failed",
  "SERVER_ERROR"        => "500 Internal Server Error",
  "NOT_IMPLEMENTED"     => "501 Method Not Implemented",
  "BAD_GATEWAY"         => "502 Bad Gateway",
  "VARIANT_ALSO_VARIES" => "506 Variant Also Negotiates"
}
MAX_MULTIPART_COUNT =

Maximum number of request parameters when multipart

128
@@accept_charset =

@@accept_charset is default accept character set. This default value default is “UTF-8” If you want to change the default accept character set when create a new CGI instance, set this:

CGI.accept_charset = "EUC-JP"

"UTF-8"
@@max_multipart_length =

@@max_multipart_length is the maximum length of multipart data. The default value is 128 * 1024 * 1024 bytes

The default can be set to something else in the CGI constructor, via the :max_multipart_length key in the option hash.

See CGI.new documentation.

128 * 1024 * 1024

Constants included from Util

Util::RFC822_DAYS, Util::RFC822_MONTHS, Util::TABLE_FOR_ESCAPE_HTML__

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util

escape, escapeElement, escapeHTML, pretty, rfc1123_date, unescape, unescapeElement, unescapeHTML

Constructor Details

#initialize(options = {}, &block) ⇒ CGI

Create a new CGI instance.

:call-seq:

CGI.new(tag_maker) { block }
CGI.new(options_hash = {}) { block }
tag_maker

This is the same as using the options_hash form with the value { :tag_maker => tag_maker } Note that it is recommended to use the options_hash form, since it also allows you specify the charset you will accept.

options_hash

A Hash that recognizes three 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:

“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.



831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
 
# File 'lib/cgi/core.rb', line 831

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 'cgi/html'
    extend Html3
    extend HtmlExtension
  when "html4"
    require 'cgi/html'
    extend Html4
    extend HtmlExtension
  when "html4Tr"
    require 'cgi/html'
    extend Html4Tr
    extend HtmlExtension
  when "html4Fr"
    require 'cgi/html'
    extend Html4Tr
    extend Html4Fr
    extend HtmlExtension
  when "html5"
    require 'cgi/html'
    extend Html5
    extend HtmlExtension
  end
end

Instance Attribute Details

#accept_charset ⇒ Object (readonly)

Return the accept character set for this CGI instance.



750
751
752
 
# File 'lib/cgi/core.rb', line 750

def accept_charset
  @accept_charset
end

Class Method Details

.accept_charset ⇒ Object

Return the accept character set for all new CGI instances.



740
741
742
 
# File 'lib/cgi/core.rb', line 740

def self.accept_charset
  @@accept_charset
end

.accept_charset=(accept_charset) ⇒ Object

Set the accept character set for all new CGI instances.



745
746
747
 
# File 'lib/cgi/core.rb', line 745

def self.accept_charset=(accept_charset)
  @@accept_charset=accept_charset
end

.parse(query) ⇒ Object

Parse an HTTP query string into a hash of key=>value pairs.

params = CGI::parse("query_string")
  # {"name1" => ["value1", "value2", ...],
  #  "name2" => ["value1", "value2", ...], ... }



375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/cgi/core.rb', line 375

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

Instance Method Details

#http_header(options = 'text/html') ⇒ Object Also known as: header

Create an HTTP header block as a string.

:call-seq:

http_header(content_type_string="text/html")
http_header(headers_hash)

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:

type

The Content-Type header. Defaults to “text/html”

charset

The charset of the body, appended to the Content-Type header.

nph

A boolean value. If true, prepend protocol string and status code, and date; and sets default values for “server” and “connection” if not explicitly set.

status

The HTTP status code as a String, returned as the Status header. The values are:

OK

200 OK

PARTIAL_CONTENT

206 Partial Content

MULTIPLE_CHOICES

300 Multiple Choices

MOVED

301 Moved Permanently

REDIRECT

302 Found

NOT_MODIFIED

304 Not Modified

BAD_REQUEST

400 Bad Request

AUTH_REQUIRED

401 Authorization Required

FORBIDDEN

403 Forbidden

NOT_FOUND

404 Not Found

METHOD_NOT_ALLOWED

405 Method Not Allowed

NOT_ACCEPTABLE

406 Not Acceptable

LENGTH_REQUIRED

411 Length Required

PRECONDITION_FAILED

412 Precondition Failed

SERVER_ERROR

500 Internal Server Error

NOT_IMPLEMENTED

501 Method Not Implemented

BAD_GATEWAY

502 Bad Gateway

VARIANT_ALSO_VARIES

506 Variant Also Negotiates

server

The server software, returned as the Server header.

connection

The connection type, returned as the Connection header (for instance, “close”.

length

The length of the content that will be sent, returned as the Content-Length header.

language

The language of the content, returned as the Content-Language header.

expires

The time on which the current content expires, as a Time object, returned as the Expires header.

cookie

A cookie or cookies, returned as one or more Set-Cookie headers. The value can be the literal string of the cookie; a CGI::Cookie object; an Array of literal cookie strings or Cookie objects; or a hash all of whose values are literal cookie strings or Cookie objects.

These cookies are in addition to the cookies held in the @output_cookies field.

Other headers can also be set; they are appended as key: value.

Examples:

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.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/cgi/core.rb', line 153

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

#nph? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


256
257
258
 
# File 'lib/cgi/core.rb', line 256

def nph?  #:nodoc:
  return /IIS\/(\d+)/.match($CGI_ENV['SERVER_SOFTWARE']) && $1.to_i < 5
end

#out(options = "text/html") ⇒ Object

Print an HTTP header and body to $DEFAULT_OUTPUT ($>)

:call-seq:

cgi.out(content_type_string='text/html')
cgi.out(headers_hash)
content_type_string

If a string is passed, it is assumed to be the content type.

headers_hash

This is a Hash of headers, similar to that used by #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



349
350
351
352
353
354
355
356
357
358
 
# File 'lib/cgi/core.rb', line 349

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(*options) ⇒ Object

Print an argument or list of arguments to the default output stream

cgi = CGI.new
cgi.print    # default:  cgi.print == $DEFAULT_OUTPUT.print



365
366
367
 
# File 'lib/cgi/core.rb', line 365

def print(*options)
  stdoutput.print(*options)
end