# Perl no Maguyva: grafos de pacotes e sub-rotinas

Canonical source: https://maguyva.ai/pt-br/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).

O Maguyva oferece suporte a Perl com AST, símbolos e grafo, para que agentes de IA sigam pacotes, sub-rotinas, importações use e require e construtores em Perl legado.

## Panorama de suporte

- Nível: Suporte a AST e símbolos
- Programação
- Extensões: .perl, .pl, .pm, .pod, .t
- Parsing real de AST para busca com consciência de sintaxe e contexto estrutural.
- Símbolos nomeados alimentam a busca semântica e as referências cruzadas. A navegação por grafo fica disponível quando a extração de relações está habilitada.
- Esta linguagem fornece símbolos e relações para a busca orientada por grafo; os tipos de aresta compatíveis variam de acordo com seus construtos nativos.
- A análise de AST e a extração de símbolos estão disponíveis.

## Uso ideal

- Equipes que herdaram serviços em Perl, aplicações CGI ou scripts de lote e relatórios que ainda rodam em produção.
- Bases de código centradas em módulos, em que pacotes `.pm` são compartilhados por muitos scripts e arquivos de teste.
- Trabalhos de migração ou desativação em que a primeira pergunta é quais scripts dependem de quais módulos.

## Fluxos de trabalho de agente

- Listar todos os scripts e módulos que usam um pacote compartilhado antes de mudá-lo.
- Encontrar onde uma classe é construída com `->new` e quais sub-rotinas ela chama em seguida.
- Rastrear um relatório ou job desde o script de entrada pelos módulos que ele carrega.

## Por que é difícil mudar Perl com segurança

Código Perl é denso, flexível e muitas vezes escrito por pessoas que saíram há anos. Sigils mudam o sentido de um nome, pacotes servem também como classes, e o mesmo módulo é carregado por scripts em muitos diretórios. Uma busca textual encontra as strings, mas não diz a um agente qual sub-rotina um script realmente chama.

O Maguyva entrega ao agente pacotes, sub-rotinas, importações e construtores como estrutura, para que ele delimite uma mudança antes de mexer no código.

## O que o Maguyva extrai em Perl

O Maguyva cobre `.pl`, `.pm`, `.t`, `.pod` e `.perl`. Sub-rotinas são extraídas como funções e declarações `package` como classes, e os nomes de definição têm os sigils (`$`, `@`, `%`, `&`, `*`) removidos, para que variáveis e sub-rotinas sejam encontradas pelo nome simples.

As importações vêm das instruções `use`, `require` e `package`. Chamadas de método na forma `Class->new` contam como instanciação, e `bless` e `tie` são mantidos de propósito no grafo de chamadas. O grafo também registra herança, sobrescritas, referências de tipo, leituras e escritas, e lançamento de exceções.

Cerca de 189 funções embutidas (`print`, `open`, `die`, `warn` e semelhantes) são filtradas das relações de chamada para que o código do repositório se destaque.

## Exemplos de prompts para agentes

- "Quais scripts usam `Billing::Invoice` e quais das suas sub-rotinas eles chamam?" (`dependency_search` incoming)
- "Onde `Report::Monthly` é construído e o que acontece depois de `->new`?" (`find_symbol`, depois `get_task_context`)
- "Encontre todos os arquivos de teste que exercitam `Auth::Session`." (`text_pattern_search`, depois `find_symbol`)

## Limitações conhecidas

- Métodos Perl clássicos são declarações `sub` comuns dentro de um pacote, então na busca estrutural só a sintaxe dedicada mais recente `method` é classificada como método. Use o preset `functions` para Perl orientado a objetos mais antigo.
- Chamadas a funções embutidas filtradas não aparecem como arestas do grafo. Use `text_pattern_search` quando precisar de cada chamada a `open` ou `print`.

## Próximos passos

Conecte um repositório pelo [início rápido](/pt-br/docs/quickstart) e depois confira a matriz de suporte na [página de compatibilidade](/pt-br/docs/compatibility). Se o acervo está migrando para outra linguagem de script, compare com o [guia de Python](/pt-br/languages/python).

## Detalhes do motor

- O suporte a Perl cobre `.pl`, `.pm`, `.t`, `.pod` e `.perl`. Sub-rotinas são funções e declarações `package` são classes.
- Sigils são removidos dos nomes de definição, `use` e `require` viram importações, e `Class->new` conta como instanciação.
- Cerca de 189 funções embutidas como `print`, `open` e `die` são filtradas das chamadas, enquanto `bless` e `tie` continuam no grafo.

## Pontos de entrada MCP úteis

- `find_symbol`: Use com o nome de um pacote ou sub-rotina; os sigils são removidos, então busque pelo nome simples.
- `dependency_search`: Use a travessia incoming em um módulo compartilhado para ver quais scripts e pacotes dependem dele.
- `text_pattern_search`: Use para funções embutidas filtradas, chaves de configuração e strings SQL que o grafo de chamadas deixa de fora.