Схема сокета парсера 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 | any | ні | Непрозорий документ параметрів, який споживач надає для специфічної поведінки парсера. Хост передає його далі, не інтерпретуючи; парсер читає ту форму, яку він документує. Відсутній, якщо споживач не надає параметрів. |
Додаткові властивості не дозволені.
ParseOutput
Дані, які повертає гостьовий модуль парсера: канонічне структуроване дерево розібраного джерела, а також будь-яка діагностика, що виникла під час розбору, і будь-які діапазони джерела, що зіставляють вузли дерева з початковими байтами.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
tree | any | так | Канонічне структуроване представлення розібраного джерела у вигляді документа 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 | any | ні | Канонічне структуроване дерево, яке визначений парсер створив у разі успіху, у вигляді документа 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" |
Додаткові властивості не дозволені.