класс CGI

Обзор

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

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

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

См. www.w3.org/CGI/ для получения дополнительной информации о протоколе CGI.

Введение

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

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

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

Запросы

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

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

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

Куки

HTTP-куки автоматически парсятся из запроса. Они доступны через аксессор cookies(), который возвращает хеш от имени куки до объекта 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.

Получение значений куки

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 — это хеш.

Получение объектов куки

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