coc-perl

Perl Language client for Language Server Protocol through coc.nvim.

Language Servers support

This project supports two different language servers:

1. Perl-LanguageServer;
2. PerlNavigator.

Being that each has its own characteristics and are differentiated through the way you enable and configure them in CoC configuration file.

Installation

In the current version of coc-perl, both supported language servers are automatically installed in case you don't have it already, meaning you only need to define which server you want to enable in CoC configuration.

Prerequisites

For Perl::LanguageServer you need to have cpan installed in your host system. The way coc-perl installs it is by executing cpan Perl::LanguageServer with a specific version (the latest supported version). However, you can manually install it on your system or your local library path in case you're using PerlBrew, preventing any installation done by coc-perl.

Now, for PerlNavigator, coc-perl also handles it automatically, but it requires git to be installed. In case you decide to install it manually, since it's not present in CPAN and its initialization is entirely written in TypeScript rather than Perl, you need to follow what's described on PerlNavigator repository about installing it on other editors. In summary, you need to clone the repository, install the server running the npx tsc command from within server's folder and take note of the absolute path for the generated code, for instance /home/<user>/PerlNavigator/server/out/server.js, which will be needed when configuring CoC later on.

Installing coc-perl

Inside (neo)vim run this command:

:CocInstall coc-perl

or, you can set g:coc_global_extensions.

let g:coc_global_extensions = [
      \ 'coc-perl',
\ ]

or even install directly via any plugin manager, for example, with vim-plug:

Plug 'bmeneg/coc-perl'

Automatic language server installation

When coc-perl is installed for the first time, you probably won't have any configuration referring to what language server you want to enable, thus neither Perl::LanguageServer nor PerlNavigator will be installed. Make sure to after installing coc-perl, enable one of the servers in coc.nvim configuration file (keep reading the next sections to know how perform such action) and then reopen a Perl file or, in case you're already with a Perl file opened, call :CocRestart, so the automatic installation process can take place considering the choice you made regarding the language server.

Choosing a Language Server

To enable a language server an option must be added to the coc-settings.json file, which can be accessed through the (neo)vim command :CocConfig. However, before directly enabling them, it's important to understand how the configuration properties are defined for each server.

Configuration properties

As said before, coc-perl supports two different Perl language servers: Perl::LanguageServer (hereafter referred as p::ls) and PerlNavigator (hereafter referred as navigator). Each has its own set of options to be set on :CocConfig and coc-perl support them completely.

Originally, for those using p::ls in VSCode or older versions of coc-perl, the default properties can be used, like perl.*, while for newcomers, it's recommended the new coc-perl format to avoid confusion, perl.p::ls.*. Now, for navigator, the original format is also supported, perlnavigator.*, but in the same way the new format is recommended when using it with coc-perl, perl.navigator.*.

Enabling one server

Only one language server can be enabled at a time. In case both are enabled, an error will be prompted on :CocOpenLog and no server action will be seen on (neo)vim's buffer.

For enabling p::ls, you can use either options (the first is preferred):

{
    "perl.p::ls.enable": true
}

{
    "perl.enable": true
}

And for navigator:

{
    "perl.navigator.enable": true,
}

or using the original configuration property (not recommended):

{
    "perlnavigator.enable": true,
}

If you're using a development branch of navigator, manually downloaded and/or installed, you'll need one additional option: the server absolute path.

    "perl.navigator.serverPath": "/home/<user>/PerlNavigator/server/out/server.js"

Other options

As user, you can change and pass different options to each language server, however, the options are tied to the server version being used. Because of that, make sure to always run the newest version of the server alongside the coc-perl extension. A brief example of using different options are as follows:

{
    "perl.p::ls.enable": true,
    "perl.p::ls.logLevel": 2,
    "perl.p::ls.logFile": "/home/<user>/coc-perl.log",

    "perl.navigator.enable": false,
    "perl.navigator.serverPath": "/home/<user>/PerlNavigator/server/out/server.js"
}

You can have options for both servers in the configuration file, but only one server can be enabled at a time, meaning that options for the disabled server won't reach the enabled server.

For a detailed list of all options, please visit PerlNavigator and Perl-LanguageServer repositories.

Differences from VSCode extension

Unfortunatelly not all features supported in the original VSCode extension are available in coc-perl due to the differences between VSCode extension core code and coc.nvim. Although Language Server Protocol is fully compatible, the Debug Adapter Protocol (DAP) is missing from coc.nvim, cause the features related to lauching and debugging Perl code non-existent on (neo)vim through coc-perl.

For those navigating the extension code will notice some "DAP-related" variables are defined and "used", but in reality they have no operation at all, serving just as placeholders to allow transparent use of VSCode extension configuration file. Working is being done in different fronts to get DAP support to neovim as soon as possible, but a third plugin might be required (besides coc.nvim and coc-perl).

Whenever a decent and full-featured support lands through another project, instructions will be presented in this README file.

Troubleshooting

Before filling an issue, it's important to gather some information to use as entry point. Make sure to copy the contents from :CocConfig, :CocOpenLog and :CocCommand workspace.showOutput.

:CocConfig is important to understand how you're trying to use the extension and the server. :CocOpenLog shows the log for coc.nvim itself, when trying to initialize the extension and the server. Finally, when issuing :CocCommand workspace.showOutput a selections window will pop up to choose the server (Perl::LanguageServer or PerlNavigator) and, once you have done that, any errors from the server will be shown in a new buffer. Only then, an issue can be filled with all this information presented inline.

But remember, server's code are far more complicated than this client extension, meaning that most of the bugs will be related to the server. Make sure to search for the symptoms you're experiencing in server's repository either.

Maintainers

bmeneg - Maintainer
ulwlu - Project creator and former maintainer