Perl Navigator Language Server

Common errors

• command not found: perlnavigator

  cause The `perlnavigator` executable is not in your system's PATH, or the global npm install failed or was not performed.
  fix Run `sudo npm install -g perlnavigator-server` to install globally, or ensure the installation directory is added to your system's PATH environment variable. If installing from source, ensure `npx tsc` was run in the `server/` directory and your editor configuration points to the correct `server/out/server.js` path.

• No Syntax Highlighting, nor Code completion. Also the imported Scalar Package is not recognised.

  cause The Perl Navigator server is running but cannot find your Perl executable or is not correctly resolving Perl modules due to incorrect include paths.
  fix Verify and set the `perlnavigator.perlPath` setting in your editor's LSP configuration to the absolute path of your Perl executable. Also, add directories containing your project's Perl modules to `perlnavigator.includePaths` (e.g., `"perlnavigator.includePaths": ["$workspaceFolder/lib", "/path/to/cpan_modules"]`).

• Perl::Critic diagnostics or Perl::Tidy formatting not working, or 'perlimports' does not clean up code.

  cause The Perl modules `Perl::Critic`, `Perl::Tidy`, or `perlimports` are either not installed on your system or the Perl Navigator configuration for their profiles is incorrect.
  fix Install the necessary Perl modules via CPAN (e.g., `cpanm Perl::Critic Perl::Tidy perlimports`). Additionally, check your editor's LSP settings for `perlnavigator.perlcriticEnabled`, `perlnavigator.perlcriticProfile`, `perlnavigator.perltidyProfile`, and `perlnavigator.perlimportsProfile` to ensure they are enabled and point to valid profile files if custom ones are used.

Warnings

• gotcha Perl Navigator is a Language Server, an executable application, not a traditional JavaScript/TypeScript library designed for programmatic imports into other Node.js projects. Its interaction model is via the Language Server Protocol (LSP) through editor integrations. Attempting to `import` or `require` symbols directly from the `perlnavigator-server` package will likely result in unexpected behavior or errors, as its main export is the server's entry point, not a library API.
  Fix: Interact with Perl Navigator by configuring your code editor's LSP client to run the `perlnavigator` executable, typically installed globally via npm. Do not attempt to import it as a library in your JavaScript/TypeScript code.
• gotcha For features like static analysis (Perl::Critic), code formatting (Perl::Tidy), and imports cleanup (perlimports), the corresponding Perl modules are NOT bundled with `perlnavigator-server`. These modules must be installed separately via CPAN on your system for Perl Navigator to utilize them.
  Fix: Install required Perl modules using CPAN (e.g., `cpanm Perl::Critic Perl::Tidy perlimports`) and ensure your Perl environment is correctly configured and accessible by the server.
• gotcha If Perl is installed in a non-standard location or if you are using a Perl environment manager (like `perlbrew`), you might need to explicitly configure the `perlnavigator.perlPath` setting in your editor's LSP client. The server might fail to find your Perl executable, leading to non-functional language features.
  Fix: Set the `perlnavigator.perlPath` configuration option to the full, absolute path of your Perl executable (e.g., `"/home/user/perl5/perlbrew/perls/perl-5.38.2/bin/perl"`). Avoid aliases or relative paths.
• gotcha When developing in environments with specialized Perl setups, such as Docker containers or complex multi-root workspaces, Perl Navigator might not find custom modules. It's crucial to correctly configure `perlnavigator.perlPath` and `perlnavigator.includePaths` to reflect the Perl environment and module directories within your project.
  Fix: Use LSP client settings to define `perlnavigator.perlPath` and an array of `perlnavigator.includePaths` (which map to Perl's `@INC`). For containerized setups, this often involves careful path mapping or custom wrapper scripts for `perlPath`. The `$workspaceFolder` variable can be used in `includePaths` to reference project roots.
• gotcha The `perlimports` feature, used for cleaning up imports, requires the file you are working on to be saved to disk for accurate results due to implementation limitations. Real-time updates for `perlimports` diagnostics might not occur until after a save action.
  Fix: Ensure you save your Perl file before expecting `perlimports` features (like diagnostics or formatting) to reflect the latest changes. This is standard behavior for this specific feature.
• gotcha If you are installing Perl Navigator from source by cloning the GitHub repository, merely running `npm install` in the root might not be sufficient. The TypeScript source code for the server (`server/src/server.ts`) needs to be compiled to JavaScript (`server/out/server.js`) using `npx tsc` within the `server/` directory before the server executable is available.
  Fix: After cloning and running `npm install`, navigate to the `server/` directory and execute `npx tsc` to compile the server code. Then, you can reference `server/out/server.js` when configuring your LSP client.

Install

• npm install perlnavigator-server npm
• yarn add perlnavigator-server yarn
• pnpm add perlnavigator-server pnpm

Quickstart

Demonstrates a typical LSP client configuration for Perl Navigator, showing how to invoke the server executable and configure basic settings like Perl path and include directories. This is how editors interact with the server.

{
  "languageserver": {
    "perl": {
      "command": "perlnavigator",
      "args": ["--stdio"],
      "filetypes": ["perl", "cperl", "pl", "pm", "t", "cgi", "psgi"],
      "rootPatterns": [
        "cpanfile",
        "META.json",
        "META.yml",
        ".git",
        "perlnavigator.json"
      ],
      "settings": {
        "perlnavigator.perlPath": "/usr/bin/perl",
        "perlnavigator.includePaths": ["$workspaceFolder/lib"],
        "perlnavigator.perlcriticEnabled": true
      }
    }
  }
}