msra-language.md

MSRA Language Reference

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

Куда идти сначала

• Формат файла: [msra]
• Базовый пакет и runtime-дефолты: [app]
• Стартовый warmup: [app.warmup]
• Общие headers-дефолты: [app.defaults.func.headers]
• Переменные окружения: [app.variables.]
• Переиспользуемые префиксы: [app.prefixes]
• Regex-правила: [app.regexes.]
• Группы клиента: [app.groups.]
• Функции API: [app.func.]
• Аргументы функций: [app.func..input.]
• URL и параметры: [app.func..url]
• Тело запроса: [app.func..body]
• Локальные headers функции: [app.func..headers]
• Extractor для goto: [app.func..extractor]
• Примеры вызова: [app.func..examples]

Дополнительно

• Семантика quoted/unquoted-путей и identity: Пути и identity
• Что не отражено в generated Python-коде: Ограничения генератора

Мультифайловость

Основной .msra файл можно разбивать на дочерние .msraf-фрагменты. Основной файл подключает фрагмент через !include("path/to/file.msraf"), а сам child-файл содержит !root(".../parent.msra") только для LSP, чтобы редактор мог корректно резолвить ссылки во время правки.

Пример:

[app]
name="RootAPI"

[app.func]
!include("funcs.msraf")

!root("./parent.msra")

[GET_USER]
name="get_user"
group=<GROUPS.Catalog>

Правила:

• !include("path/to/file.msraf") обычно пишется внутри [app.func] в основном файле;
• в .msraf пишутся только относительные таблицы функций: [GET_USER], [GET_USER.url], [GET_USER.input.query];
• в .msraf не нужно писать app.func явно, этот префикс добавляется при сборке;
• !root(...) нужен для LSP и не попадает в итоговый merged-файл;
• генератор пишет промежуточный merged.msra, где все .msraf уже вставлены в единый документ без include-ссылок; по умолчанию этот файл удаляется после генерации, --no-cleanup сохраняет его в output.

Как читать язык

Удобно воспринимать MSRA как дерево таблиц:

• [msra] задаёт версию формата.
• [app] задаёт package_name, package_owner, logo, social и глобальное runtime-поведение; logo должен быть монохромным, а генератор сам определяет, пришёл black или white образец, и выпускает webp-пару для docs.
• Остальные таблицы описывают либо shared-настройки, либо конкретные функции и их runtime-контракт.

Если нужен не обзор, а конкретная схема таблицы, открывай соответствующую страницу выше. Каждая из них описывает один namespace и его поведение отдельно, без смешения с остальными.