Perl Language Server

A fast, native Perl 5 language server extension. Written in Rust for speed and reliability. No runtime dependencies -- just install and code.

Public Alpha -- This extension is under active development. Every feature listed below is wired up and exercised by tests, but as an alpha you will find edge cases where behavior is incomplete or wrong. Please report issues if you encounter problems. For what the project's headline numbers mean (and do not mean), see the status overview.

perl-lsp uses proof-backed answers where it has fresh, source-backed facts and keeps fallback or no-edit behavior where Perl is dynamic, generated, stale, ambiguous, or low confidence. See the editor trust guide for support-tier boundaries, explanations, previews, and copyable receipts.

Features

Navigation and Intelligence

• Go to Definition -- Jump to source-backed definitions where proof is available, with fallback for ambiguous or dynamic cases
• Find References -- Find source-backed usages and keep fallback behavior for unsupported shapes
• Hover Documentation -- Show provenance-backed docs and module-lookup explanations where available
• Auto-completion -- Rank proof-backed variables, functions, and modules while preserving fallback for uncertain candidates
• Signature Help -- Real-time parameter hints as you type function calls
• Symbol Navigation -- Outline view, breadcrumbs, and workspace symbol search with generated/dynamic boundaries labeled or gated

Refactoring and Code Actions

• Rename -- Scoped lexical and package-local renames only where source-backed proof and fallback guards pass
• Preview Safe Delete -- Preview allowed, blocked, or refused symbol deletion before any edit is returned
• Preview Package Rename -- Preview package/compiler-backed rename evidence without authorizing broad edits
• Extract Variable -- Pull out expressions into named variables
• Extract Subroutine -- Create functions from selected code blocks
• Organize Imports -- Sort and clean use statements (Shift+Alt+O)

Diagnostics and Quality

• Real-time Errors -- Syntax and semantic error detection as you type
• Undefined Variables -- Catch typos under use strict
• Unused Variables -- Find dead code
• Missing Pragmas -- Suggest strict and warnings
• Diagnostic Explanations -- Explain PL701/PL109 evidence, fallback, and setup boundaries when receipts are available
• Document Formatting -- Format with perltidy (Shift+Alt+F)

Advanced Features

• Semantic Highlighting -- Context-aware syntax coloring beyond TextMate grammars
• Type Hierarchy -- Navigate inheritance with @ISA and use parent
• Call Hierarchy -- Trace function calls inbound and outbound
• CodeLens -- Inline reference counts above functions
• Inlay Hints -- Type annotations shown inline in the editor
• Code Folding -- Collapse subs, blocks, POD, and heredocs

Debugging (via perl-dap)

• Breakpoints -- Set breakpoints with conditional support
• Step Debugging -- Step into, over, and out of function calls
• Variable Inspection -- View variables, watch expressions, and call stack
• Attach to Process -- Debug running Perl processes by PID or TCP

Debugging is optional and uses perl-dap as a separate adapter. See the debugging guide for setup steps and the required launch configuration.

Test Explorer

• Test Discovery -- Automatic discovery of .t test files
• Run Tests -- Run individual tests or entire files from the Testing panel (Shift+Alt+T)
• TAP Support -- Native Test Anything Protocol result parsing

Extension Coexistence

If VS Code warns that other Perl extensions are installed, keep one provider for navigation, diagnostics, and formatting where possible. Perl Navigator, Perl::Critic, and PerlTidy can overlap with perl-lsp features. If you see duplicate hover, completion, or formatting results, disable the competing feature in one extension and keep the other as the source of truth.

Walkthrough Media

The extension includes a "Get Started" walkthrough in VS Code. Walkthrough media assets and recording notes live in:

• media/walkthrough/README.md
• media/walkthrough/install-health.svg
• media/walkthrough/find-references.svg
• media/walkthrough/extract-variable.svg

Installation

Install from the Visual Studio Marketplace or Open VSX Registry.

Current extension and managed-binary artifacts are public alpha.

# VS Code
code --install-extension EffortlessMetrics.perl-lsp-rs

# VSCodium / Open VSX
codium --install-extension EffortlessMetrics.perl-lsp-rs

# PearAI (VS Code-compatible)
# Install from Open VSX inside PearAI's Extensions view:
# EffortlessMetrics.perl-lsp-rs

The extension automatically downloads the correct perllsp binary for your platform on first activation:

On Linux, auto selects the GNU/glibc archive for mainstream distributions and the musl archive for Alpine Linux or musl-based containers. Set perl-lsp.linuxLibc to gnu, glibc, or musl only when you need to override that detection.

Enterprise / offline / air-gapped deployments

The extension downloads the Perl LSP server binary on first activation. If your environment blocks internet access during extension install or uses a strict proxy, see INTERNAL_DEPLOYMENT.md for:

• Pre-downloading the binary and bundling it with your VSIX
• Using perl-lsp.serverPath to point at a shared binary
• Corporate proxy and certificate configuration

Manual Installation

If you prefer to manage the binary yourself:

# Homebrew via the EffortlessMetrics tap (macOS/Linux)
brew install effortlessmetrics/tap/perllsp

# One-liner (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/EffortlessMetrics/perl-lsp/master/install.sh | bash

# From source
cargo install --git https://github.com/EffortlessMetrics/perl-lsp --package perllsp

Then point the extension to your perllsp binary via perl-lsp.serverPath.

Configuration

All settings are under the perl-lsp.* namespace. Open settings with Ctrl+, and search for "perl-lsp".

Internal / Air-Gapped Deployment

For environments without internet access, set perl-lsp.downloadBaseUrl to an internal server hosting the release archives and SHA256SUMS file. See INTERNAL_DEPLOYMENT.md for details.

Keyboard Shortcuts

Use Ctrl+Shift+P (Command Palette) and search "Perl" to see all available commands.

Supported Perl Features

Modern Perl (5.38+)

• class / method / field keywords
• try / catch / finally blocks
• defer blocks
• Subroutine signatures
• Type constraints

Complete Syntax Support

• Regular expressions with any delimiter (m!pattern!, `s{}{}``)
• Heredocs (all variants including indented <<~)
• Unicode identifiers (my $cafe = 'coffee')
• Postfix dereferencing ($ref->@*)
• Smart match operator (~~)
• Indirect object syntax
• Built-in function signatures with parameter documentation
• XS interface files (.xs) and SWIG interface files (.i) are associated with Perl for bundled syntax highlighting, including common SWIG directives and embedded C/C++ blocks

Commands

Open the command palette (Ctrl+Shift+P) and search for "Perl":

Compatibility

The perllsp binary works with any editor that supports the Language Server Protocol:

Troubleshooting

Server not starting?

1. Open the output channel: Command Palette > "Perl: Show Output Channel"
2. Check that perllsp is available: Command Palette > "Perl: Show Server Version"
3. If auto-download failed, check your network/proxy settings or install manually

Formatting not working?

• Ensure perltidy is installed and available in your PATH
• Check perl-lsp.enableFormatting is true

Diagnostics too noisy?

• Run Perl LSP: Explain This Diagnostic to see whether the warning is a true missing fact, low-confidence evidence, or a dynamic boundary.
• Run Perl LSP: Show Workspace Trust Report if module paths, Perl binary, or setup policy may be involved.
• For Perl binary, @INC, PERL5LIB, perldoc, or DAP module-path mismatches, see the Perl setup troubleshooting guide.
• Set perl-lsp.enableDiagnostics to false to disable diagnostics.
• File an issue with the copied provider receipt if you see false positives.

Known Issues

• Variable/watch rendering in debugger sessions is still evolving; complex Perl structures may appear with placeholder values in some scenarios.
• The Format Document shortcut (Shift+Alt+F) is provided by VS Code's built-in formatter binding. perl-lsp participates through the registered formatting provider when perl-lsp.enableFormatting is enabled.
• On first activation, environments with strict proxies or blocked outbound traffic may fail auto-download. Use perl-lsp.serverPath or perl-lsp.downloadBaseUrl for managed/internal deployment.

Resources

• Source Code
• Issue Tracker
• Changelog
• Open VSX Registry — alternative marketplace for VSCodium and other open-source VS Code derivatives
• Sponsor this project — support continued development

License

MIT