# Perl Support in Maguyva: Package and Subroutine Graphs

Canonical source: https://maguyva.ai/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 parses Perl with AST, symbol, and graph support, so AI agents can follow packages, subroutines, use and require imports, and constructors in legacy Perl.

## Support snapshot

- Tier: AST and symbol support
- Programming
- Extensions: .perl, .pl, .pm, .pod, .t
- Real AST parsing for syntax-aware search and structural context.
- Named symbols feed semantic lookup and cross-reference. Graph navigation is available when relationship extraction is enabled.
- This language contributes symbols and relationships to graph-aware search; supported edge types vary with its native constructs.
- AST parsing and symbol extraction are both available.

## Best fit

- Teams that inherited Perl services, CGI applications, or batch and reporting scripts that still run in production.
- Module-heavy codebases where `.pm` packages are shared across many scripts and test files.
- Migration or retirement work where the first question is which scripts depend on which modules.

## Agent workflows

- List every script and module that uses a shared package before changing it.
- Find where a class is constructed with `->new` and which subroutines it calls next.
- Trace a report or job from its entry script through the modules it loads.

## Why Perl estates are hard to change safely

Perl code is dense, flexible, and often written by people who left years ago. Sigils change a name's meaning, packages double as classes, and the same module is loaded by scripts in many directories. A text search finds the strings; it does not tell an agent which subroutine a script actually calls.

Maguyva gives the agent packages, subroutines, imports, and constructors as structure, so it can scope a change before touching the code.

## What Maguyva extracts in Perl

Maguyva covers `.pl`, `.pm`, `.t`, `.pod`, and `.perl`. Subroutines are extracted as functions and `package` declarations as classes, and definition names have their sigils (`$`, `@`, `%`, `&`, `*`) stripped so variables and subroutines are searchable by their bare names.

Imports come from `use`, `require`, and `package` statements. Method calls of the form `Class->new` count as instantiation, and `bless` and `tie` are kept in the call graph on purpose. The graph also records inheritance, overrides, type references, reads and writes, and exception raises.

About 189 built-in functions (`print`, `open`, `die`, `warn`, and similar) are filtered from call relationships so repository code stands out.

## Example agent prompts

- "Which scripts use `Billing::Invoice`, and which of its subroutines do they call?" (`dependency_search` incoming)
- "Where is `Report::Monthly` constructed, and what happens after `->new`?" (`find_symbol`, then `get_task_context`)
- "Find every test file that exercises `Auth::Session`." (`text_pattern_search`, then `find_symbol`)

## Known limits

- Classic Perl methods are ordinary `sub` declarations inside a package, so only the newer dedicated `method` syntax is classified as a method in structural search. Use the `functions` preset for older object-oriented Perl.
- Calls to filtered built-ins do not appear as graph edges. Use `text_pattern_search` when you need every `open` or `print` call.

## Next steps

Connect a repository with the [quickstart](/docs/quickstart), then check the support matrix on the [compatibility page](/docs/compatibility). If the estate is moving to another scripting language, compare the [Python guide](/languages/python).

## Engine details

- Perl support covers `.pl`, `.pm`, `.t`, `.pod`, and `.perl`. Subroutines are functions and `package` declarations are classes.
- Sigils are stripped from definition names, `use` and `require` become imports, and `Class->new` counts as instantiation.
- About 189 built-ins such as `print`, `open`, and `die` are filtered from calls, while `bless` and `tie` stay in the graph.

## Useful MCP entry points

- `find_symbol`: Use it for a package or subroutine name; sigils are stripped, so search by the bare name.
- `dependency_search`: Use incoming traversal on a shared module to see which scripts and packages depend on it.
- `text_pattern_search`: Use it for filtered built-ins, config keys, and SQL strings that the call graph leaves out.