Схема сокета парсера Aggrega Wasm
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/wasm-parse-v1beta1.schema.json
Формы данных, которые сокет плагина-парсера принимает (ParseInput) и выдаёт (ParseOutput). Парсер — это преобразователь без состояния и без побочных эффектов, который превращает стороннее текстовое представление в каноническое структурированное дерево JSON, так что любой потребитель на любом языке может прочитать дерево, не имея собственного парсера этого языка. Парсер объявляет поддерживаемые форматы как возможности parse:
Одна из следующих форм
ParseInputParseOutput
Определения
ParseInput
Полезная нагрузка, которую получает гостевой модуль парсера: имя формата, определяющее, как читать байты, исходные байты для разбора и необязательный непрозрачный документ параметров, который потребитель передаёт для поведения, специфичного для парсера.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
format | string | да | Имя исходного формата для разбора, соответствующее одной из заявленных парсером возможностей parse: |
bytes | string | да | Исходные байты для разбора. Каждый набор хранит их в поле собственного типа — в сыром виде, если этот тип байтовый, и в кодировке base64, если это строка, которую парсер декодирует, чтобы восстановить байты, — а сгенерированный кодировщик выполняет преобразование между полем и формой, в которой байты передаются по проводу. Парсер читает восстановленные байты в указанном формате. |
options | любой | нет | Непрозрачный документ параметров, который потребитель передаёт для поведения, специфичного для парсера. Хост передаёт его дальше, не интерпретируя; парсер читает ту форму, которую он документирует. Отсутствует, если потребитель не передаёт параметров. |
Дополнительные свойства не допускаются.
ParseOutput
Полезная нагрузка, которую возвращает гостевой модуль парсера: каноническое структурированное дерево разобранного исходного текста, а также все диагностики, возникшие при разборе, и все диапазоны исходного текста, связывающие узлы дерева с исходными байтами.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
tree | любой | да | Каноническое структурированное представление разобранного исходного текста в виде документа JSON. Здесь «документ JSON» обозначает форму значения, которое выдаёт парсер, — в этом и состоит суть разбора, — а не кодировку, в которой значение передаётся: дерево является документом JSON независимо от того, по какому проводу его передаёт этот сокет. Верхний уровень может быть объектом, массивом или скаляром в соответствии с собственной формой разобранного документа (например, файл JSON может разбираться в любой из них). Хост передаёт дерево дальше непрозрачно, дословно и не интерпретируя его содержимое. |
diagnostics | Diagnostic[] | нет | Диагностики, возникшие при разборе, — например, синтаксическая ошибка или предупреждение. Отсутствует, если разбор не дал ни одной. |
spans | NodeSpan[] | нет | Диапазоны исходного текста, связывающие узлы дерева с их положением в исходных байтах, чтобы потребитель мог сопоставить находку в узле дерева с местом в исходном тексте. Отсутствует, если парсер не сообщает диапазонов. |
error | string | нет | Сообщение о сбое, задаваемое, когда гостевой модуль выполнился, но не смог завершить операцию; отсутствует при успехе. Оно отличается от любых диагностик, которые несёт вывод: диагностики сообщают о проблемах, найденных во время выполнения, которое всё же дало результат, а error сообщает, что сама операция не завершилась. Присутствующую ошибку хост представляет как неудачный вызов плагина. |
Дополнительные свойства не допускаются.
NodeSpan
Диапазон исходного текста для одного узла дерева: JSON Pointer по RFC 6901, адресующий узел в дереве, в паре с диапазоном, указывающим его место в исходных байтах.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
pointer | string | да | JSON Pointer по RFC 6901 в дерево, адресующий узел, местоположение которого указывает этот диапазон. |
span | SourceSpan | да | Диапазон, указывающий место адресуемого узла в исходных байтах. |
Дополнительные свойства не допускаются.
SourceSpan
Диапазон исходных байтов: смещения в байтах — основное, точное местоположение, а номера строки и столбца сопровождают их для понятной человеку диагностики.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
start_offset | integer | да | Смещение первого байта диапазона в исходных данных в байтах, отсчёт с нуля. |
end_offset | integer | да | Смещение в байтах на единицу дальше последнего байта диапазона в исходных данных, так что end_offset минус start_offset — длина диапазона в байтах. |
start_line | integer | да | Номер строки начала диапазона, отсчёт с единицы, для понятной человеку диагностики. |
start_column | integer | да | Номер столбца начала диапазона, отсчёт с единицы, для понятной человеку диагностики. |
end_line | integer | да | Номер строки конца диапазона, отсчёт с единицы, для понятной человеку диагностики. |
end_column | integer | да | Номер столбца конца диапазона, отсчёт с единицы, для понятной человеку диагностики. |
Дополнительные свойства не допускаются.
ParseSourceResponse
Ответ хост-функции parse-source: при успехе — каноническое структурированное дерево, созданное выбранным парсером, при сбое — сообщение об ошибке. Заполнено ровно одно из двух полей. Сбой передаётся внутри ответа, а не через ловушку, так что гостевой модуль-потребитель переносит отсутствие парсера или сбой разбора в собственные диагностики как детерминированный сбой. Это оболочка, которую получает сокет-потребитель, когда просит хост запустить производителя через хост; полезная нагрузка запроса — ParseInput.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
tree | любой | нет | Каноническое структурированное дерево, созданное выбранным парсером при успехе, в виде документа JSON, передаваемого дословно; отсутствует при сбое. Как и для собственного дерева вывода разбора, «документ JSON» обозначает форму значения, а не кодировку, в которой оно передаётся. |
error | string | нет | Сообщение о сбое при сбое, указывающее формат и причину; отсутствует при успехе. |
hostfunc_error_code | string (enum) | нет | Машинно сопоставимый идентификатор сбоя при сбое, взятый из закрытого каталога кодов ошибок хост-функций и задаваемый рядом с понятным человеку сообщением об ошибке; отсутствует при успехе. Этот каталог — фиксированный словарь, называющий способы, которыми может завершиться сбоем хост-функция, и он отличается от словаря условий остановки, регистрируемых компилятором, идентификаторы которых гостевой модуль сообщает в выводе сокета как condition_code и condition_short_code, — имя ключа указывает, к какому из двух относится значение, поэтому они никогда не читаются как один набор. Гостевой модуль выбирает ветвь по этому коду, не разбирая сообщение, а при отсутствии кода (более старый хост) или неизвестном коде (более новый хост) возвращается к сообщению. Допустимые значения: "fetch_request_unreadable", "fetch_input_unavailable", "fetch_failed", "request_unreadable", "request_undecodable", "source_root_unavailable", "source_read_failed", "unknown_selection_op", "source_escape", "producer_consumption_reentry", "no_source_parser", "no_parser_for_format", "parse_failed" |
Дополнительные свойства не допускаются.