search

FractalBoy / perl-language-server

101 stars 12 forks source link

readme

Perl Language Server

PLS implements features of the Language Server Protocol for Perl 5.

It is still very much in its early stages and Pull Requests are more than welcome.

The features currently implemented are:

Installation

Install the PLS package from CPAN: https://metacpan.org/pod/PLS

Setup

VSCode

Install the fractalboy.pls extension in Visual Studio Code: https://marketplace.visualstudio.com/items?itemName=FractalBoy.pls

Neovim

This assumes Neovim 0.5.0 or greater.

Install nvim-lspconfig.

nvim-lspconfig comes with a default configuration for PLS and its name is perlpls (do not confuse this with perlls which is the default configuration for Perl::LanguageServer).

The simplest means of configuring PLS is to place the following somewhere in your Neovim config:

require'lspconfig'.perlpls.setup()

This will set you up with the defaults. It assumes that pls is in your $PATH. By default Perl Critic integration will be turned off.

A more complex configuration will look like this:

local config = {
  cmd = { '/opt/bin/pls' }, -- complete path to where PLS is located
  settings = {
    pls = {
      inc = { '/my/perl/5.34/lib', '/some/other/perl/lib' },  -- add list of dirs to @INC
      cwd = { '/my/projects' },   -- working directory for PLS
      perlcritic = { enabled = true, perlcriticrc = '/my/projects/.perlcriticrc' },  -- use perlcritic and pass a non-default location for its config
      syntax = { enabled = true, perl = '/usr/bin/perl', args = { 'arg1', 'arg2' } }, -- enable syntax checking and use a non-default perl binary
      perltidy = { perltidyrc = '/my/projects/.perltidyrc' } -- non-default location for perltidy's config
    }
  }
}
require'lspconfig'.perlpls.setup(config)

See perldoc PLS for more details about the configuration items.

The above assumes a Lua configuration. If you are using a Vimscript configuration remember to wrap everything in a Lua here-doc, e.g.:

lua <<EOF
...config...
EOF

BBEdit

BBEdit version 14.0 and higher adds support for Language Server Protocols, including PLS. Add the following JSON configuration file, adjusting paths accordingly, to the folder ~/Library/Application Support/BBEdit/Language Servers/Configuration/. Then enable the language server support for Perl following their recommendations, selecting the file you saved for the configuration.

{
  "initializationOptions": {},
  "workspaceConfigurations": {
    "*": {
      "pls": {
        "inc": [],
        "syntax": {
          "enabled": true,
          "perl": "/usr/bin/perl",
          "args": []
        },
        "perltidy": {
            "perltidyrc": "~/.perltidyrc"
        },
        "perlcritic": {
          "enabled": true,
          "perlcriticrc": "~/.perlcriticrc"
        },
        "cwd": "."
      }
    }
  }
}

Emacs lsp-mode

Several LSP client implementations for Emacs exist in the form of Emacs packages. This installation instruction covers the LSP Mode package.

Starting with version 9.0.0, LSP Mode has built-in support for PLS. Thus, after installing PLS, all you need to do is to make sure that the lsp-mode package is installed into Emacs, and gets activated when Emacs opens a Perl file. Both steps are described in the LSP Mode installation instructions.

If pls should not be in your $PATH, you will need to set the variable lsp-pls-executable in Emacs to point to the pls executable. All PLS related, configurable options are available in the customisation group lsp-pls in Emacs (M-x customize-group lsp-pls).

That's all. Now, a PLS server instance will be fired up when not already running, whenever a Perl file is opened in Emacs. For more details, or what to do next, see the extensive LSP Mode documentation.

Configuration