класс CGI

Обзор

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

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

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

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

Введение

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

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

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

Запросы

Класс CGI динамически подключает функциональность разбора параметров и куки, доступ к переменным среды и поддержку разбора многочастных запросов (включая загруженные файлы) из модуля 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?.

Куки

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

Многочастные запросы

Если метод запроса — 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

Получение значений многочастной формы

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