Class: CGI

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

Overview

:stopdoc

Defined Under Namespace

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

Constant Summary collapse

VERSION =

The version string

"0.5.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 Escape

Escape::TABLE_FOR_ESCAPE_HTML__

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Escape

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

Methods included from Util

pretty, rfc1123_date

Constructor Details

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

  • tag_maker: html_version: specifies which version of HTML to use in generating tags.

    Value html_version may be one of:

    Example:

    CGI.new(tag_maker: 'html5')

    If the option is not given, no HTML generation methods are loaded.

With string argument tag_maker given as tag_maker and no block given, equivalent to CGI.new(tag_maker: tag_maker):

CGI.new('html5')

Outside a Standard Call Environment

This section assumes that ENV['REQUEST_METHOD'] is not defined; for example:

ENV['REQUEST_METHOD'] # => nil

In this mode, the method reads its parameters from the command line or (failing that) from standard input; returns a new CGI object.

Otherwise, cookies and other parameters are parsed automatically from the standard CGI locations, which vary according to the request method.

Options vs Public Methods

Some initialization options configure internal behavior only and do not provide corresponding public getter methods:

  • accept_charset: Configures internal encoding for parsing. The accept_charset method returns the HTTP Accept-Charset header.

  • max_multipart_length: Configures internal multipart size limits. No public getter method is available.

  • tag_maker: Loads HTML generation methods (publicly accessible).

Block

If a block is given, its code is stored as a Proc; whenever CGI::InvalidEncoding would be raised, the proc is called instead.

In this example, the proc simply saves the error:

encoding_errors={}
CGI.new(accept_charset: 'EUC-JP') do |name,value|
  encoding_errors[name] = value
end
# =>
#<CGI:0x000002b0ec11bcd8
 @accept_charset="EUC-JP",
 @accept_charset_error_block=#<Proc:0x000002b0ed2ee190 (irb):146>,
 @cookies={},
 @max_multipart_length=134217728,
 @multipart=false,
 @options={accept_charset: "EUC-JP", max_multipart_length: 134217728},
 @output_cookies=nil,
 @output_hidden=nil,
 @params={}>



930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
 
# File 'lib/cgi/core.rb', line 930

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.



772
773
774
 
# File 'lib/cgi/core.rb', line 772

def accept_charset
  @accept_charset
end

Class Method Details

.accept_charset ⇒ Object

Return the accept character set for all new CGI instances.



762
763
764
 
# File 'lib/cgi/core.rb', line 762

def self.accept_charset
  @@accept_charset
end

.accept_charset=(accept_charset) ⇒ Object

Set the accept character set for all new CGI instances.



767
768
769
 
# File 'lib/cgi/core.rb', line 767

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

.parse(query) ⇒ Object

:call-seq:

CGI.parse(query_string) -> hash

Returns a new hash built from name/value pairs in the given query_string:

query = 'foo=0&bar=1&foo=2&bar=3'
CGI.parse(query)
# => {"foo" => ["0", "2"], "bar" => ["1", "3"]}



396
397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/cgi/core.rb', line 396

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:



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