класс CGI

Обзор

Интерфейс общего шлюза (CGI) — это простой протокол для передачи запроса HTTP от веб-сервера к автономной программе и возврата результата в веб-браузер. В основном, программа CGI вызывается с параметрами запроса, переданными либо в среде (GET), либо через $stdin (POST), и всё, что она выводит в $stdout, возвращается клиенту.

Этот файл содержит класс CGI. Этот класс предоставляет функциональность для извлечения параметров запроса HTTP, управления cookie и генерации HTML-вывода.

Файл CGI::Session предоставляет функциональность управления сеансами; см. этот класс для получения более подробной информации.

Дополнительную информацию о протоколе CGI см. на сайте www.w3.org/CGI.

Введение

Класс CGI является обширным, предоставляя несколько категорий методов, многие из которых взяты из других модулей. Некоторые документы находятся в этом классе, а другие — в модулях CGI::QueryExtension и CGI::HtmlExtension. Дополнительную информацию о работе с cookie см. в CGI::Cookie, а информацию о сеансах — в cgi/session.rb (CGI::Session).

Для запросов класс CGI предоставляет методы для доступа к переменным среды, параметрам, cookie и данным запроса multipart. Для ответов класс CGI предоставляет методы для записи вывода и генерации HTML.

Для получения более подробной информации см. далее. В конце приведены примеры.

Запросы

Класс CGI динамически включает в себя функциональность анализа параметров и cookie, доступ к переменным среды и поддержку анализа запросов multipart (включая загруженные файлы) из модуля 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» со значениями «blue» и «green». Будет наблюдаться следующее поведение:

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

Если параметр не существует, первый метод вернёт пустой массив, второй — пустую строку. Самый простой способ проверить существование параметра — использовать метод has_key?.

Cookie

HTTP Cookie автоматически анализируются из запроса. Они доступны через аксессор cookies(), который возвращает хеш, где ключами являются имена cookie, а значениями — объекты CGI::Cookie.

Запросы multipart

Если метод запроса POST, а тип контента — multipart/form-data, он может содержать загруженные файлы. Модуль QueryExtension сохраняет их в параметрах запроса. Имя параметра — это атрибут name поля ввода файла, как обычно. Однако значение не является строкой, а объектом IO, либо IOString для небольших файлов, либо Tempfile для больших.

local_path()

путь к загруженному файлу в локальной файловой системе

original_filename()

имя файла на компьютере клиента

content_type()

тип контента файла

Ответы

Класс CGI предоставляет методы для отправки заголовков и контента клиенту HTTP и включает методы для программированного генерации HTML из модулей CGI::HtmlExtension и CGI::TagMaker. Конкретная версия 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 вернул 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

Получение значений multipart-формы

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