library cgi

要約

CGI プログラムの支援ライブラリです。

CGI プロトコルの詳細については以下の文書を参照してください。

https://tools.ietf.org/html/draft-coar-cgi-v11-03
[RFC3875]: The Common Gateway Interface (CGI) Version 1.1
https://www.w3.org/CGI/

使用例

フォームフィールドの値を得る

require "cgi"
cgi = CGI.new
values = cgi['field_name']   # <== 'field_name' の配列
# 'field_name' が指定されていなかったら、 ""を返す。
fields = cgi.keys            # <== field nameの配列

# フォームに 'field_name' というfield nameがあるときに真
cgi.has_key?('field_name')
cgi.include?('field_name')

フォームフィールドの値をハッシュとして得る

フォームの値をハッシュとして得るには 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                          # 全パラメータを消去

フォームフィールドの値をファイルに保存する

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

ただし、PStore は Ruby のバージョンによってデータ互換性がなくなることがあるので、長い期間データを保存することがある場合には検討が必要です。

PStore も参照してください。

マルチパートフィールドの値を取得する（ファイル送信）

require "cgi"
cgi = CGI.new
value = cgi.params['field_name'][0]   # TempFile オブジェクト（10240バイト未満の場合は StringIOオブジェクト）
value.read                            # 本文（送られてきたファイルの中身）
value.local_path                      # ローカルファイルのパス
value.original_filename               # 元の名前
value.content_type                    # content_type

クライアントにクッキーを渡す

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

クライアントからクッキーを得る

require "cgi"
cgi = CGI.new
values = cgi.cookies['name']  # values は name クッキーの値の配列。
                              # name クッキーが存在しない場合は空配列を返す。
names = cgi.cookies.keys      # 全てのクッキーの名前の配列

CGI に関連する環境変数の値を取得する

CGI に関連する環境変数の値は直接 ENV から得る他に、 CGI クラスのメソッドで得ることもできます。基本的には環境変数の名前を downcase したメソッドにマップされます。例えば 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_ を除いた部分を downcase したメソッド名が定義されています。

例
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

CGI に関連する環境変数に関しては http://www.w3.org/CGI/ も参照してください。

標準出力に HTTP ヘッダと 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] を参照してください。

オフラインモード

cgi には、コマンドラインから CGI スクリプトを動かすための仕組み（オフラインモード）があります。コマンドラインから以下のように実行すると、

$ ruby -r cgi some_script.rb
(offline mode: enter name=value pairs on standard input)

と聞いてくるので、

q=hoge&v=foo

などと入力して下さい。クエリーに入力された値がセットされて、スクリプトが実行されます。

なお、Windows 環境の場合、ただ値を入力して Enter を押すだけでは実行されません。キーボードから Ctrl + Z を入力する必要があります。

HTMLエレメント出力用メソッド

新たな CGI オブジェクトを生成する際、引数として特定の文字列を与えることによって、そのオブジェクトに HTML 生成用のメソッドを追加することができます。これらのメソッドを利用することにより、「よりRuby的に」HTML 文書を出力することが可能になります。

例:

cgi = CGI.new("html3")  # HTML3.2に準拠したHTML生成メソッドを追加
cgi.h1
  # <H1></h1>
cgi.h1{ "content" }
  # <H1>content</H1>
cgi.h1({ "class" => "foo", "attr" => "bar" }){ "content" }
  # <H1 class="foo" attr="bar">content</H1>

# HTML生成メソッドを追加
CGI.new("html3")    # html3.2
CGI.new("html4")    # html4.0 (Strict)
CGI.new("html4Tr")  # html4.0 Transitional
CGI.new("html4Fr")  # html4.0 Frameset

HTML 生成メソッドの引数としては、基本的に Hash オブジェクトが与えられる（あるいは何も与えられない）べきです。ただし以下に列挙されたメソッドでは、各メソッドの引数の形式に従って、 Hash オブジェクト以外のものを渡すこともできます。

クラス

CGI	CGI スクリプトを書くために必要な機能を提供するクラスです。
CGI::Cookie	クッキーを表すクラスです。

モジュール

CGI::Html3
CGI::Html4
CGI::Html4Fr
CGI::Html4Tr
CGI::HtmlExtension	HTML を生成するためのメソッドを提供するモジュールです。
CGI::QueryExtension	クエリ文字列を扱うためのメソッドを定義しているモジュールです。
CGI::QueryExtension::Value
CGI::TagMaker

例外クラス

CGI::InvalidEncoding

不正な文字エンコーディングが現れたときに発生する例外です。

同時にrequireされるライブラリ

cgi/cookie	HTTP クッキーを利用するためのクラスを定義したライブラリです。
cgi/core	cgi ライブラリのコア機能を提供するライブラリです。
cgi/html	HTML を生成するためのメソッドを提供するモジュールを定義したライブラリです。
cgi/util	CGI で利用するユーティリティメソッドを定義したライブラリです。

サブライブラリ

cgi/session	CGI のセッション管理を行うライブラリ。
cgi/session/pstore