hs.http

Коллекция общих HTML-сущностей (&что-либо) и их UTF8-эквивалентов. Для получения UTF8-последовательности для заданной сущности, обратитесь к таблице как hs.http.htmlEntities["&key;"], где key - текст имени сущности или числовая ссылка, например #number.

• Этот список, вероятно, неполный. Он основан на списке общих сущностей, описанных на http://www.freeformatter.com/html-entities.html.

• Дополнительные сущности можно временно добавить с помощью функции hs.http.registerEntity(...). Если вы считаете, что у вас есть более официальный список сущностей, содержащий элементы, которые в настоящее время не включены по умолчанию, откройте вопрос на https://github.com/Hammerspoon/hammerspoon, и ваша ссылка будет рассмотрена.

• Чтобы увидеть список текущих определенных сущностей, включен __tostring-метаметод, поэтому обращение к таблице напрямую как строке вернёт текущие определения.

  • Для справки, этот метаметод по существу следующий:

    for i,v in hs.fnutils.sortByKeys(hs.http.htmlEntities) do print(string.format("%-10s %-10s %s\n", i, "&#"..tostring(hs.utf8.codepoint(v))..";", v)) end

  • Обратите внимание, что этот список не будет включать числовое преобразование сущностей (например, A), поскольку это обрабатывается __index-метаметодом, чтобы позволить все возможные числовые значения.

Асинхронно отправляет HTTP-запрос GET

• url - Строка, содержащая URL для получения
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки
• callback - Функция, которая вызывается при успешном или неудачном выполнении запроса. Функции будут переданы три параметра:
  • Число, содержащее код HTTP-ответа
  • Строка, содержащая тело ответа
  • Таблица, содержащая заголовки ответа

• None

• Если для загрузки запроса требуется аутентификация, необходимые учетные данные должны быть указаны в URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение попытается продолжить без учетных данных.
• Если запрос завершился ошибкой, первый параметр функции обратного вызова будет отрицательным, а второй параметр будет содержать сообщение об ошибке. Третий параметр будет nil

Асинхронно отправляет HTTP-запрос POST

• url - Строка, содержащая URL для отправки
• data - Строка, содержащая тело запроса, или nil, чтобы не отправлять тело
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки
• callback - Функция, которая вызывается при успешном или неудачном выполнении запроса. Функции будут переданы три параметра:
  • Число, содержащее код HTTP-ответа
  • Строка, содержащая тело ответа
  • Таблица, содержащая заголовки ответа

• None

• Если для загрузки запроса требуется аутентификация, необходимые учетные данные должны быть указаны в URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение попытается продолжить без учетных данных.
• Если запрос завершился ошибкой, первый параметр функции обратного вызова будет отрицательным, а второй параметр будет содержать сообщение об ошибке. Третий параметр будет nil

Асинхронно отправляет HTTP-запрос PUT

• url - Строка, содержащая URL для отправки
• data - Строка, содержащая тело запроса, или nil, чтобы не отправлять тело
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки
• callback - Функция, которая вызывается при успешном или неудачном выполнении запроса. Функции будут переданы три параметра:
  • Число, содержащее код HTTP-ответа
  • Строка, содержащая тело ответа
  • Таблица, содержащая заголовки ответа

• None

• Если для загрузки запроса требуется аутентификация, необходимые учетные данные должны быть указаны в URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение попытается продолжить без учетных данных.
• Если запрос завершился ошибкой, первый параметр функции обратного вызова будет отрицательным, а второй параметр будет содержать сообщение об ошибке. Третий параметр будет nil

Преобразует все распознанные HTML-сущности в inString в соответствующие последовательности байтов UTF8 и возвращает преобразованный текст.

• inString -- Строка, содержащая любое количество HTML-сущностей (&whatever;) в тексте.

• outString -- входная строка со всеми распознанными последовательностями HTML-сущностей, преобразованными в последовательности байтов UTF8.

• Распознанные HTML-сущности — это те, которые зарегистрированы в hs.http.htmlEntities или числовые последовательности сущностей: &#n;, где n может быть любым целым числом.
• Эта функция особенно полезна в качестве постфильтра для данных, полученных функциями hs.http.get и hs.http.asyncGet.

Создаёт HTTP-запрос и выполняет его асинхронно

• url - Строка, содержащая URL
• method - Строка, содержащая HTTP-метод (например, "GET", "POST" и т.д.)
• data - Строка, содержащая тело запроса, или nil, чтобы не отправлять тело
• headers - Таблица, содержащая строковые ключи и значения, представляющие ключи и значения заголовков запроса, или nil, чтобы не добавлять заголовки
• callback - Функция, вызываемая при получении ответа. Функция должна принимать три аргумента:
  • code - Число, содержащее код HTTP-ответа
  • body - Строка, содержащая тело ответа
  • headers - Таблица, содержащая HTTP-заголовки ответа
• cachePolicy - Необязательная строка, содержащая политику кэширования ("protocolCachePolicy", "ignoreLocalCache", "ignoreLocalAndRemoteCache", "returnCacheOrLoad", "returnCacheDontLoad" или "reloadRevalidatingCache"). По умолчанию protocolCachePolicy.
• enableRedirect - Необязательный булевый параметр, указывающий, следует ли перенаправлять http-запрос. По умолчанию true.

• None

• Если для загрузки запроса требуется аутентификация, необходимые учетные данные должны быть указаны в URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение попытается продолжить без учетных данных.
• Если заголовок ответа Content-Type начинается с text/, то значение возвращаемого тела ответа является строкой UTF8. Любой другой тип контента передает тело ответа без изменений как поток байтов.
• Если enableRedirect установлен в true, тело ответа будет пустой строкой. Тело http будет опущено, даже если ответ имеет тело. Это, похоже, ограничение метода «connection:willSendRequest:redirectResponse».

Создаёт HTTP-запрос и выполняет его синхронно

• url - Строка, содержащая URL
• method - Строка, содержащая HTTP-метод (например, "GET", "POST" и т.д.)
• data - Необязательная строка, содержащая данные для POST запроса к URL, или nil, чтобы не отправлять данные
• headers - Необязательная таблица с строковыми ключами и значениями, используемыми в качестве заголовков для запроса, или nil, чтобы не добавлять заголовки
• cachePolicy - Необязательная строка, содержащая политику кэширования ("protocolCachePolicy", "ignoreLocalCache", "ignoreLocalAndRemoteCache", "returnCacheOrLoad", "returnCacheDontLoad" или "reloadRevalidatingCache"). По умолчанию protocolCachePolicy.

• Число, содержащее код состояния HTTP-ответа
• Строка, содержащая тело ответа
• Таблица, содержащая заголовки ответа

• Если для скачивания запроса требуется аутентификация, необходимые учетные данные должны быть указаны в части URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение будет пытаться продолжить без учетных данных.

• Эта функция синхронная и, следовательно, заблокирует все выполнение Lua до завершения. Рекомендуется использовать асинхронные функции.

• Если вы пытаетесь подключиться к локальному серверу Hammerspoon, созданному с помощью hs.httpserver, Hammerspoon заблокируется до истечения времени ожидания подключения (60 секунд), вернёт результат с ошибкой из-за таймаута, а затем вызовется функция обратного вызова hs.httpserver (следовательно, любые побочные эффекты функции будут происходить, но её результаты будут потеряны). Используйте hs.http.doAsyncRequest, чтобы избежать этого.

• Если заголовок ответа Content-Type начинается с text/, то возвращаемое значение тела ответа - строка UTF8. Любой другой тип контента передаёт тело ответа без изменений как поток байтов.

Возвращает копию предоставленной строки, в которой символы, не являющиеся допустимыми в ключе или значении HTTP-запроса, экранируются их эквивалентом %##.

• originalString - строка, которую нужно сделать безопасной в качестве ключа или значения для запроса

• преобразованная строка

• Цель этой функции — предоставить допустимый ключ или допустимое значение для строки запроса, а не проверить всю строку запроса. По этой причине знаки ?, =, +, и & включены в преобразованные символы.

Отправляет HTTP-запрос GET на URL

• url - Строка, содержащая URL для извлечения
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки

• Число, содержащее HTTP-код состояния
• Строка, содержащая тело ответа
• Таблица, содержащая заголовки ответа

• Если для скачивания запроса требуется аутентификация, необходимые учетные данные должны быть указаны в части URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение будет пытаться продолжить без учетных данных.
• Эта функция синхронная и, следовательно, блокирует все другие выполнения Lua во время обработки запроса, рекомендуется использовать асинхронные функции.
• Если вы пытаетесь подключиться к локальному серверу Hammerspoon, созданному с помощью hs.httpserver, Hammerspoon заблокируется до истечения времени ожидания подключения (60 секунд), вернёт результат с ошибкой из-за таймаута, а затем вызовется функция обратного вызова hs.httpserver (следовательно, любые побочные эффекты функции будут происходить, но её результаты будут потеряны). Используйте hs.http.asyncGet, чтобы избежать этого.

Отправляет HTTP-запрос POST на URL

• url - Строка, содержащая URL для отправки
• data - Строка, содержащая тело запроса, или nil, чтобы не отправлять тело
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки

• Число, содержащее HTTP-код состояния
• Строка, содержащая тело ответа
• Таблица, содержащая заголовки ответа

• Если для скачивания запроса требуется аутентификация, необходимые учетные данные должны быть указаны в части URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение будет пытаться продолжить без учетных данных.
• Эта функция синхронная и, следовательно, блокирует все другие выполнения Lua во время обработки запроса, рекомендуется использовать асинхронные функции.
• Если вы пытаетесь подключиться к локальному серверу Hammerspoon, созданному с помощью hs.httpserver, Hammerspoon заблокируется до истечения времени ожидания подключения (60 секунд), вернёт результат с ошибкой из-за таймаута, а затем вызовется функция обратного вызова hs.httpserver (следовательно, любые побочные эффекты функции будут происходить, но её результаты будут потеряны). Используйте hs.http.asyncPost, чтобы избежать этого.

Отправляет HTTP-запрос PUT на URL

• url - Строка, содержащая URL для отправки
• data - Строка, содержащая тело запроса, или nil, чтобы не отправлять тело
• headers - Таблица, содержащая строковые ключи и значения, представляющие заголовки запроса, или nil, чтобы не добавлять заголовки

• Число, содержащее HTTP-код состояния
• Строка, содержащая тело ответа
• Таблица, содержащая заголовки ответа

• Если для скачивания запроса требуется аутентификация, необходимые учетные данные должны быть указаны в части URL (например, "http://user:password@host.com/"). Если аутентификация не удалась или учетные данные отсутствуют, подключение будет пытаться продолжить без учетных данных.
• Эта функция синхронная и, следовательно, блокирует все другие выполнения Lua во время обработки запроса, рекомендуется использовать асинхронные функции.
• Если вы пытаетесь подключиться к локальному серверу Hammerspoon, созданному с помощью hs.httpserver, Hammerspoon заблокируется до истечения времени ожидания подключения (60 секунд), вернёт результат с ошибкой из-за таймаута, а затем вызовется функция обратного вызова hs.httpserver (следовательно, любые побочные эффекты функции будут происходить, но её результаты будут потеряны). Используйте hs.http.asyncPost, чтобы избежать этого.

Регистрирует HTML-сущность с указанным кодовым значением Unicode, которая в дальнейшем может быть использована в вашем коде как hs.http.htmlEntity[entity] для удобства и читаемости.

• entity -- Полный текст HTML-сущности, как он представлен в кодированных HTML-документах. Правильная сущность начинается с & и заканчивается ; и метки сущностей, которые не соответствуют этому, будут добавлены — для последующих обращений к соответствующей UTF8 обязательно включайте этот инициатор и терминатор, иначе они не будут распознаны.
• codepoint -- числовое или U+xxxx представление кодового значения Unicode для регистрации с данной сущностью.

• Последовательность байтов UTF8 для зарегистрированной сущности.

• Если метка сущности была ранее зарегистрирована, это перепишет предыдущее значение новым.
• Возвращаемое значение является просто синтаксическим сахаром, и вам не нужно его сохранять локально; его можно безопасно игнорировать — последующий доступ к предварительно преобразованной сущности должен быть получен как hs.http.htmlEntities[entity] в вашем коде. Впрочем, это выглядит неплохо при вызове из консоли ☺.

Возвращает таблицу ключей, содержащих отдельные компоненты предоставленного URL.

• url - URL для разбора на отдельные компоненты

• таблица, содержащая любые из следующих ключей, применимых к указанному URL:
  • absoluteString - Строка URL для URL в виде абсолютного URL.
  • absoluteURL - Абсолютный URL, который ссылается на тот же ресурс, что и предоставленный URL.
  • baseURL - базовый URL, если URL относительный
  • fileSystemRepresentation - Неэкранированный путь URL, указанный как путь файловой системы
  • fragment - фрагмент, если он указан в URL
  • host - хост для URL
  • isFileURL - логическое значение, указывающее, представляет ли URL локальный файл
  • lastPathComponent - последний компонент пути, указанный в URL
  • parameterString - строка параметров, если она указана в URL
  • password - пароль, если он указан в URL
  • path - неэкранированный путь, указанный в URL
  • pathComponents - массив, содержащий компоненты пути URL
  • pathExtension - расширение файла, если оно указано в URL
  • port - порт, если он указан в URL
  • query - запрос, если он указан в URL
  • queryItems - если URL содержит строку запроса, это поле содержит массив неэкранированных пар ключ-значение для каждого элемента. Каждая пара ключ-значение представлена таблицей в массиве для сохранения порядка. См. примечания для получения дополнительной информации.
  • relativePath - относительный путь URL без разрешения по отношению к его базовому URL. Если путь имеет конечный слеш, он удаляется. Если URL уже является абсолютным URL, это содержит то же значение, что и path.
  • relativeString - строковое представление относительной части URL. Если URL уже является абсолютным URL, это содержит то же значение, что и absoluteString.
  • resourceSpecifier - ресурс, указанный в URL
  • scheme - схема URL
  • standardizedURL - URL со всеми экземплярами ".." или "." удаленными из его пути
  • user - имя пользователя, если оно указано в URL

• Эта функция предполагает, что URL соответствует RFC 1808. Если URL некорректен или не соответствует RFC1808, то многие из этих полей могут отсутствовать.

• Пример для URL http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment:

  hs.inspect(hs.http.urlParts("http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment"))

  { absoluteString = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", absoluteURL = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", fileSystemRepresentation = "/path/to a/../file.txt", fragment = "fragment", host = "host.site.com", isFileURL = false, lastPathComponent = "file.txt", parameterString = "parameter", password = "password", path = "/path/to a/../file.txt", pathComponents = { "/", "path", "to a", "..", "file.txt" }, pathExtension = "txt", port = 80, query = "query1=1&query2=a%28", queryItems = { { query1 = "1" }, { query2 = "a(" } }, relativePath = "/path/to a/../file.txt", relativeString = "http://user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", resourceSpecifier = "//user:password@host.site.com:80/path/to%20a/../file.txt;parameter?query1=1&query2=a%28#fragment", scheme = "http", standardizedURL = "http://user:password@host.site.com:80/path/file.txt;parameter?query1=1&query2=a%28#fragment", user = "user" }

• Поскольку для пары ключ-значение запроса допустимо отсутствовать ключ, значение или оба, используются следующие соглашения:

  • отсутствующий ключ (например, '=value') будет представлен как { "" = value }
  • отсутствующее значение (например, 'key=') будет представлено как { key = "" }
  • отсутствующее значение без = (например, 'key') будет представлено как { key }
  • отсутствующий ключ и значение (например, '=') будут представлены как { "" = "" }
  • пустой элемент запроса (например, запрос, заканчивающийся '&', или запрос, содержащий && между двумя другими элементами запроса) будет представлен как { "" }

• В настоящее время Hammerspoon не предоставляет способ представления URL в виде истинного объекта Objective-C в API OS X. Это влияет на следующие ключи:

  • относительные URL не могут быть выражены должным образом, поэтому baseURL всегда будет nil, а relativePath и relativeString всегда будут совпадать с path и absoluteString.
  • Эти ограничения могут быть изменены в будущих обновлениях, если необходимость более полного соответствия обработке URL будет признана необходимой.