класс CGI

Обзор

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

Например, предположим, что запрос содержит параметр «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-элемент имеет соответствующий метод для генерации этого элемента в виде строки. Название этого метода совпадает с именем элемента, приведённым в нижнем регистре. Атрибуты элемента передаются в виде хеша, а тело — в качестве блока без аргументов, возвращающего строку. Модуль генерации 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 возвращает массив со старой версией 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