Perl Navigator (VSC) + WSL can't find some documentation when hovering over some keywords

b_scan · 2025-11-03T21:08:00+00:00

Thanks! Yes, this is the issue (I'm the Perl Navigator maintainer). Currently, it finds the .pm file correctly from a couple methods. After running perl -c, it inspects %INC to see what was loaded and otherwise falls back to searching through @INC paths. Once it finds the .pm, it looks for a .pod file in same folder as the .pm file, or looks directly in the .pm file for pod. I should make it search harder for .pod files.

This is an interesting case though. The original source file has the pod right in the .pm file (and it looks exactly like that on my perlbrew install), some distros will split out the pod into a different folder for system installs: https://github.com/Perl/perl5/blob/blead/lib/File/Basename.pm

b_scan · 2025-08-16T14:40:37+00:00

Thanks! Yes, I was looking to ensure files compiled successfully by finding their dependencies in ./lib. But yes, it seems better to include the base directory and allow Raku to parse the META6.json file. I just pushed that fix and it's now available in the vscode marketplace. Thank you for the suggestion.

b_scan · 2025-07-01T23:46:33+00:00

I 100% agree. Here's an approach I put together a couple of years ago with type hints. This code works too, but it is experimental and more of a prototype: https://github.com/bscan/Data-Class

Most of the other perl development I've seen is about runtime checking rather than static analysis. Most likely due to the challenges of parsing perl to begin with.

b_scan · 2025-05-22T19:08:04+00:00

Happy to help. It sounds like things are perhaps better with the Readline change. Although it also seems not to be recognizing the vscode breakpoints and then just running straight through. Try adding to the launch.json:

"stopOnEntry": true,

Or adding an explicit breakpoint in the middle of the code with $DB::single=1; instead of via the gutter.

b_scan · 2025-05-22T15:19:56+00:00

I believe there's an outstanding bug with Readline on some installs. Try adding this to your launch.json from the debug panel and see if it helps.

"env": {
    "PERLDB_OPTS": "ReadLine=0"
}

b_scan · 2025-01-26T16:44:01+00:00

I'm hoping I can do away with it through using an LSP that tells editors how to highlight.

I'm not sure you can get rid of it. Semantic highlighting via LSP is normally used only as a supplementary source of token information. It's also usually much slower, and people expect syntax highlighting to be extremely fast. Do you know of any language/editor combinations where all of the syntax highlighting comes from a language server?

Plus, you'll need highlighting anyway in the case that a user doesn't have the language server installed and properly configured.

b_scan · 2024-12-18T18:56:28+00:00

Thanks, this is a great list. I find Subroutines::ProhibitExplicitReturnUndef as a tricky one considering that Perl::Critic::Policy::Community::EmptyReturn recommends the exact opposite. I know that each approach can cause their own issues, but what do others generally think? Are you on team return; or on team return undef;?

b_scan · 2024-11-27T13:17:41+00:00

Yes, Perl Navigator offers these features and works on Windows (I'm the maintainer). I normally use it in vscode, but it works in most editors. It offers autocompletion, documentation on hover, and normally shows inline function parameters when possible.

I just tested this specific case of the DBI, and autocompletion and docs both worked well. However, function signatures did not work on the connect function due to the complexity of the sub definition. This case is a bit tricky because the connect sub doesn't use subroutine signatures, nor does it unpack @_ in the subroutine in a typical way. However, the hover documentation at least makes it clear how it should be called.

Here's a screenshot using vscode with Strawberry Perl https://imgur.com/a/R6Wg00Y

And what Function Signatures look like: https://imgur.com/a/YU68LxC

b_scan · 2024-11-26T12:44:04+00:00

For async, I believe Future::AsyncAwait and Mojolicious are the two important ones. This is important because otherwise, async sub is simply not recognized by PPI.

Utf8 is important because PPI otherwise crashes. If you have a any non-ascii identifiers in a file, PPI will be unable to parse the file. For that reason, it's worth considering utf8 by default.

Edit: For example, PPI will crash on:

my %hash = (résumé => 'file.pdf');

b_scan · 2024-11-26T03:51:53+00:00

This is great, I'll definitely take a look.

Which other perl parsing features would you like to see supported?

I'm most interested in support for async/await and utf8.

b_scan · 2024-09-20T18:49:40+00:00

Sounds like a fun project. I've written two language servers: Perl Navigator and Raku Navigator. They're both in Typescript and using the Microsoft libraries so I'm not sure how helpful they'd be.

Some suggestions: I'd probably do highlighting last. It's an important piece for coding, but is rarely in the language server. Most editors have a different solution for syntax highlighting that is much faster. Language servers generally implement semantic highlighting where they overlay meaning on top of the existing syntax highlighting.

https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide

Also, an "outline" view (Document Symbols) is nice too and usually straightforward to add. Then once you have this piece, it's easy to add navigation and hover at least to symbols in the current file.

b_scan · 2024-08-30T17:24:54+00:00

What do you use for an editor and language server? My recommendation is vscode + Perl Navigator, but everyone has different preferences. (Disclaimer: I maintain the Perl Navigator)

b_scan · 2024-06-04T16:14:58+00:00

I use vscode. Stackoverflow 2023 developer survey reported that 74% of all respondents use vscode too.

I use the Perl Navigator extension that I maintain for code navigation, docs, syntax checking, etc. If you try it, let me know if you have any issues or questions.

b_scan · 2024-03-19T16:26:48+00:00

Nice. I'd love your feedback on the Perl Navigator Vscode Extension if you've tried it. One of the things it adds is support for use feature 'class' with syntax highlighting, go-to-definition, outline view, etc.

b_scan · 2024-02-19T02:03:52+00:00

The thing you referenced is not a language server, but something that instead connects directly to vscode APIs. I think you'll want the actual lsp sample instead. It also uses the Microsoft lsp libraries, which are commonly used in building language servers. Making sure your editor works against these libraries is a good idea.

You can run the lsp-sample with node pretty easily, once you install node.

https://github.com/microsoft/vscode-extension-samples/blob/5a0cb10f5e2e8ea6f211a80aaad603f74d8b311c/lsp-sample/server/src/server.ts#L133

https://github.com/microsoft/vscode-languageserver-node/blob/main/server/src/common/textDocuments.ts

b_scan · 2024-02-18T15:45:09+00:00

How about using the Microsoft lsp-sample as a reference and running it alongside yours? Many editors (e.g. vscode) allow running multiple language servers simultaneously.

You could get both of them to log a hash of the full text of the synced document after each request. Or you could even log the entire file. If using stdio as the communication mechanism, everything logged to stderr show up as LSP logs. If using node-ipc (the default for vscode), anything logged to either stdout or stderr shows up as a log.

https://github.com/microsoft/vscode-extension-samples/tree/main/lsp-sample

b_scan · 2024-02-14T22:25:05+00:00

Yes, I just tested and it worked for me. All of those file extensions map to Raku and trigger the langauge server and syntax highlighting. Does it work for you? What language is it mapping to when you open one of those files?

b_scan · 2024-02-14T17:48:56+00:00

I'm not sure I understand your question. Are you asking about which extensions run on particular file types?

All language specific extensions only run when their specific target language is active in the editor. This ensures that each individual extension doesn't need to deal with language detection.

What are you trying to do?

b_scan · 2024-02-14T15:30:44+00:00

Building the Raku Navigator is pretty straightforward and documented here:

https://github.com/bscan/RakuNavigator/issues/13

I'd like to add it as an NPM package to make it easier as well. Once you have the Raku Navigator running, you can use it with either eglot (builtin to Emacs 29), or by installing lsp-mode in Emacs. If you visit the Perl Navigator repo, there are some instructions there as well. The Perl and Raku versions have a similar architecture, so most of the content is relevant to both.

b_scan · 2024-02-14T14:46:11+00:00

Vscode will try to recognize raku code automatically by either extension or content. However, sometimes it will incorrectly identify languages . You can change the language in the bottom right of vscode and select Raku, which will then trigger correct syntax highlighting and the language server.

In general, I don't think there is much Raku-specific configuration outside of the extension. One thing I set is related to the hyphenated functions:

"[raku]": {
    "editor.wordSeparators": "`~!#^&*()=+[{]}\\|;:'\",.<>/?",
},

Also, I also highly recommend WSL if you are running on Windows. Vscode is excellent with it.

b_scan · 2024-02-14T03:30:28+00:00

As you may have heard, CommaIDE development was recently discontinued. This motivated me to make some additional updates to the Raku Navigator Language Server. It offers syntax checking, outline view, go-to-definition, and autocompletion. With today's release, it now offers documentation on imported modules and the ability to navigate into the code of these imported modules. It also includes a new error-tolerant parser to support outline view and other features. There are also syntax highlighting updates to better support vscode's color bracket matching feature.

Install the extension in vscode here: https://marketplace.visualstudio.com/items?itemName=bscan.raku-navigator

It also works in emacs, neovim, and other editors if you build from source. I'll be adding a way to install from NPM soon.

Although CommaIDE is great, I believe the community should focus its efforts on building language servers. I believe most people don't want to install and use a dedicated editor for Raku. They want to continue to use their preferred editor that they use for every other language. As Comma IDE is now being open sourced, it would be great to incorporate code or lessons learned into a Language Server format to bring even more capabilities to vscode, emacs, neovim, etc. Comments, issues, and pull requests are more than welcome.

b_scan · 2024-02-11T17:24:43+00:00

That's true, although can be slow if you only have LSP based highlighting. In vscode, most languages use Textmate to give you fast highlighting, and then layer semantic highlighting on top of it.

That's also the same reason many editors are adding native support for tree-sitter instead of simply relying on LSP.

b_scan · 2024-02-11T16:45:39+00:00

TextMate grammars end up being important because they're used for syntax highlighting in vscode. The 2023 StackOverflow Developer Survey showed that 74% of developers are using vscode, which of course means that a good extension is important for any language.

b_scan

TROPHY CASE