Class: CGI

Inherits:
Object show all
Extended by:
Util
Includes:
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,
ext/cgi/escape/escape.c,
ext/erb/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

VERSION = 
"0.4.1"
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::TABLE_FOR_ESCAPE_HTML__

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util

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

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.



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
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
 
# 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

Instance Attribute Details

#accept_charset ⇒ Object (readonly)

Return the accept character set for this CGI instance.



769
770
771
 
# File 'lib/cgi/core.rb', line 769

def accept_charset
  @accept_charset
end

Class Method Details

.accept_charset ⇒ Object

Return the accept character set for all new CGI instances.



759
760
761
 
# File 'lib/cgi/core.rb', line 759

def self.accept_charset
  @@accept_charset
end

.accept_charset=(accept_charset) ⇒ Object

Set the accept character set for all new CGI instances.



764
765
766
 
# File 'lib/cgi/core.rb', line 764

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", ...], ... }



393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# 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

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.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/cgi/core.rb', line 160

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) 


274
275
276
 
# File 'lib/cgi/core.rb', line 274

def nph?  #:nodoc:
  return /IIS\/(\d+)/ =~ $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



367
368
369
370
371
372
373
374
375
376
 
# 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(*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



383
384
385
 
# File 'lib/cgi/core.rb', line 383

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