Provide Hover Documentation For Perl's Inbuilts

[Aequitosh]

Basically what the title says.

At least in my case (Neovim 0.10.1) there's no hover documentation for inbuilts like die, warn, shift, push, etc. - basically all inbuilts, as far as I'm aware.

Would be cool if it was possible to look those docs up somehow.

Depending on how PR #142 evolves, this should be fairly straightforward to implement. Luckily, the official docs provide sources for the docs themselves -- and they just happen to be written in POD, who would've thought? ;) For example, the source for perlfunc is perlfunc.txt.

One possible solution would be to "vendor" these .txt files together with the server and parse them into PodDocuments (see PR #142) during startup, so that they don't need to be re-parsed on every textDocument/hover event.

Then, when a symbol's name isn't found in the POD of the current file, fall back to the POD docs of the inbuild Perl stuff and try to find it in there.

Having the lookup of inbuilts be a "fallback" mechanism would also be compatible with e.g. WWW::Mechanize, which provides its own die and warn subs. That way those would still be found before the inbuilt die and warn functions.

Once PR #142 is resolved, I'll happily tackle this too.

[bscan]

Sure, this feature would be great, thanks! It would also be nice to be able to autocomplete on inbuilts similar to how the current auto-completion + docs work now. For this to work, we would need to know in advance the set of inbuilts to add them to a list in advance.

I like the idea of parsing them once to avoid speed penalties. This line of code will give you the location of perlfunc.pod in perl: print Pod::Simple::Search->new->find('perlfunc'); This could be nicer than vendoring them because it'll always stay up to date, and match the specifics of the exact version of perl installed.

The Perl Navigator already runs ModHunter.pl on startup to get locations of installed modules. It could be modified to get locations of documentation as well and evolve into a generic start-up script. An additional one we would want is perlvar from print Pod::Simple::Search->new->find('perlvar');. This contains the definitions of predefined variables like $^O and $]. Being able to hover on these would be nice as their meaning is not immediately obvious from the name.

I'll take a closer look at #142 this week as well. Thanks again for your help so far on this project.

[Aequitosh]

This line of code will give you the location of perlfunc.pod in perl: print Pod::Simple::Search->new->find('perlfunc'); This could be nicer than vendoring them because it'll always stay up to date, and match the specifics of the exact version of perl installed.

Ah, this is great, actually! I like this approach a lot.

I also agree that perlvar should be included there too; there have been way too many moments where I wondered what some predefined variable meant - and context-switching to the docs always kicked me out of my flow.

I'll take a closer look at #142 this week as well. Thanks again for your help so far on this project.

That's great, thanks! Whenever you got time.