Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/perl-ide/coc-perl

Enable Perl5 language server on VIM/NeoVIM through coc-nvim.
https://github.com/perl-ide/coc-perl

coc lsp neovim perl vim

Last synced: 24 days ago
JSON representation

Enable Perl5 language server on VIM/NeoVIM through coc-nvim.

Awesome Lists containing this project

README 

        
# coc-perl



Perl Language client for Language Server Protocol through [coc.nvim](https://github.com/neoclide/coc.nvim).



coc-perl



## Language Servers support



This project supports two different language servers:



1. [Perl-LanguageServer](https://github.com/richterger/Perl-LanguageServer);

2. [PerlNavigator](https://github.com/bscan/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](https://github.com/gugod/App-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](https://github.com/bscan/PerlNavigator/tree/main#installation-for-other-editors) 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//PerlNavigator/server/out/server.js`, which will be needed when configuring CoC later on.



### Installing coc-perl



Inside (neo)vim run this command:

```vim

:CocInstall coc-perl

```

or, you can set `g:coc_global_extensions`.

```vim

let g:coc_global_extensions = [

      \ 'coc-perl',

\ ]

```

or even install directly via any plugin manager, for example, with [vim-plug](https://github.com/junegunn/vim-plug):

```vim

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):



```json

{

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

}

```

```json

{

    "perl.enable": true

}

```

And for `navigator`:



```json

{

    "perl.navigator.enable": true,

}

```

or using the original configuration property (not recommended):

```json

{

    "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.

```json

    "perl.navigator.serverPath": "/home//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:

```json

{

    "perl.p::ls.enable": true,

    "perl.p::ls.logLevel": 2,

    "perl.p::ls.logFile": "/home//coc-perl.log",



    "perl.navigator.enable": false,

    "perl.navigator.serverPath": "/home//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](https://github.com/bscan/PerlNavigator/tree/main#perl-paths) and

[Perl-LanguageServer](https://github.com/richterger/Perl-LanguageServer#extension-settings) 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)](https://microsoft.github.io/debug-adapter-protocol/) 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](https://github.com/bmeneg) - Maintainer  

[ulwlu](https://github.com/ulwlu) - Project creator and former maintainer