附加库

-> CGI

支持CGI程序的库。请参考下文以了解CGI协议之详情。

  * http://Web.Golux.Com/coar/cgi/draft-coar-cgi-v11-03.txt

用例
获取form field的值

require "cgi"
cgi = CGI.new
values = cgi['field_name'] # <== 'field_name' 的数组
 # 若尚未指定'field_name', 则返回 []。 (1.6)
 # 若尚未指定'field_name', 则返回 ""。 (1.8)
fields = cgi.keys    # <== field name的数组

# 若form中有名为'field_name'的field name, 则为真
cgi.has_key?('field_name')
cgi.include?('field_name')

以哈希表的方式获取form field的值

以哈希表方式获取form的值时,需要使用CGI#params。

例
require "cgi"
cgi = CGI.new
params = cgi.params

因为CGI#params每次都返回相同的Hash对象,所以还可以这样。

cgi.params['new_field_name'] = ["value"] # 添加新参数
cgi.params['field_name'] = ["new_value"] # 改变参数值
cgi.params.delete('field_name')    # 删除参数
cgi.params.clear         # 删除所有参数

将form field的值存入文件

最简单的方法就是使用PStore。

# 保存
require 'pstore'
db = PStore.new("query.db")
db.transaction do
 db["params"] = cgi.params
end

# 恢复
require 'pstore'
db = PStore.new("query.db")
db.transaction do
 cgi.params = db["params"]
end

但是,随着Ruby版本的不断更新, PStore数据的兼容性可能会出现问题, 所以若需要长期保存数据的话, 还请您慎重选择。

请参考PStore。
获取multipart field的值

ruby-1.6 のcgi.rb:

require "cgi"
cgi = CGI.new
values = cgi['field_name'] # field_name的数组
values[0].read     # values[0]的内容
values[0].local_path   # values[0]的本地文件的路径
values[0].original_filename # values[0]原来的名称
values[0].content_type   # values[0]的content_type

values[0] 是 Tempfile对象。

ruby-1.8 的cgi.rb:

require "cgi"
cgi = CGI.new
value = cgi['field_name'] # field_name的数组
value.read     # 内容
value.local_path   # 本地文件的路径
value.original_filename # 原来的名称
value.content_type   # content_type

向客户端传递cookie

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"}

从客户端获取cookie

require "cgi"
cgi = CGI.new
values = cgi.cookies['name'] # values是name cookie的值的数组。
          # 若name cookie不存在, 则返回空数组。
names = cgi.cookies.keys  # 所有cookie名称的数组

取得与CGI相关的环境变量的值

您可以直接从ENV中取得与CGI相关的环境变量的值, 此外您还可以利用CGI类的方法来获得这些值. 通常情况下,将环境变量名变为小写之后就得到了相应的方法名. 例如AUTH_TYPE就与CGI#auth_type相对应。

require "cgi"
cgi = CGI.new
value = cgi.auth_type

这些环境变量包括

  * AUTH_TYPE
  * CONTENT_LENGTH
  * CONTENT_TYPE
  * GATEWAY_INTERFACE
  * PATH_INFO
  * PATH_TRANSLATED
  * QUERY_STRING
  * REMOTE_ADDR
  * REMOTE_HOST
  * REMOTE_IDENT
  * REMOTE_USER
  * REQUEST_METHOD
  * SCRIPT_NAME
  * SERVER_NAME
  * SERVER_PORT
  * SERVER_PROTOCOL
  * SERVER_SOFTWARE

其中#content_length和#server_port返回整数, 其他方法返回字符串。

HTTP_COOKIE和HTTP_COOKIE2分别对应于raw_cookie和raw_cookie2。

value = cgi.raw_cookie  # ENV["HTTP_COOKIE"]
value = cgi.raw_cookie2  # ENV["HTTP_COOKIE2"]

此外,将下列这些与HTTP相关的环境变量名中的HTTP_部分去掉之后再变为小写,就得到了对应的方法名。

例
value = cgi.accept     # ENV["HTTP_ACCEPT"]
value = cgi.accept_charset  # ENV["HTTP_ACCEPT_CHARSET"]

这类环境变量包括

  * 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

请参考<URL:http://www.w3.org/CGI/>来了解与CGI相关的环境变量的详情。
将HTTP Header和HTML输出到标准输出

require "cgi"
cgi = CGI.new("html3") # 添加生成HTML的方法
cgi.out() do
 cgi.html() do
  cgi.head{ cgi.title{"TITLE"} } +
  cgi.body() do
  cgi.form() do
   cgi.textarea("get_text") +
   cgi.br +
   cgi.submit
  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

# 添加生成HTML的方法
CGI.new("html3")  # html3.2
CGI.new("html4")  # html4.0 (Strict)
CGI.new("html4Tr") # html4.0 Transitional
CGI.new("html4Fr") # html4.0 Frameset

上传文件

请参考[ruby-list:25399]。
class CGI
类方法

CGI.escape(string)

  将string进行URL编码之后返回结果。

  p CGI::escape('%##') #=> "%40%23%23"

CGI.unescape(string)

  将string进行URL解码之后返回结果。

  p CGI::unescape('%40%23%23') #=> "@##"

CGI.escapeHTML(string)

  对string中的 &"<> 进行编码并返回结果。

  p CGI::escapeHTML("3 > 1") #=> "3 &gt; 1"

CGI.unescapeHTML(string)

  只对string中的 & &gt; &lt; " 和带有数值的元素(&#0ffff 等)进行解码。

  p CGI::unescapeHTML("3 &gt; 1") #=> "3 > 1"

CGI.escapeElement(string, *elements)

  只对elements所指元素的标签(tag)进行编码。

  例:
  p CGI::escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
   # => "<BR>&lt;A HREF="url"&gt;&lt;/A&gt"

  p CGI::escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
   # => "<BR>&lt;A HREF="url"&gt;&lt;/A&gt"

CGI.unescapeElement(string, *element)

  只对特定元素进行HTML解码。

  例:   
  print CGI::unescapeElement('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;', "A", "IMG")
  # => "&lt;BR&gt;<A HREF="url"></A>"

  print CGI::unescapeElement('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;', %w(A IMG))
  # => "&lt;BR&gt;<A HREF="url"></A>"

CGI.rfc1123_date(time)

  将time时间变为RFC 1123格式的字符串。

  例:
  CGI::rfc1123_date(Time.now)
  # => Sat, 1 Jan 2000 00:00:00 GMT

CGI.parse(query)

  对QUERY_STRING进行解析。

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

CGI.pretty(string, shift = " ")

  整理HTML代码，增强其可读性。

  例:
  print CGI::pretty("<HTML><BODY></BODY></HTML>")
  # <HTML>
  # <BODY>
  # </BODY>
  # </HTML>

  print CGI::pretty("<HTML><BODY></BODY></HTML>", "\t")
  # <HTML>
  #   <BODY>
  #   </BODY>
  # </HTML>

方法

CGI#header(headers = "text/html")

  按照headers的要求输出HTTP头。若不想借助CGI#out，而是要自定义输出HTML时，可以使用该方法。该方法不会对字符串进行编码。

  例:
  header
  # Content-Type: text/html

  header("text/plain")
  # Content-Type: text/plain

  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
    "language" => "ja",
    "expires"  => Time.now + 30,
    "cookie"  => [cookie1, cookie2],
    "my_header1" => "my_value"
    "my_header2" => "my_value"})

  status参数可以使用下列字符串。

  "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 Rrecondition 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"

例

  cgi = CGI.new('html3')
  print cgi.header({"charset" => "shift_jis"})
  print "<html><head><title>TITLE</title></head>\r\n"
  print "<body>BODY</body></html>\r\n"

CGI#out(options = "text/html") { .... }

  输出HTTP头和块中给出的字符串。

  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" }

  若遇到HEAD request(REQUEST_METHOD == "HEAD")，则只输出HTTP头。

  若charset为"iso-2022-jp"、"euc-jp"或"shift_jis"其中之一时，会自动编码字符串，并将language设为"ja"。
CGI#print(*strings)

  将参数的字符串发送到标准输出。

  例:
  cgi = CGI.new
  cgi.print "This line is a part of content body.\r\n"

CGI#auth_type

ENV['AUTH_TYPE']

CGI#content_length

ENV['CONTENT_LENGTH']

CGI#content_type

ENV['CONTENT_TYPE']

CGI#gateway_interface

ENV['GATEWAY_INTERFACE']

CGI#path_info

ENV['PATH_INFO']

CGI#path_translated

ENV['PATH_TRANSLATED']

CGI#query_string

ENV['QUERY_STRING']

CGI#remote_addr

ENV['REMOTE_ADDR']

CGI#remote_host

ENV['REMOTE_HOST']

CGI#remote_ident

ENV['REMOTE_IDENT']

CGI#remote_user

ENV['REMOTE_USER']

CGI#request_method

ENV['REQUEST_METHOD']

CGI#script_name

ENV['SCRIPT_NAME']

CGI#server_name

ENV['SERVER_NAME']

CGI#server_port

ENV['SERVER_PORT']

CGI#server_protocol

ENV['SERVER_PROTOCOL']

CGI#server_software

ENV['SERVER_SOFTWARE']

CGI#raw_cookie

ENV["HTTP_COOKIE"]

CGI#raw_cookie2

ENV["HTTP_COOKIE2"]

CGI#accept

ENV['HTTP_ACCEPT']

CGI#accept_charset

ENV['HTTP_ACCEPT_CHARSET']

CGI#accept_encoding

ENV['HTTP_ACCEPT_ENCODING']

CGI#accept_language

ENV['HTTP_ACCEPT_LANGUAGE']

CGI#cache_control

ENV['HTTP_CACHE_CONTROL']

CGI#from

ENV['HTTP_FROM']

CGI#host

ENV['HTTP_HOST']

CGI#negotiate

ENV['HTTP_NEGOTIATE']

CGI#pragma

ENV['HTTP_PRAGMA']

CGI#referer

ENV['HTTP_REFERER']

CGI#user_agent

ENV['HTTP_USER_AGENT']

class CGI::Cookie
类方法

CGI::Cookie.new(name = "", *value)

  生成cookie对象。

  例:
  cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
  cookie1 = CGI::Cookie::new({"name" => "name", "value" => "value"})
  cookie1 = CGI::Cookie::new({'name'  => 'name',
           'value' => ['value1', 'value2', ...],
           'path'  => 'path', # optional
           'domain' => 'domain', # optional
           'expires' => Time.now, # optional
           'secure' => true  # optional
           })

  cgi.out({"cookie" => [cookie1, cookie2]}){ "string" }

  name  = cookie1.name
  values = cookie1.value
  path  = cookie1.path
  domain = cookie1.domain
  expires = cookie1.expires
  secure = cookie1.secure

  cookie1.name  = 'name'
  cookie1.value = ['value1', 'value2', ...]
  cookie1.path  = 'path'
  cookie1.domain = 'domain'
  cookie1.expires = Time.now + 30
  cookie1.secure = true

CGI::Cookie.parse(raw_cookie)

  解析cookie字符串。

  例:
  cookies = CGI::Cookie::parse("raw_cookie_string")
  # { "name1" => cookie1, "name2" => cookie2, ... }

CGI::Cookie#name
CGI::Cookie#name=
CGI::Cookie#value
CGI::Cookie#value=
CGI::Cookie#path
CGI::Cookie#path=
CGI::Cookie#domain
CGI::Cookie#domain=
CGI::Cookie#expires
CGI::Cookie#expires=
CGI::Cookie#secure
CGI::Cookie#secure=

  Cookie 对象的属性。

  例:
  cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
  cookie1 = CGI::Cookie::new({"name" => "name", "value" => "value"})
  cookie1 = CGI::Cookie::new({'name'  => 'name',
           'value' => ['value1', 'value2', ...],
           'path'  => 'path', # optional
           'domain' => 'domain', # optional
           'expires' => Time.now, # optional
           'secure' => true  # optional
           })

  cgi.out({"cookie" => [cookie1, cookie2]}){ "string" }

  name  = cookie1.name
  values = cookie1.value
  path  = cookie1.path
  domain = cookie1.domain
  expires = cookie1.expires
  secure = cookie1.secure

  cookie1.name  = 'name'
  cookie1.value = ['value1', 'value2', ...]
  cookie1.path  = 'path'
  cookie1.domain = 'domain'
  cookie1.expires = Time.now + 30
  cookie1.secure = true

输出HTML元素的方法

例:
cgi = CGI.new("html3") # 添加生成HTML的方法
cgi.element
cgi.element{ "string" }
cgi.element({ "ATTRILUTE1" => "value1", "ATTRIBUTE2" => "value2" })
cgi.element({ "ATTRILUTE1" => "value1", "ATTRIBUTE2" => "value2" }){ "string" }

# 添加生成HTML的方法
CGI.new("html3")  # html3.2
CGI.new("html4")  # html4.0 (Strict)
CGI.new("html4Tr") # html4.0 Transitional
CGI.new("html4Fr") # html4.0 Frameset

CGI::HtmlExtension#a(href = "")

  例:
  a("url")
  # = a({ "HREF" => "url" })

CGI::HtmlExtension#base(href = "")

  例:
  base("url")
  # = base({ "HREF" => "url" })

CGI::HtmlExtension#blockquote(cite = nil)

  例:
  blockquote("url"){ "string" }
  # = blockquote({ "CITE" => "url" }){ "string" }

CGI::HtmlExtension#caption(align = nil)

  例:
  caption("align"){ "string" }
  # = caption({ "ALIGN" => "align" }){ "string" }

CGI::HtmlExtension#checkbox(name = "", value = nil, checked = nil)

  例:
  checkbox("name")
  # = checkbox({ "NAME" => "name" })

  checkbox("name", "value")
  # = checkbox({ "NAME" => "name", "VALUE" => "value" })

  checkbox("name", "value", true)
  # = checkbox({ "NAME" => "name", "VALUE" => "value", "CHECKED" => true })

CGI::HtmlExtension#checkbox_group(name = "", *values)

  例:
  checkbox_group("name", "foo", "bar", "baz")
  # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  # <INPUT TYPE="checkbox" NAME="name" VALUE="bar">bar
  # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz

  checkbox_group("name", ["foo"], ["bar", true], "baz")
  # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  # <INPUT TYPE="checkbox" SELECTED NAME="name" VALUE="bar">bar
  # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz

  checkbox_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  # <INPUT TYPE="checkbox" NAME="name" VALUE="1">Foo
  # <INPUT TYPE="checkbox" SELECTED NAME="name" VALUE="2">Bar
  # <INPUT TYPE="checkbox" NAME="name" VALUE="Baz">Baz

  checkbox_group({ "NAME" => "name",
       "VALUES" => ["foo", "bar", "baz"] })

  checkbox_group({ "NAME" => "name",
       "VALUES" => [["foo"], ["bar", true], "baz"] })

  checkbox_group({ "NAME" => "name",
       "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"] })

CGI::HtmlExtension#file_field(name = "", size = 20, maxlength = nil)

  例:
  file_field("name")
  # <INPUT TYPE="file" NAME="name" SIZE="20">

  file_field("name", 40)
  # <INPUT TYPE="file" NAME="name" SIZE="40">

  file_field("name", 40, 100)
  # <INPUT TYPE="file" NAME="name" SIZE="40" MAXLENGTH="100">

  file_field({ "NAME" => "name", "SIZE" => 40 })
  # <INPUT TYPE="file" NAME="name" SIZE="40">

CGI::HtmlExtension#form(method = "post", action = nil, enctype = "application/x-www-form-urlencoded")

  例:
  form{ "string" }
  # <FORM METHOD="post" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

  form("get"){ "string" }
  # <FORM METHOD="get" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

  form("get", "url"){ "string" }
  # <FORM METHOD="get" ACTION="url" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

  form({"METHOD" => "post", ENCTYPE => "enctype"}){ "string" }
  # <FORM METHOD="post" ENCTYPE="enctype">string</FORM>

CGI::HtmlExtension#hidden(name = "", value = nil)

  例:
  hidden("name")
  # <INPUT TYPE="hidden" NAME="name">

  hidden("name", "value")
  # <INPUT TYPE="hidden" NAME="name" VALUE="value">

  hidden({ "NAME" => "name", "VALUE" => "reset", "ID" => "foo" })
  # <INPUT TYPE="hidden" NAME="name" VALUE="value" ID="foo">

CGI::HtmlExtension#html(attributes = {})

  例:

  html{ "string" }
  # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML>string</HTML>

  html({ "LANG" => "ja" }){ "string" }
  # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML LANG="ja">string</HTML>

  html({ "DOCTYPE" => false }){ "string" }
  # <HTML>string</HTML>

  html({ "DOCTYPE" => '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">' }){ "string" }
  # <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"><HTML>string</HTML>

  html({ "PRETTY" => " " }){ "<BODY></BODY>" }
  # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  # <HTML>
  # <BODY>
  # </BODY>
  # </HTML>

  html({ "PRETTY" => "\t" }){ "<BODY></BODY>" }
  # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  # <HTML>
  #   <BODY>
  #   </BODY>
  # </HTML>

  html("PRETTY"){ "<BODY></BODY>" }
  # = html({ "PRETTY" => " " }){ "<BODY></BODY>" }

  html(if $VERBOSE then "PRETTY" end){ "HTML string" }

CGI::HtmlExtension#image_button(src = "", name = nil, alt = nil)

  例:
  image_button("url")
  # <INPUT TYPE="image" SRC="url">

  image_button("url", "name", "string")
  # <INPUT TYPE="image" SRC="url" NAME="name" ALT="string">

  image_button({ "SRC" => "url", "ATL" => "strng" })
  # <INPUT TYPE="image" SRC="url" ALT="string">

CGI::HtmlExtension#img(src = "", alt = "", width = nil, height = nil)

  例:
  img("src", "alt", 100, 50)
  # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">

  img({ "SRC" => "src", "ALT" => "alt", "WIDTH" => 100, "HEIGHT" => 50 })
  # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">

CGI::HtmlExtension#multipart_form(action = nil, enctype = "multipart/form-data")

  例:
  multipart_form{ "string" }
  # <FORM METHOD="post" ENCTYPE="multipart/form-data">string</FORM>

  multipart_form("url"){ "string" }
  # <FORM METHOD="post" ACTION="url" ENCTYPE="multipart/form-data">string</FORM>

CGI::HtmlExtension#password_field(name = "", value = nil, size = 40, maxlength = nil)

  例:
  password_field("name")
  # <INPUT TYPE="password" NAME="name" SIZE="40">

  password_field("name", "value")
  # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="40">

  password_field("password", "value", 80, 200)
  # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">

  password_field({ "NAME" => "name", "VALUE" => "value" })
  # <INPUT TYPE="password" NAME="name" VALUE="value">

CGI::HtmlExtension#popup_menu(name = "", *values)

  例:
  popup_menu("name", "foo", "bar", "baz")
  # <SELECT NAME="name">
  # <OPTION VALUE="foo">foo</OPTION>
  # <OPTION VALUE="bar">bar</OPTION>
  # <OPTION VALUE="baz">baz</OPTION>
  # </SELECT>

  popup_menu("name", ["foo"], ["bar", true], "baz")
  # <SELECT NAME="name">
  # <OPTION VALUE="foo">foo</OPTION>
  # <OPTION VALUE="bar" SELECTED>bar</OPTION>
  # <OPTION VALUE="baz">baz</OPTION>
  # </SELECT>

  popup_menu("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  # <SELECT NAME="name">
  # <OPTION VALUE="1">Foo</OPTION>
  # <OPTION SELECTED VALUE="2">Bar</OPTION>
  # <OPTION VALUE="Baz">Baz</OPTION>
  # </SELECT>

  popup_menu({"NAME" => "name", "SIZE" => 2, "MULTIPLE" => true,
      "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"] })
  # <SELECT NAME="name" MULTIPLE SIZE="2">
  # <OPTION VALUE="1">Foo</OPTION>
  # <OPTION SELECTED VALUE="2">Bar</OPTION>
  # <OPTION VALUE="Baz">Baz</OPTION>
  # </SELECT>

CGI::HtmlExtension#radio_button(name = "", value = nil, checked = nil)

  例:
  radio_button("name", "value")
  # <INPUT TYPE="radio" NAME="name" VALUE="value">

  radio_button("name", "value", true)
  # <INPUT TYPE="radio" NAME="name" VALUE="value" CHECKED>

  radio_button({ "NAME" => "name", "VALUE" => "value", "ID" => "foo" })
  # <INPUT TYPE="radio" NAME="name" VALUE="value" ID="foo">

CGI::HtmlExtension#radio_group(name = "", *values)

  例:
  radio_group("name", "foo", "bar", "baz")
  # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  # <INPUT TYPE="radio" NAME="name" VALUE="bar">bar
  # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz

  radio_group("name", ["foo"], ["bar", true], "baz")
  # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="bar">bar
  # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz

  radio_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  # <INPUT TYPE="radio" NAME="name" VALUE="1">Foo
  # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="2">Bar
  # <INPUT TYPE="radio" NAME="name" VALUE="Baz">Baz

  radio_group({ "NAME" => "name",
      "VALUES" => ["foo", "bar", "baz"] })

  radio_group({ "NAME" => "name",
      "VALUES" => [["foo"], ["bar", true], "baz"] })

  radio_group({ "NAME" => "name",
      "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"] })

CGI::HtmlExtension#reset(value = nil, name = nil)

  例:
  reset
  # <INPUT TYPE="reset">

  reset("reset")
  # <INPUT TYPE="reset" VALUE="reset">

  reset({ "VALUE" => "reset", "ID" => "foo" })
  # <INPUT TYPE="reset" VALUE="reset" ID="foo">

CGI::HtmlExtension#scrolling_list(name = "", *values)

  例:

  scrolling_list({"NAME" => "name", "SIZE" => 2, "MULTIPLE" => true,
       "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"] })
  # <SELECT NAME="name" MULTIPLE SIZE="2">
  # <OPTION VALUE="1">Foo</OPTION>
  # <OPTION SELECTED VALUE="2">Bar</OPTION>
  # <OPTION VALUE="Baz">Baz</OPTION>
  # </SELECT>

CGI::HtmlExtension#submit(value = nil, name = nil)

  例:
  submit
  # <INPUT TYPE="submit">

  submit("ok")
  # <INPUT TYPE="submit" VALUE="ok">

  submit("ok", "button1")
  # <INPUT TYPE="submit" VALUE="ok" NAME="button1">

  submit({ "VALUE" => "ok", "NAME" => "button1", "ID" => "foo" })
  # <INPUT TYPE="submit" VALUE="ok" NAME="button1" ID="foo">

CGI::HtmlExtension#text_field(name = "", value = nil, size = 40, maxlength = nil)

  例:
  text_field("name")
  # <INPUT TYPE="text" NAME="name" SIZE="40">

  text_field("name", "value")
  # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="40">

  text_field("name", "value", 80)
  # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80">

  text_field("name", "value", 80, 200)
  # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">

  text_field({ "NAME" => "name", "VALUE" => "value" })
  # <INPUT TYPE="text" NAME="name" VALUE="value">

CGI::HtmlExtension#textarea(name = "", cols = 70, rows = 10)

  例:
  textarea("name")
  # = textarea({ "NAME" => "name", "COLS" => 70, "ROWS" => 10 })

  textarea("name", 40, 5)
  # = textarea({ "NAME" => "name", "COLS" => 40, "ROWS" => 5 })

--> Complex
函数:

Complex(x, y)

Numeric
方法:

im

  返回虚数单位倍。
real

  实部。
image

  虚部。
arg

  返回复数形式的偏角。
polar

  返回极坐标。
conjugate

  返回共轭复数。

[2002-04-03] by sugawah@attglobal.net

处理复数的类
用法 Usage

若想使用Complex的话，必须添加require 'complex'语句。当您require该库时，Math模块会作相应的扩展以处理复数。

require 'complex'

因为Vector以及Matrix中包含复数，所以如果程序中已经读入了附加库的矢量类Vector以及矩阵类Matrix的话，就可以直接使用复数了。关于这个问题，请参考Vector以及Matrix的文档。

require 'matrix'
require 'complex'

超类:

  * Numeric

类方法:

Complex.new(r,i=0)
Complex(r,i=0)

  生成实部为r，虚部为i的复数。

方法:

Complex#+ c

  加上复数c并返回结果。
Complex#- c

  减去复数c并返回结果。
Complex#* c

  乘以复数c并返回结果。
Complex#/ c

  除以复数c并返回结果。
Complex#% c

  除以复数c，并返回余数(实部与实部进行运算，虚部与虚部进行运算)。
Complex#** c

  用复数c进行阶乘并返回结果。
Complex#divmod -- obsolete

  该方法已停用。
Complex#abs

  返回复数的绝对值。
Complex#abs2

  返回复数绝对值的平方。
Complex#arg

  返回复数的偏角。(值域？)
Complex#polar

  返回复数的极坐标形式，即返回数组[self.abs,self.arg]。
Complex#conjugate

  返回共轭复数。
Complex#real

  返回实部。
Complex#image

  返回虚部。
Complex#<=> c

  与c进行比较并返回结果。
Complex#== c

  若与c相等则返回真。
Complex#to_i

  变为整数Integer。
Complex#to_f

  变为浮点数Float。
Complex#to_r

  变为有理数Rational。

常数

I

  虚数单位。

ChangeLog

  * [2002-04-03] 初稿 by sugawah@attglobal.net
  * [2003-04-29] 将Complex#polar部分的内容修改为正确的数组字面值形式 by pastor

See <URL:http://rrr.jin.gr.jp/doc/csv/>

终端操作库 curses 的 Ruby 接口。
Curses 模块
模块函数

init_screen

  为curses初始化屏幕。在使用Curses模块中的任何方法之前，都必须调用该方法进行初始化操作。
close_screen

  关闭curses 屏幕。此时若再调用Curses 模块中的方法的话，就会引发异常。
stdscr

  返回代表整个画面的Curses::Window对象。
refresh

  刷新stdscr。
doupdate

  ？
clear

  删除stdscr的字符。该删除操作将立即进行而不会等待refresh。
echo

  启用输入回显。
noecho

  停用输入回显。
cbreak
crmode

  停用键盘输入缓冲。
nocbreak
nocrmode

  启用键盘输入缓冲。
nl

  在cooked 模式中，对return键返回LF (Ctrl-j)。
nonl

  在cooked 模式中，对return键返回CR (Ctrl-m)。
raw

  停止对键盘输入缓冲和Ctrl-C等特殊键的处理(raw 模式)。
noraw

  启用对键盘输入缓冲和Ctrl-C登特殊键的处理(cooked 模式)。
beep

  蜂鸣。若系统中没有该功能时，将被忽略。
flash

  将画面变为闪动的点。若系统中没有该功能时，将被忽略。
getch

  从标准输入中读入1字节。返回值是一个表示ASCII码的整数。
getstr

  从标准输入中读入一行。返回值是字符串。

  在不含getnstr()的平台上，该方法可能会导致缓冲溢出。
ungetch(ch)

  将字符ch(表示ASCII代码的整数)置入流。
setpos(y, x)

  将stdscr的光标移动到坐标为(x,y)的地方。坐标起点为0。

  若没有字符时，setpos的行为将取决于 OS 。
standout

  突出显示其后的字符。“突出显示”常指反显，但也不尽然。
standend

  在此处终止突出显示。
addch(ch)

  在stdscr的光标处覆盖以ch (1 字节)。
insch(ch)

  向stdscr的光标处插入ch (1 字节)。
addstr(str)

  向stdscr的光标处插入字符串 str 。
delch

  从stdscr 的光标处删除1 字节的内容。
deleteln

  删除stdscr的光标所在行的内容，并将后续内容上调一行。
lines

  返回画面中的可显行数。
cols

  返回画面中的可显列数(字节)。但有时返回的结果会比实际值少1字节。
inch

  从stdscr的光标处读取1 字节内容后将其返回。

Curses::Window 类
类方法

new(height, width, y, x)

  生成一个以画面坐标(x,y)为左上顶点，宽width高height的curses顶层窗口，并返回表示该窗口的Curses::Window对象。

方法

subwin(height, width, y, x)

  生成一个以画面坐标(x,y)为左上顶点，宽width高height的子窗口，并返回表示该窗口的Curses::Window对象。
close

  关闭窗口。此后若对该窗口对象进行操作的话，就会引发异常。
clear

  清除窗口。该操作会立即执行。
refresh

  更新显示窗口。
box(ver_char, hor_char)

  沿着窗口绘制方框，对竖线使用ver_char而对横线则使用hor_char。通常情况下，框体边线会被描画在窗口内部，请注意不要出现覆盖情况。
move(y, x)

  将窗口移动到(x,y)。

  若指定位置超出了父窗口的范围，则会被忽略。
setpos(y, x)

  将光标移动到窗口内的 (x,y)位置。
cury

  返回窗口内的光标行号。第一行为 0 。
curx

  返回窗口内的光标列号。第一列为 0 。
maxy

  返回可用的最大 y 坐标。其值为可显行数 + 1 。
maxx

  返回可用的最大 x 坐标。其值为可显字节数 + 1 。
begy

  返回父窗口中的窗口左上角的 y 坐标。 其起点为 0 。
begx

  返回父窗口中的窗口左上角的 x 坐标。 其起点为 0 。
standout

  突出显示后面的字符。
standend

  在此处结束突出显示。
inch

  在窗口光标处读入1字节的内容后将其返回。
addch(ch)

  向窗口光标处覆盖以ch (1 字节)。
insch(ch)

  向窗口光标处插入ch (1 字节)。
addstr(str)
self << str

  向窗口光标处插入字符串 str 。
getch

  从窗口输入中读入1 字节的内容。
getstr

  从窗口输入中读入一行。
delch

  从窗口光标处删除1 字节。
deleteln

  删除窗口中光标所在的行。

--> Date

--> DateTime

Date

处理日期的类。
术语的定义

术语定义以ISO 8601以及JIS X 0301为准。
历日

历日是由 历年、历月和历月中的序数所共同构成的特定的日期。

也就是由通常的年月日所构成的日期。
年内通算日 (年日)

年内通算日 (年日)是由 历年以及历年中的序数所构成的特定的日期。
历周日

历周日是由历周和历年中的序数所构成的日期。

历周是由历年中的序数所指定的特定的7天时间段，从周一开始。通常将包含首个星期四的那个周当作该年的第1个历周。其实就是“包含1月4日的那个周”。
儒略日

儒略日是指，将公元前4713年1月1日(儒略历)正午(格林尼治平均时)作为起点算起直到现在的天数(经过的天数)。

本文档中提到的天文学儒略日就是指原来的儒略日。而年代学儒略日是指，在地方时中把零点作为一天的开始。

在本文档中，若只是说“儒略日”的话，就是指“年代学儒略日”而并非原来的儒略日。
修正儒略日

修正儒略日是指将公元1858年11月17日(格林尼治历)零点(协调世界时)作为起点算起直到现在的天数(经过的天数)。

本文档中提到的天文学修正儒略日就是指原来的修正儒略日。而年代学修正儒略日是指，在地方时中把零点作为一天的开始。

在本文档中，若只是说“修正儒略日”的话，就是指“年代学修正儒略日”而并非原来的修正儒略日。
超类

Object
包含的模块

Comparable
类方法

civil([year[, mon[, mday[, start]]]])
new([year[, mon[, mday[, start]]]])

  生成与历日相对应的日期对象。

  在该类中，对于公元前的年份，将按照天文学的方式进行处理。1年前面的是零年，零年前面是-1年。月份以及月份中的日期必须是正数或负数(负数表示从后面算起的序数)，不可为零。

  末项参数是一个儒略历日期，它表示何时开始使用格里历。可以将格里历指定为真，儒略历指定为假。省略时其值为Date::ITALY (1582年10月15日)。

  请参考jd 。
commercial([cwyear[, cweek[, cwday[, start]]]])

  生成与历周日相对应的日期对象。

  周以及周中的日(星期几)必须是正数或负数(负数表示从后面算起的序数)，不可为零。

  不能在该方法中指定改历前的日期。

  请参考jd以及new 。
jd([jd[, start]])

  生成与儒略日相对应的日期对象。

  在该类的几个重要方法中使用负的儒略日时，可能会出现问题。

  请参考new 。
ordinal([year[, yday[, start]]])

  生成与年内通算日(年日)相对应的日期对象。

  月中的日必须是正数或负数(负数表示从后面算起的序数)，不可为零。

  请参考jd以及 new 。
parse(str[, complete[, start]])

  对给出的日期形式进行解析，并生成相应的日期对象。

  若最后那个可选参数为真，且年份处于0到99之间的范围中时，会将其看作是年份的后两位数字来进行自动补全。省略时，则看作假。

  还可以使用_parse。虽然该方法与parse十分类似，但它不生成日期对象，并以哈希表的形式返回找到的要素。
strptime(str[, format[, start]])

  使用给出的模型对日期形式进行解析，并生成相应的日期对象。

  还可以使用_strptime。虽然该方法与strptime十分类似，但它不生成日期对象，并以哈希表的形式返回找到的要素。

  请参考strptime(3)以及 strftime 。
today([start])

  生成与现在的日期相对应的日期对象。
valid_civil? (year, mon, mday[, start])
valid_date? (year, mon, mday[, start])

  若为正确的历日，则返回相应的儒略日。否则返回假。

  请参考jd以及 civil 。
valid_commercial? (cwyear, cweek, cwday[, start])

  若为正确的历周日，则返回相应的儒略日。否则返回假。

  请参考jd以及 commercial 。
valid_jd? (jd[, start])

  原封不动地返回第一个参数。

  该方法只是为保持对称性而设，没有实际的意义。

  请参考jd 。
valid_ordinal? (year, yday[, start])

  若为正确的年间通算日(年日)，则返回相应的儒略日。否则返回假。

  请参考jd以及 ordinal 。

方法

self + n

  返回self的n天后的日期对象。n必须是数值。
self - x

  若x是日期对象，则返回二者之差。若x是数值，则返回self的x天前的日期对象。
self << n

  返回self的n月前的日期对象。n必须是数值。
self <=> other

  对二者进行比较，返回-1、零或 1 。other必须是日期对象，或者是个表示天文学儒略日的数值。
self === other

  若为同一天则返回真
self >> n

  返回self的n月后的日期对象。n必须是数值。
asctime
ctime

  返回asctime(3)格式的字符串(但末尾的 "\n\0"除外)。
cwday

  返回历周中的日(星期几) (1-7、星期一是1)。
cweek

  返回历周 (1-53)。
cwyear

  返回历周中的年。
downto(min){|date| ...}

  该方法等价于step(min, -1){|date| ...} 。
england

  该方法等价于new_start(Date::ENGLAND) 。
gregorian

  该方法等价于new_start(Date::GREGORIAN) 。
italy

  该方法等价于new_start(Date::ITALY) 。
jd

  返回儒略日。不包含时刻。

  还可以使用ajd。该方法与jd类似，但它返回天文学儒略日。包含时刻。
julian

  该方法等价于new_start(Date::JULIAN) 。
leap?

  若为闰年则返回真。
mday
day

  返回月中的日 (1-31)。
mjd

  返回修正儒略日。不包含时刻信息。

  还可以使用amjd。该方法与mjd类似，但它返回天文学修正儒略日。包含时刻。
mon
month

  返回月 (1-12)。
new_start([start])

  复制self，重新设定改历日。省略参数时，其值为Date::ITALY (1582年10月15日)。

  请参考new 。
start

  返回一个表示改历日的儒略日。

  请参考new 。
step(limit, step){|date| ...}

  反复对块进行计算。块会取得日期对象。limit必须是日期对象，而step的值必须非零。
strftime([format])

  使用给出的格式对日期进行格式化。变换样式如下。つぎ的恃垂慌屯をあつかいます:

  %A, %a, %B, %b, %C, %c, %D, %d, %e, %F, %G, %g, %H, %h, %I, %j, %k, %l, %M, %m, %n, %P, %p, %R, %r, %S, %s, %T, %t, %U, %u, %V, %v, %W, %w, %X, %x, %Y, %y, %Z, %z, %%, %+

  请参考strftime(3)以及 strptime 。
succ
next

  返回第二天的日期对象。
to_s

  返回ISO 8601格式的字符串(不使用扩大表示法)。
upto(max){|date| ...}

  该方法等价于step(max, 1){|date| ...} 。
wday

  返回星期几(0-6、星期天是0)。
yday

  返回年中的日 (1-366)。
year

  返回年。

超类

Date
类方法

civil([year[, mon[, mday[, hour[, min[, sec[, offset[, start]]]]]]]])
new([year[, mon[, mday[, hour[, min[, sec[, offset[, start]]]]]]]])

  生成与历日相对应的日期时间对象。
commercial([cwyear[, cweek[, cwday[, hour[, min[, sec[, offset[, start]]]]]]]])

  生成与历周日相对应的日期时间对象。
jd([jd[, hour[, min[, sec[, offset[, start]]]]]])

  生成与儒略日相对应的日期时间对象。
now([start])

  生成与当前时刻相对应的日期时间对象。
ordinal([year[, yday[, hour[, min[, sec[, offset[, start]]]]]]])

  生成与年日相对应的日期时间对象。

方法

hour

  返回时 (0-23)。
min

  返回分 (0-59)。
new_offset([offset])

  复制self，重新设定时差。省略参数时，其值为零(协调世界时)。

  请参考new。
offset

  返回时差。
sec

  返回秒 (0-59)。
zone

  返回时区。