Функции поддержки модуля совместимости CGILua для включения и перевода шаблонов Lua в код Lua для выполнения в среде Hammerspoon, чтобы обеспечить динамическое содержимое для запросов http.
Вероятно, наиболее часто используемой функцией будет cgilua.lp.include, которая позволяет включать файл, управляемый шаблоном, во время рендеринга, чтобы общие фрагменты кода можно было повторно использовать проще. Хотя передача собственной таблицы среды для upvalues возможна, это не рекомендуется для общего использования, потому что по умолчанию передаваемая каждой включённой функции среда гарантирует, что все переменные сервера и функции совместимости CGILua доступны с теми же именами, и любые новые переменные, определённые вне области видимости (т.е. «глобальные»), разделяются с окружающей средой вызывающей функции, а не с глобальной средой Hammerspoon.
Если вашему файлу шаблона требуется возможность создавать переменные в глобальной среде Hammerspoon, получите доступ к глобальной среде напрямую через _G.
Обратите внимание, что вышеизложенные соображения относятся только к созданию новых «глобальных» переменных. Любые в настоящее время определенные глобальные переменные (например, таблица hs, где хранятся функции модулей Hammerspoon) доступны в файле шаблона, пока имя не будет использоваться локальной переменной или переменной среды CGILua (например, _G["hs"] и hs относятся к одной и той же таблице).
hs.httpserver.hsminweb.cgilua.lp.compile(source, name, [env]) -> function
Тип
Функция
Описание
Преобразует указанный источник шаблона Lua в функцию Lua.
Параметры
source - строка, содержащая содержимое шаблона Lua/HTML, который необходимо преобразовать в функцию
name - метка, используемая в сообщении об ошибке, если выполнение возвращённой функции приводит к ошибке во время выполнения
env - необязательная таблица, определяющая среду, которая будет использоваться встроенной функцией lua load, при преобразовании источника в функцию. По умолчанию функция унаследует среду своего вызывающего объекта.
Возвращает
Функция lua, которая не должна принимать аргументов.
Примечания
Предоставленный источник сначала сравнивается с сохраненным кешем ранее переведенных шаблонов, и, если шаблон уже встречался, используется существующий перевод. Если источник уникален, вызывается cgilua.lp.translate для источника шаблона.
Эта функция используется внутри cgilua.lp.include и, вероятно, не будет полезна, если вы не хотите перевести динамически сгенерированный шаблон — что имеет последствия для безопасности, в зависимости от того, какие входные данные вы используете для генерации этого шаблона, так как полученный код Lua будет выполняться в вашей среде Hammerspoon. Будьте очень осторожны с входными данными, если решите проигнорировать это предупреждение.
file - строка, содержащая путь к файлу шаблона для включения.
env - необязательная таблица, определяющая среду, которая будет использоваться включенным шаблоном. По умолчанию шаблон унаследует среду своего вызывающего объекта.
Возвращает
Ничего
Примечания
Эта функция вызывается веб-сервером для обработки шаблона, указанного запрошенным URL. Последующие вызовы этой функции могут использоваться для включения общего или повторно используемого кода из других файлов шаблонов и будут включены в строку, где вызывается функция cgilua.lp.include в исходном шаблоне.
Во время обработки веб-запроса локальный каталог временно изменяется, чтобы соответствовать локальному каталогу пути к обслуживаемому файлу, как определено URL запроса. Это обычно отличается от стандартного каталога Hammerspoon, который соответствует каталогу, содержащему файл init.lua для Hammerspoon.
метаметод __index указывает на переменную среды _G в экземпляре Hammerspoon Lua; это означает, что любая глобальная переменная в среде Hammerspoon доступна для кода lua в файле шаблона.
метаметод __newindex указывает на функцию, которая создает новые «глобальные» переменные в среде файлов шаблонов; это означает, что если шаблон включает другой файл шаблона, и этот второй файл шаблона создает «глобальную» переменную, эта новая переменная будет доступна в среде вызывающего шаблона, но не будет разделена с глобальным пространством имен Hammerspoon; «глобальные» переменные, созданные таким образом, будут удалены после завершения HTTP-запроса.
print перезаписывается, так что его вывод передаётся в тело ответа, которое будет возвращено при завершении веб-запроса. Он следует традиционной модели встроенной функции print: несколько аргументов разделены символом табуляции, вывод завершается символом новой строки, нестроковые аргументы преобразуются в строки с помощью встроенной функции tostring.
write определён как альтернатива print и отличается от описанной выше функцией print следующим образом: в вывод, передаваемый в тело ответа, не включаются промежуточные табуляции или новые строки.
cgilua определён как таблица, содержащая все функции, включённые в этот модуль поддержки.
hsminweb определён как таблица, содержащая следующие таблицы, которые могут быть полезны:
CGIVariables - таблица, содержащая пары ключ-значение, эквивалентные данным, доступным через функцию cgilua.servervariable.
id - строка, сгенерированная с помощью hs.host.globallyUniqueString, уникальная для данного HTTP-запроса.
log - таблица/объект, представляющий экземпляр hs.loggerhs.httpserver.hsminweb. Это можно использовать для записи сообщений в консоль Hammerspoon, как описано в документации для hs.logger.
request - таблица, содержащая данные, представляющие подробности HTTP-запроса, сделанного веб-клиентом серверу. Часто встречаются следующие ключи:
headers - таблица, содержащая пары ключ-значение, представляющие заголовки, включенные в HTTP-запрос; в отличие от значений, доступных через cgilua.servervariable или найденных в CGIVariables, эти доступны в исходном формате.
эта таблица также содержит таблицу с ключом "_". Эта таблица содержит функции и данные, используемые внутри, и описана более подробно в дополнительном документе (планируется). Она в основном предназначена для пользовательских функций обработки ошибок, предназначенных для использования с hs.httpserver.hsminweb и обычно не требуется для файлов шаблонов Lua.
method - метод HTTP-запроса, чаще всего "GET" или "POST"
path - часть пути запрошенного URL.
response - таблица, содержащая данные, представляющие формируемый ответ на HTTP-запрос. Это обычно обрабатывается функциями поддержки cgilua, но в особых случаях вы можете изменить её напрямую; она должна содержать только следующие ключи:
body - строка, содержащая тело ответа. По мере вывода содержимого шаблоном Lua эта строка добавляется.
code - целое число, представляющее ожидаемый код ответа для HTTP-запроса.
headers - таблица, содержащая пары ключ-значение текущих определённых заголовков ответа
_tmpfiles - используется внутри для отслеживания временных файлов, используемых при завершении этого HTTP-запроса; не изменяйте напрямую.
Преобразует указанный источник шаблона Lua в код Lua, исполняемый в среде Hammerspoon.
Параметры
source - строка, содержащая содержимое шаблона Lua/HTML, который нужно преобразовать в настоящий код Lua
Возвращает
Код lua, соответствующий предоставленному источнику, который можно передать в встроенную функцию lua load, чтобы создать функцию Lua.
Примечания
Эта функция используется внутри cgilua.lp.include и, вероятно, не будет полезна, если вы не хотите перевести динамически сгенерированный шаблон — что имеет последствия для безопасности, в зависимости от того, какие входные данные вы используете для генерации этого шаблона, так как полученный код Lua будет выполняться в вашей среде Hammerspoon. Будьте очень осторожны с входными данными, если решите проигнорировать это предупреждение.
Чтобы гарантировать, что переведенный код имеет доступ к функциям поддержки cgilua, передайте _ENV в качестве аргумента среды для встроенной функции lua load; в противном случае любой вывод, созданный полученной функцией, будет направлен в консоль Hammerspoon, а не включён в ответ HTTP, отправленный клиенту.
