類別 CGI

概述¶ ↑

通用閘道介面 (CGI) 是一種簡單的協定，用於將 HTTP 要求從網路伺服器傳遞至獨立程式，並將輸出傳回至網路瀏覽器。基本上，CGI 程式會使用在環境 (GET) 或透過 $stdin (POST) 傳遞的請求參數來呼叫，而它列印至 $stdout 的所有內容都會傳回至客戶端。

這個檔案包含 CGI 類別。這個類別提供用於擷取 HTTP 請求參數、管理 Cookie 和產生 HTML 輸出的功能。

檔案 CGI::Session 提供階段管理功能；請參閱該類別以取得更多詳細資料。

請參閱 www.w3.org/CGI/ 以取得有關 CGI 協定的更多資訊。

簡介¶ ↑

CGI 是個大型類別，提供多種類別的方法，其中許多方法都混合自其他模組。有些文件說明在這個類別中，有些在 CGI::QueryExtension 和 CGI::HtmlExtension 模組中。請參閱 CGI::Cookie 以取得有關處理 Cookie 的具體資訊，以及 cgi/session.rb (CGI::Session) 以取得有關階段的資訊。

對於查詢，CGI 提供方法來取得環境變數、參數、Cookie 和多部分請求資料。對於回應，CGI 提供方法來寫入輸出和產生 HTML。

請繼續閱讀以取得更多詳細資料。範例提供在最下方。

查詢¶ ↑

CGI 類別會動態混合參數和 cookie 解析功能、環境變數存取，以及支援解析來自 CGI::QueryExtension 模組的多重部分要求（包括上傳的檔案）。

環境變數¶ ↑

標準的 CGI 環境變數可用作 CGI 物件的唯讀屬性。以下是這些變數的清單

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

對於這些變數中的每一個，都有對應的屬性具有相同的名稱，但全部小寫且沒有前置的 HTTP_。content_length 和 server_port 是整數；其餘的都是字串。

參數¶ ↑

params() 方法會傳回要求中所有參數的雜湊，作為名稱/值清單對，其中值清單是一個包含一個或多個值的 Array。CGI 物件本身也會表現為參數名稱到值的雜湊，但只會傳回每個參數名稱的單一值（作為 String）。

例如，假設要求包含具有多個值「藍色」和「綠色」的參數「favourite_colours」。會發生下列行為

cgi.params["favourite_colours"]  # => ["blue", "green"]
cgi["favourite_colours"]         # => "blue"

如果參數不存在，前一個方法會傳回一個空陣列，後一個會傳回一個空字串。測試參數是否存在最簡單的方法是使用 has_key? 方法。

Cookie¶ ↑

HTTP Cookie 會自動從要求中解析。它們可從 cookies() 存取器取得，它會傳回從 cookie 名稱到 CGI::Cookie 物件的雜湊。

多重部分要求¶ ↑

如果要求的方法是 POST，而其內容類型是 multipart/form-data，則它可能包含上傳的檔案。這些檔案會由 QueryExtension 模組儲存在要求的參數中。參數名稱通常是檔案輸入欄位的 name 屬性。然而，值不是字串，而是 IO 物件，對於小檔案是 IOString，對於較大檔案是 Tempfile。這個物件也有下列額外的單例方法

local_path()

上傳的檔案在本地檔案系統中的路徑

original_filename()

用戶端電腦上的檔案名稱

content_type()

檔案的內容類型

回應¶ ↑

CGI 類別提供傳送標頭和內容輸出至 HTTP 用戶端的方法，並混合 CGI::HtmlExtension 和 CGI::TagMaker 模組的程式化 HTML 產生方法。用於 HTML 產生的 HTML 精確版本在物件建立時指定。

寫入輸出¶ ↑

傳送輸出至 HTTP 用戶端的最簡單方式是使用 out() 方法。這將 HTTP 標頭作為雜湊參數，並透過區塊傳送主體內容。標頭可以使用 http_header() 方法產生為字串。輸出串流可以使用 print() 方法直接寫入。

產生 HTML¶ ↑

每個 HTML 元素都有對應的方法，用於將該元素產生為 String。此方法的名稱與元素相同，全部小寫。元素的屬性作為雜湊傳入，主體則作為無參數區塊傳入，評估為 String。HTML 產生模組知道哪些元素始終為空，並靜默地捨棄任何傳入的主體。它也知道哪些元素需要匹配的關閉標籤，哪些則不需要。但是，它不知道哪些屬性對哪些元素是合法的。

還有一些額外的 HTML 產生方法混合自 CGI::HtmlExtension 模組。這些方法包括不同類型表單輸入的個別方法，以及通常採用特定屬性的元素的方法，其中屬性可以直接指定為參數，而不是透過雜湊。

實用程式 HTML 逸出和其他方法類似於函數。¶ ↑

有些實用程式工具定義在 cgi/util.rb 中。包含後，您可以像函數一樣使用實用程式方法。

使用範例¶ ↑

取得表單值¶ ↑

require "cgi"
cgi = CGI.new
value = cgi['field_name']   # <== value string for 'field_name'
  # if not 'field_name' included, then return "".
fields = cgi.keys            # <== array of field names

# returns true if form has 'field_name'
cgi.has_key?('field_name')
cgi.has_key?('field_name')
cgi.include?('field_name')

小心！cgi['field_name'] 會傳回一個 Array，包含舊的 cgi.rb（包含在 Ruby 1.6 中）

取得雜湊形式的表單值¶ ↑

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

cgi.params 是雜湊。

cgi.params['new_field_name'] = ["value"]  # add new param
cgi.params['field_name'] = ["new_value"]  # change value
cgi.params.delete('field_name')           # delete param
cgi.params.clear                          # delete all params

將表單值儲存至檔案¶ ↑

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

取得多部分表單值¶ ↑

require "cgi"
cgi = CGI.new
value = cgi['field_name']   # <== value string for 'field_name'
value.read                  # <== body of value
value.local_path            # <== path to local file of value
value.original_filename     # <== original filename of value
value.content_type          # <== content_type of value

且值具有 StringIO 或 Tempfile 類別方法。

取得 Cookie 值¶ ↑

require "cgi"
cgi = CGI.new
values = cgi.cookies['name']  # <== array of 'name'
  # if not 'name' included, then return [].
names = cgi.cookies.keys      # <== array of cookie names

且 cgi.cookies 是雜湊。

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

將 http 標頭和 html 字串列印至 $DEFAULT_OUTPUT ($>)¶ ↑

require "cgi"
cgi = CGI.new("html4")  # add HTML generation methods
cgi.out do
  cgi.html do
    cgi.head do
      cgi.title { "TITLE" }
    end +
    cgi.body do
      cgi.form("ACTION" => "uri") do
        cgi.p do
          cgi.textarea("get_text") +
          cgi.br +
          cgi.submit
        end
      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

# add HTML generation methods
CGI.new("html3")    # html3.2
CGI.new("html4")    # html4.01 (Strict)
CGI.new("html4Tr")  # html4.01 Transitional
CGI.new("html4Fr")  # html4.01 Frameset
CGI.new("html5")    # html5

一些公用程式方法¶ ↑

require 'cgi/util'
CGI.escapeHTML('Usage: foo "bar" <baz>')

一些類似函式的公用程式方法¶ ↑

require 'cgi/util'
include CGI::Util
escapeHTML('Usage: foo "bar" <baz>')
h('Usage: foo "bar" <baz>') # alias