# Perl в Maguyva: графы пакетов и подпрограмм

Canonical source: https://maguyva.ai/ru/languages/perl

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Maguyva поддерживает Perl с AST, символами и графом, чтобы ИИ-агенты отслеживали пакеты, подпрограммы, импорты use и require и конструкторы в унаследованном Perl.

## Сводка поддержки

- Уровень: Поддержка AST и символов
- Программирование
- Расширения: .perl, .pl, .pm, .pod, .t
- Настоящий AST-разбор для синтаксически осведомлённого поиска и структурного контекста.
- Именованные символы обеспечивают семантический поиск и перекрёстные ссылки. Навигация по графу доступна, когда включено извлечение связей.
- Этот язык добавляет символы и связи в поиск с учётом графа; поддерживаемые типы рёбер зависят от присущих ему конструкций.
- Доступны и AST-разбор, и извлечение символов.

## Лучше всего подходит

- Команды, которым достались сервисы на Perl, CGI-приложения или пакетные и отчётные скрипты, всё ещё работающие в продакшене.
- Кодовые базы с упором на модули, где пакеты `.pm` используются многими скриптами и тестовыми файлами.
- Миграция или вывод из эксплуатации, где первый вопрос — какие скрипты зависят от каких модулей.

## Сценарии работы агента

- Перечислить все скрипты и модули, использующие общий пакет, прежде чем его менять.
- Найти, где класс создаётся через `->new` и какие подпрограммы вызываются дальше.
- Проследить отчёт или задание от стартового скрипта через загружаемые модули.

## Почему наследие на Perl трудно безопасно менять

Код на Perl плотный, гибкий и часто написан людьми, ушедшими много лет назад. Сигилы меняют смысл имени, пакеты одновременно служат классами, а один и тот же модуль загружают скрипты из многих каталогов. Текстовый поиск находит строки, но не говорит агенту, какую подпрограмму скрипт вызывает на самом деле.

Maguyva даёт агенту пакеты, подпрограммы, импорты и конструкторы в виде структуры, чтобы он очертил границы изменения, прежде чем трогать код.

## Что Maguyva извлекает из Perl

Maguyva охватывает `.pl`, `.pm`, `.t`, `.pod` и `.perl`. Подпрограммы извлекаются как функции, объявления `package` — как классы, а из имён определений удаляются сигилы (`$`, `@`, `%`, `&`, `*`), поэтому переменные и подпрограммы ищутся по голому имени.

Импорты строятся из операторов `use`, `require` и `package`. Вызовы методов вида `Class->new` считаются созданием экземпляров, а `bless` и `tie` намеренно остаются в графе вызовов. Граф также фиксирует наследование, переопределения, ссылки на типы, чтения и записи, а также возбуждение исключений.

Около 189 встроенных функций (`print`, `open`, `die`, `warn` и подобные) отфильтровываются из связей вызовов, чтобы код репозитория был на виду.

## Примеры промптов для агентов

- «Какие скрипты используют `Billing::Invoice` и какие его подпрограммы вызывают?» (`dependency_search` incoming)
- «Где создаётся `Report::Monthly` и что происходит после `->new`?» (`find_symbol`, затем `get_task_context`)
- «Найди все тестовые файлы, которые проверяют `Auth::Session`.» (`text_pattern_search`, затем `find_symbol`)

## Известные ограничения

- Классические методы Perl — это обычные объявления `sub` внутри пакета, поэтому в структурном поиске методом считается только новый специальный синтаксис `method`. Для старого объектно-ориентированного Perl используйте пресет `functions`.
- Вызовы отфильтрованных встроенных функций не появляются как рёбра графа. Если нужен каждый вызов `open` или `print`, используйте `text_pattern_search`.

## Следующие шаги

Подключите репозиторий по [быстрому старту](/ru/docs/quickstart), затем изучите матрицу поддержки на [странице совместимости](/ru/docs/compatibility). Если наследие переезжает на другой скриптовый язык, сравните с [руководством по языку Python](/ru/languages/python).

## Детали движка

- Поддержка Perl охватывает `.pl`, `.pm`, `.t`, `.pod` и `.perl`. Подпрограммы являются функциями, а объявления `package` — классами.
- Из имён определений удаляются сигилы, `use` и `require` становятся импортами, а `Class->new` считается созданием экземпляра.
- Около 189 встроенных функций, таких как `print`, `open` и `die`, отфильтровываются из вызовов, а `bless` и `tie` остаются в графе.

## Полезные точки входа MCP

- `find_symbol`: Используйте с именем пакета или подпрограммы; сигилы удаляются, поэтому ищите по голому имени.
- `dependency_search`: Используйте обход incoming для общего модуля, чтобы увидеть, какие скрипты и пакеты от него зависят.
- `text_pattern_search`: Используйте для отфильтрованных встроенных функций, ключей конфигурации и SQL-строк, которые граф вызовов не охватывает.