{"id":13600748,"url":"https://github.com/perl-ide/coc-perl","last_synced_at":"2025-04-13T06:05:28.286Z","repository":{"id":45916372,"uuid":"294856751","full_name":"perl-ide/coc-perl","owner":"perl-ide","description":"Enable Perl5 language server on VIM/NeoVIM through coc-nvim.","archived":false,"fork":false,"pushed_at":"2025-02-03T19:26:58.000Z","size":768,"stargazers_count":35,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T06:04:52.048Z","etag":null,"topics":["coc","lsp","neovim","perl","vim"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/coc-perl","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perl-ide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-09-12T02:46:53.000Z","updated_at":"2025-02-03T19:13:29.000Z","dependencies_parsed_at":"2024-01-16T23:26:09.023Z","dependency_job_id":null,"html_url":"https://github.com/perl-ide/coc-perl","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.3392857142857143,"last_synced_commit":"daaa45d6ffc6e5d4cef49c5e2f35bb45c4559d6d"},"previous_names":["perl-ide/coc-perl","bmeneg/coc-perl"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perl-ide%2Fcoc-perl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perl-ide%2Fcoc-perl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perl-ide%2Fcoc-perl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perl-ide%2Fcoc-perl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perl-ide","download_url":"https://codeload.github.com/perl-ide/coc-perl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670437,"owners_count":21142904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coc","lsp","neovim","perl","vim"],"created_at":"2024-08-01T18:00:47.803Z","updated_at":"2025-04-13T06:05:28.239Z","avatar_url":"https://github.com/perl-ide.png","language":"TypeScript","funding_links":[],"categories":["Language Support"],"sub_categories":[],"readme":"# coc-perl\n\nPerl Language client for Language Server Protocol through [coc.nvim](https://github.com/neoclide/coc.nvim).\n\n\u003cimg width='400' alt=\"coc-perl\" src=\"https://user-images.githubusercontent.com/41639488/93008922-91aad880-f5b5-11ea-995b-3097806a4327.png\"\u003e\n\n## Language Servers support\n\nThis project supports two different language servers:\n\n1. [Perl-LanguageServer](https://github.com/richterger/Perl-LanguageServer);\n2. [PerlNavigator](https://github.com/bscan/PerlNavigator).\n\nBeing that each has its own characteristics and are differentiated through the way you enable and configure them in\nCoC configuration file.\n\n## Installation\n\nIn the current version of coc-perl, both supported language servers are automatically installed in case you don't have\nit already, meaning you only need to define which server you want to enable in CoC configuration. However, for\n`Perl::LanguageServer` it depends if you've [local::lib](https://metacpan.org/pod/local::lib) set in your system or\nnot: if you have it set manually or through some other installation/dependency management tool, like\n[PerlBrew](https://perlbrew.pl/), [Carton](https://metacpan.org/pod/Carton), [Carmel](https://metacpan.org/pod/Carmel), etc, the automatic installation should happen without any\nproblems, since the server will be placed in a local directory, that your user has access to; on the other hand,\nwithout it set, the installation is required to be manually executed as root, as described by its own [documentation](https://github.com/richterger/Perl-LanguageServer?tab=readme-ov-file#requirements).\n\n### Prerequisites\n\nFor Perl::LanguageServer you need to have `cpan` installed in your host system. The way coc-perl installs it is by\nexecuting `cpan Perl::LanguageServer` with a specific version (the latest supported version). However, you can\nmanually install it on your system or your local library path in case you're using, preventing any installation done by coc-perl.\n\nNow, for PerlNavigator, coc-perl also handles it automatically, but it requires `git` to be installed. In case you\ndecide to install it manually, since it's not present in CPAN and its initialization is entirely written in TypeScript\nrather than Perl, you need to follow what's described on [PerlNavigator\nrepository](https://github.com/bscan/PerlNavigator/tree/main#installation-for-other-editors) about installing it on\nother editors. In summary, you need to clone the repository, install the server running the `npx tsc` command from\nwithin server's folder and take note of the absolute path for the generated code, for instance\n`/home/\u003cuser\u003e/PerlNavigator/server/out/server.js`, which will be needed when configuring CoC later on.\n\n### Installing coc-perl\n\nInside (neo)vim run this command:\n```vim\n:CocInstall coc-perl\n```\nor, you can set `g:coc_global_extensions`.\n```vim\nlet g:coc_global_extensions = [\n      \\ 'coc-perl',\n\\ ]\n```\nor even install directly via any plugin manager, for example, with [vim-plug](https://github.com/junegunn/vim-plug):\n```vim\nPlug 'bmeneg/coc-perl'\n```\n\n#### Automatic language server installation\n\nWhen coc-perl is installed for the first time, you probably won't have any configuration referring to what language\nserver you want to enable, thus neither Perl::LanguageServer nor PerlNavigator will be installed. Make sure to after\ninstalling coc-perl, enable one of the servers in coc.nvim configuration file (keep reading the next sections to know\nhow perform such action) and then reopen a Perl file or, in case you're already with a Perl file opened, call\n`:CocRestart`, so the automatic installation process can take place considering the choice you made regarding the\nlanguage server.\n\n## Choosing a Language Server\n\nTo enable a language server an option must be added to the `coc-settings.json` file, which can be accessed through the\n(neo)vim command `:CocConfig`. However, before directly enabling them, it's important to understand how the\nconfiguration properties are defined for each server.\n\n### Configuration properties\n\nAs said before, coc-perl supports two different Perl language servers: _Perl::LanguageServer_ (hereafter referred as\n`pls`) and _PerlNavigator_ (hereafter referred as `navigator`). Each has its own set of options to be set on\n`:CocConfig` and coc-perl support them completely.\n\nFor those using `pls`, configuration options are set under the `perl.*` namespace, while for `navigator`, the\nnamespace `perlnavigator.*` is used.\n\n#### Deprecation/removal notice\n\nIn the coc-perl version `2.x`, there was an effort to also support coc-specific namespaces, like `perl.p::ls.*` for\n_Perl::LanguageServer_ and `perl.navigator.*` for _PerlNavigator_. However, after some time, the burden to keep both\ndefault and coc-perl specific namespace has proven not to be worth. With that, we have completely removed its support\nin version `3.x`.\n\n### Enabling one server\n\nOnly one language server can be enabled at a time. In case both are enabled, an error will be prompted on\n`:CocOpenLog` and no server action will be seen on (neo)vim's buffer.\n\nFor enabling `pls`, you can use either options (the first is preferred):\n\n```json\n{\n    \"perl.enable\": true\n}\n```\n\nAnd for `navigator`:\n\n```json\n{\n    \"perlnavigator.enable\": true,\n}\n```\n\nIf you're using a development branch of `navigator`, manually downloaded and/or installed, you'll need one additional\noption: the server absolute path.\n```json\n    \"perlnavigator.serverPath\": \"/home/\u003cuser\u003e/PerlNavigator/server/out/server.js\"\n```\n\n### Other options\n\nAs user, you can change and pass different options to each language server, however, the options are tied to the\nserver version being used. Because of that, make sure to always run the newest version of the server alongside the\ncoc-perl extension. A brief example of using different options are as follows:\n```json\n{\n    \"perl.enable\": true,\n    \"perl.logLevel\": 2,\n    \"perl.logFile\": \"/home/\u003cuser\u003e/coc-perl.log\",\n\n    \"perlnavigator.enable\": false,\n    \"perlnavigator.serverPath\": \"/home/\u003cuser\u003e/PerlNavigator/server/out/server.js\"\n}\n```\n\nYou can have options for both servers in the configuration file, but only one server can be enabled at a time, meaning\nthat options for the disabled server won't reach the enabled server.\n\nFor a detailed list of all options, please visit\n[PerlNavigator](https://github.com/bscan/PerlNavigator/tree/main#perl-paths) and\n[Perl-LanguageServer](https://github.com/richterger/Perl-LanguageServer#extension-settings) repositories.\n\n## Differences from VSCode extension\n\nUnfortunatelly not all features supported in the original VSCode extension are available in coc-perl due to the\ndifferences between VSCode extension core code and `coc.nvim`. Although Language Server Protocol is fully compatible,\nthe [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) is missing from\n`coc.nvim`, cause the features related to lauching and debugging Perl code non-existent on (neo)vim through coc-perl.\n\nFor those navigating the extension code will notice some \"DAP-related\" variables are defined and \"used\", but in\nreality they have no operation at all, serving just as placeholders to allow transparent use of VSCode extension\nconfiguration file. Working is being done in different fronts to get DAP support to neovim as soon as possible, but a\nthird plugin might be required (besides `coc.nvim` and coc-perl).\n\nWhenever a decent and full-featured support lands through another project, instructions will be presented in this\nREADME file.\n\n## Troubleshooting\n\nBefore filling an issue, it's important to gather some information to use as entry point.\nMake sure to copy the contents from `:CocConfig`, `:CocOpenLog` and `:CocCommand workspace.showOutput`.\n\n`:CocConfig` is important to understand how you're trying to use the extension and the server. `:CocOpenLog` shows the\nlog for `coc.nvim` itself, when trying to initialize the extension and the server. Finally, when issuing `:CocCommand\nworkspace.showOutput` a selections window will pop up to choose the server (`Perl::LanguageServer` or `PerlNavigator`)\nand, once you have done that, any errors from the server will be shown in a new buffer. Only then, an issue can be\nfilled with all this information presented inline.\n\nBut remember, server's code are far more complicated than this client extension, meaning that most of the bugs will be\nrelated to the server. Make sure to search for the symptoms you're experiencing in server's repository either.\n\n## Maintainers\n\n[bmeneg](https://github.com/bmeneg) - Maintainer  \n[ulwlu](https://github.com/ulwlu) - Project creator and former maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperl-ide%2Fcoc-perl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperl-ide%2Fcoc-perl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperl-ide%2Fcoc-perl/lists"}