Class: Cyberweb::CGI

Inherits:
Object
  • Object
show all
Extended by:
Util
Defined in:
lib/cyberweb/cgi/cgi.rb,
lib/cyberweb/cgi/core.rb,
lib/cyberweb/cgi/util.rb,
lib/cyberweb/cgi/cookie.rb,
lib/cyberweb/cgi/session.rb,
lib/cyberweb/cgi/constants.rb,
lib/cyberweb/cgi/tag_maker.rb,
lib/cyberweb/cgi/exceptions.rb,
lib/cyberweb/cgi/session/pstore.rb,
lib/cyberweb/cgi/query_extension.rb,
lib/cyberweb/cgi/session/file_store.rb,
lib/cyberweb/cgi/session/memory_store.rb,
lib/cyberweb/cgi/mod_ruby_exception_printer.rb

Overview

Cyberweb::CGI

Defined Under Namespace

Modules: QueryExtension, TagMaker, Util Classes: Cookie, Exception, InvalidEncoding, ModRubyExceptionPrinter, Session

Constant Summary collapse

MAX_MULTIPART_LENGTH =
#

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.

Also have a look at the CGI.new documentation.

#
128 * 1024 * 1024
MAX_MULTIPART_COUNT =
#

MAX_MULTIPART_COUNT

Maximum number of request parameters when multipart

#
128
ARRAY_PREDEFINED_CGI_ENV_VARIABLES =
#

Cyberweb::CGI::ARRAY_PREDEFINED_CGI_ENV_VARIABLES

All ENV variables for use in .cgi scripts should be defined here prior to their usage.

SCRIPT_NAME will hold the name of the file that is supposed to be served to the visitor.

#
%w(

  AUTH_TYPE
  CONTENT_TYPE
  GATEWAY_INTERFACE
  HTTP_ACCEPT
  HTTP_ACCEPT_CHARSET
  HTTP_ACCEPT_ENCODING
  HTTP_ACCEPT_LANGUAGE
  HTTP_CACHE_CONTROL
  HTTP_FROM
  HTTP_HOST
  HTTP_NEGOTIATE
  HTTP_PRAGMA
  HTTP_REFERER
  HTTP_USER_AGENT
  PATH_INFO
  PATH_TRANSLATED
  QUERY_STRING
  REMOTE_ADDR
  REMOTE_HOST
  REMOTE_IDENT
  REMOTE_USER
  REQUEST_METHOD
  SCRIPT_NAME
  SERVER_NAME
  SERVER_PROTOCOL
  SERVER_SOFTWARE

)
RFC822_MONTHS =
#

RFC822_MONTHS

#
::Cyberweb::RFC822_MONTHS
RFC822_DAYS =
#

RFC822_DAYS

#
::Cyberweb::RFC822_DAYS
CR =
#

CR

#
::Cyberweb::CR
LF =
#

LF

#
::Cyberweb::LF
EOL =
#

EOL

Standard internet newline sequence

#
::Cyberweb::EOL
REVISION =
#

REVISION

CGI-internal revision.

#
'03 Aug 2018'
NEEDS_BINMODE =
#

NEEDS_BINMODE

Whether processing will be required in binary vs text

#
File::BINARY != 0
HTTP_STATUS =
#

HTTP_STATUS

HTTP status codes are defined here.

They can be used through this hash here such as:

HTTP_STATUS['OK'] # gives '200 OK'.
#
::Cyberweb::HTTP_STATUS
USE_OFFLINE_MODE =
#

USE_OFFLINE_MODE

The default is to have this constant set to true.

#
false
@@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'

Constants included from Util

Util::TABLE_FOR_ESCAPE_HTML__, Util::US_ASCII_ENCODING

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util

escape, escape_element, escape_html, pretty, rfc1123_date, unescape, unescapeHTML, unescape_element

Constructor Details

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

#

initialize

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.

#


128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/cyberweb/cgi/core.rb', line 128

def initialize(
    options = {}, &block
  ) # :yields: name, value
  reset # Set to a clean initial state here.
  @accept_charset_error_block = block_given? ? block : nil
  # ======================================================================= #
  # The available options:
  # ======================================================================= #
  @options = {
    accept_charset:       @@accept_charset,
    max_multipart_length: MAX_MULTIPART_LENGTH
  }
  # ======================================================================= #
  # And the passed options to this method.
  # ======================================================================= #
  case options
  when Hash
    @options.merge!(options)
  when String # Assume that we wish to add the tag_maker entry here.
    @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

  initialize_query # set @params, @cookies
  check_for_which_tag_maker_to_use
end

Instance Attribute Details

#accept_charset ⇒ Object (readonly)

#

Return the accept character set for this CGI instance.

#


598
599
600
 
# File 'lib/cyberweb/cgi/core.rb', line 598

def accept_charset
  @accept_charset
end

Class Method Details

.accept_charset=(i) ⇒ Object

#

CGI.accept_charset=

Set the accepted character set for all new CGI instances.

#


625
626
627
 
# File 'lib/cyberweb/cgi/core.rb', line 625

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

.accept_charset? ⇒ Boolean

#

CGI.accept_charset?

Return the accept character set for all new CGI instances.

#

Returns:

  • (Boolean) 


616
617
618
 
# File 'lib/cyberweb/cgi/core.rb', line 616

def self.accept_charset?
  @@accept_charset
end

.parse(query) ⇒ Object

#

CGI.parse

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

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


568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/cyberweb/cgi/core.rb', line 568

def self.parse(query)
  params = {}
  splitted = query.split(/[&;]/)
  splitted.each { |pairs|
    key, value = pairs.split('=', 2).map {|v|
      CGI.unescape(v)
    }
    next unless key
    params[key] ||= []
    params[key].push(value) if value
  }
  params.default = [].freeze
  return params
end

.predefined_cgi_env_variables ⇒ Object

#

Cyberweb::CGI.predefined_cgi_env_variables

#


109
110
111
 
# File 'lib/cyberweb/cgi/constants.rb', line 109

def self.predefined_cgi_env_variables
  ARRAY_PREDEFINED_CGI_ENV_VARIABLES
end

.use_commandline_input? ⇒ Boolean

#

Cyberweb::CGI.use_commandline_input?

#

Returns:

  • (Boolean) 


23
24
25
 
# File 'lib/cyberweb/cgi/query_extension.rb', line 23

def self.use_commandline_input?
  USE_OFFLINE_MODE
end

Instance Method Details

#check_for_which_tag_maker_to_use ⇒ Object

#

check_for_which_tag_maker_to_use

#


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/cyberweb/cgi/core.rb', line 164

def check_for_which_tag_maker_to_use

  case @options[:tag_maker] # case tag
  # === html3
  when 'html3'
    require 'cyberweb/cgi/html.rb'
    extend Html3
    extend HtmlExtension
  when 'html4'
    require 'cyberweb/cgi/html.rb'
    extend Html4
    extend HtmlExtension
  when 'html4Tr'
    require 'cyberweb/cgi/html.rb'
    extend Html4Tr
    extend HtmlExtension
  when 'html4Fr'
    require 'cyberweb/cgi/html.rb'
    extend Html4Tr
    extend Html4Fr
    extend HtmlExtension
  # === html5
  when 'html5'
    require 'cyberweb/cgi/html.rb'
    extend Html5
    extend HtmlExtension
  end
end

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

#

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

#


307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/cyberweb/cgi/core.rb', line 307

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

#

nph?

#

Returns:

  • (Boolean) 


436
437
438
 
# File 'lib/cyberweb/cgi/core.rb', line 436

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

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

#

out

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
#


537
538
539
540
541
542
543
544
545
 
# File 'lib/cyberweb/cgi/core.rb', line 537

def out(options = 'text/html') # :yield:
  options = { 'type' => options } if options.is_a? 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

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

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


555
556
557
 
# File 'lib/cyberweb/cgi/core.rb', line 555

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

#reset ⇒ Object

#

reset

#


196
197
198
199
200
 
# File 'lib/cyberweb/cgi/core.rb', line 196

def reset
  @multipart      = false
  @output_cookies = nil
  @output_hidden  = nil
end