Специальные переменные¶

Variable restas:*default-host-redirect*¶

Хост по-умолчанию, на который будут перенаправлять запросы, адресованные к незарегистрированному хосту.

Variable restas:*bindings*¶

В этой переменной сохраняется набор распарсенных переменных маршрута.

Variable restas:*submodule*¶

Активный submodule, которому принадлежит обрабатываемый маршрут

Variable restas:*route*¶

Обрабатываемый маршрут.

Маршруты¶

Macro restas:define-route (name (template &key (method :get) content-type render-method requirement parse-vars decorators) &body body)¶

Создаёт новый маршрут в текущем модуле

• name - уникальный symbol, являющийся индефикатором маршрута. Один и тот же symbol не может использоваться для различных маршрутов.

• template - шаблон URL, на основе которого проверяется соответствие маршрута запросу. Может содержать переменные, которые непосредственно доступны в теле маршрута.

• method - тип обрабатываемого HTTP-запроса, возможные значения: :GET, :POST, :PUT, :DELETE.

• content-type - Content-Type результата обработки запроса, устанавлиевается в заголовке HTTP-ответа.

• headers - plist с именами заголовков HTTP-ответа и их значениями. Используется объединение с *default-headers*, причем в случае конфликта используются значения из опции маршрута.

• render-method - объект, который будет использоваться в вызове restas:render-object для обработки результата маршрута перед отдачей его клиенту.

• requirement - произвольная функция, которая вызвается для проверки соответствия маршрута условиям запроса. Если результат NIL, то маршрут считается не удовлетворяющим запросу.

• parse-vars - plist с именами переменных (в виде keyword) и функциям их парсинга.

• decorators - список декораторов маршрута, см. Декораторы.

• body - тело обработчика, может содержать произвольный код, результат выполнения которого возвращается клиенту (после обработки с помощью restas:render-object).

Пример объявления тривиального маршрута:

(restas:define-route main ("")
  "<h1>Hello world!</h1>")

Подробнее об определении маршрутов смотрие Маршруты

Function restas:route-symbol (route)¶

Возвращает symbol, связанный с объектом-маршрутом (например, во время обработки запроса такой объект связан с переменной restas:*route*).

Function restas:genurl (route-symbol &rest args)¶

Вычисляет URL маршрута на основе индентифицирующего symbol и набора значений переменных его шаблона (см. restas:define-route)

• route-symbol - индентификатор маршрута

• args - последовательность (в формате plist) имён переменных маршрута и их значений.

Пример:

(restas:genurl 'my-route
               :arg1 "foo"
               :arg2 "bar")

Важно: данная функция работает правильно только для маршрутов, которые находятся в одном модуле с обрабатываемым в момент вызова маршрутом.

Function restas:genurl-submodule (submodule-symbol route-symbol &rest args)¶

Аналогична restas:genurl, но используется для маршрутов из подключаемых с помощью restas:mount-submodule модулей.

• submodule-symbol - индефикатор субмодуля, указаный при его определении с помощю restas:mount-submodule.

Function restas:gen-full-url (route &rest args)¶

Данная функция аналогична restas:genurl за тем исключением, что в генерируемый URL также включается имя хоста.

Function restas:redirect (route-symbol &rest args)¶

Перенаправляет запрос с помощью hunchentoot:redirect для URL, вычисляемого с помощью restas:genurl. Параметры аналогичны параметрам функции restas:genurl.

Function restas:abort-route-handler (obj &key return-code content-typе)¶

Немедленно завершает обработку запроса и передаёт OBJ в restas:render-object для формирование ответа. Если указан keyword параметр RETURN-CODE, то он используется для установки статуса ответа, что позволяет вернуть специальную страницу (500, 404 и т.п.) с произвольным содержанием (по умолчанию такие страницы формируется стандартным образом, не зависимо от возвращаемого обработчиком результата).

Модули¶

Macro restas:define-module (name &rest options)¶

Инициализирует новый модуль: создаёт новый package и проводит его инициализацию (добавляет в него некоторые служебные переменные)

Function restas:initialize-module-instance ((module context))¶

Generic-функция, вызывается при подключении модуля с помощью restas:mount-submodule. Может использваться, например, для дополнительной настройки контекста субмодуля. Должна находиться внутри пакета, определённого с помощью restas:define-module.

Function restas:finalize-module-instance ((module context))¶

Generic-функция, вызывается при повторном вычислении restas:mount-submodule и может использоваться, например, для освобождении ресрсов, выделенных при инциализации субмодуля.

Субмодули¶

Macro restas:mount-submodule (name (module &rest decorators) &rest bindings)¶

Определяет субмодуль, который становится частью модуля, в пакете которого он определяется.

• name - индентификатор (symbol) субмодуля.

• module - package designator присоеденяемого модуля.

• decorators - список декораторов субмодуля, см. Декораторы.

• bindings - набор символов переменных и их значений, определяющий контекст субмодуля. Обработка маршрутов, принадлежащих данному субмодулю, будет производиться в этом контексте с помощью вызова progv.

Пример:

(restas:mount-submodule tmp (#:restas.directory-publisher)
  (restas.directory-publisher:*baseurl* '("tmp"))
  (restas.directory-publisher:*directory* #P"/tmp/"))

Function restas:submodule-symbol (submodule)¶

Возвращает symbol, связанный с объектом-субмодулем (например, во время обработки запроса такой объект связан с переменной restas:*submodule*).

Function restas:submodule-module (submodule)¶

Возвращает package designator, связанный с объектом-субмодулем

Function restas:submodule-parent (submodule)¶

Возвращает субмодуль, к которому присоединён переданный субмодуль. С помощью макроса restas:mount-submodule можно создавать целые иерархии субмодулей.

Macro restas:with-submodule-context (submodule &body body)¶

Позволяет произвольный выполнить код в окружении контекста указанного субмодуля.

Отображение¶

Function restas:render-object (drawer object)¶

Generic-метод, используется для обработки данных, возвращаемых обработчиком маршрутов (определяемого в теле restas:define-route). Если в restas:define-route не указан параметр :render-method, то в качестве объекта drawer используется значение переменной *default-render-method* из модуля, в котором определён обрабатываемый маршрут (она создаётся автоматически при определении модуля с помощью restas:define-module и её значение равно NIL).

Более подробную информацию смотрите в разделе Представление.

Контекст¶

В RESTAS для обеспечения модульности используется механизм, напоминающий Buffer-Local Variables в GNU Emacs.

Macro restas:make-context (&body bindings)¶

Создаёт новый динамический контекст, связывающий динамические переменные со значениями. Пример:

(restas:make-context (restas.directory-publisher:*baseurl* '("tmp"))
                     (restas.directory-publisher:*directory* #P"/tmp/")
                     (restas.directory-publisher:*autoindex* t))

Function restas:context-add-variable (context symbol &optional value)¶

Добавляет новую переменную в контекст

• context - контекст

• symbol - symbol, связанный с динамической переменной

• value - значение переменной, если не указано, то используется результат вызова symbol-value.

Function restas:context-remove-variable (context symbol)¶

Удаляет переменную из контекста

Function restas:context-symbol-value (context symbol => value, present-p)¶

Возращает значение value динамической переменной, если переменная отсутствует в контексте, то для вычисления её значения используется symbol-value, а present-p равен NIL.

Macro restas:with-context (context &body body)¶

Выполняет код в окружении заданного контекста с помощью progv.

Отладка¶

Function restas:debug-mode-on ()¶

Устанавливает отладочный режим.

Function restas:debug-mode-off ()¶

Отменяет отладочный режим.

Variable restas:*max-debugging-threads*¶

Максимально колличество одновременно отлаживаемых поток.