Perl Navigator Language Server

Perl Navigator is a Language Server implemented using Microsoft's LSP libraries. It uses Perl itself for syntax checking and parsing to provide the following features:

• Syntax Checking: Real-time error detection.
• Perl Critic: Static code analysis and suggestions.
• Autocompletion: Smart, context-aware completion.
• Code Navigation: "Go To Definition" support, including installed modules and compile-time dependencies.
• Code Formatting: Integration with Perl::Tidy.
• Import Management: Cleanup of imports via perlimports.
• Code Intelligence: Outline view, hover details for objects/subs/modules, and syntax highlighting for Object::Pad, Moose, Zydeco, etc.
• Class Support: Support for classes including Moo and Moose styles.

Using eglot

If using eglot (built-in to Emacs 29+), use the following configuration to set the Perl path and register the server:

(setq-default eglot-workspace-configuration
               '((:perlnavigator . (:perlPath
                                   "/path/to/perl"
                                   :enableWarnings t))))

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `((cperl-mode perl-mode) . ("/path/to/perlnavigator", "--stdio"))))

(global-company-mode)

(add-hook 'cperl-mode-hook 'eglot-ensure)
(add-hook 'perl-mode-hook 'eglot-ensure)

Using lsp-mode

lsp-mode detects perlnavigator automatically if it is on your PATH. To specify a custom executable, use lsp-perlnavigator-executable:

(use-package lsp-mode
  ...
  :custom (lsp-perlnavigator-executable (expand-file-name "~/path/to/perlnavigator))
  ...)

You can install the server via Homebrew, NPM, or by downloading binaries.

Homebrew (macOS/Linux):

brew install perlnavigator

NPM (Global):

sudo npm install -g perlnavigator-server

Installing via NPM places the executable at /usr/bin/perlnavigator, which can be used by most editors without additional arguments.

Binaries: Download pre-built releases for Windows, Linux, and MacOS from the GitHub Releases page.

The simplest way to install the Perl Navigator Language Server is globally using npm. This installs the perlnavigator-server package and provides the perlnavigator executable in your system path (e.g., /usr/bin/perlnavigator).

sudo npm install -g perlnavigator-server

You can configure coc.nvim directly via :CocConfig or by using the coc-perl extension.

Direct Configuration:

{
  "languageserver": {
    "perlnavigator": {
      "command": "node",
      "args": [
        "/path/to/PerlNavigator/server/out/server.js",
        "--stdio"
      ],
      "filetypes": ["perl"]
    }
  }
}

Using coc-perl (Recommended):

1. Install the extension: :CocInstall coc-perl
2. Configure in :CocConfig:

{
  "perlnavigator.enable": true,
  "perlnavigator.serverPath": "/path/to/PerlNavigator/server/out/server.js"
}

Install the official VSCode extension from the Marketplace: bscan.perlnavigator.

Important Notes:

• Most dependencies are bundled with the extension and work out of the box.
• Perl::Critic and perlimports are not bundled and must be installed independently via CPAN or your package manager to enable those specific features.

Neovim requires nvim-lspconfig. You can use mason.nvim and mason-lspconfig.nvim to automate installation.

Simple Configuration:

require'lspconfig'.perlnavigator.setup{ cmd = { "perlnavigator" } }

Advanced Configuration:

require'lspconfig'.perlnavigator.setup{
    cmd = { "perlnavigator" },
    settings = {
      perlnavigator = {
          perlPath = 'perl',
          enableWarnings = true,
          perltidyProfile = '',
          perlcriticProfile = '',
          perlcriticEnabled = true,
      }
    }
}

The ParseType determines the depth and scope of the parsing logic applied to the Perl document. This controls which internal parsing functions (like subs, localVars, or dancer) are executed.

• ParseType.outline: Used for generating a high-level structural view of the file.
• ParseType.selfNavigation: Used for advanced features like symbol navigation, including variable tracking.
• ParseType.refinement: A lightweight mode focused on subroutines and class fields.

If you use a non-standard Perl installation, you can configure the paths in your VSCode settings:

• perlnavigator.perlPath: Set this to the path of your Perl executable.
• perlnavigator.includePaths: Add additional paths to the Perl search path (@INC). You can use the $workspaceFolder placeholder, which will be replaced by the full path of the current workspace folder. In multi-root workspaces, each folder will be added to the path.

Note: The ./lib subfolder is added to the path automatically.