PPI Signatures Trial Release - Feedback Requested
SYNOPSIS
I have just released a trial version of PPI that includes the first shot at support for Perl signatures. After installing it, you can access this feature in the following ways.
For users of perlcritic and other PPI consumers:
- include
use 5.035;
or higher in your code - include
use feature 'signatures';
in your code - include a known signatures-enable strictures modules from CPAN in your code, e.g. Mojolicious::Lite, Modern::Perl
- if you enable signatures via a custom strictures module, declare it via %ENV:
PPI_CUSTOM_FEATURE_INCLUDES='{MyStrict=>{signatures=>1}}' perlcritic Work.pm
For consumers of PPI, in addition to the above:
- enable recognition of custom parsing feature modules via:
PPI::Document->new( custom_feature_includes => ... )
- enable the custom parsing feature for the entire document via:
PPI::Document->new( feature_mods => ... )
- enable complex parsing of calls to module includes via:
PPI::Document->new( custom_feature_include_cb => ... )
- query enabled features via
::Element->presumed_features
In a similar way as signatures, the core try feature is also recognized.
TODO
There is still a lot to do, since this is a first shot. Questions are open:
For users of perlcritic and other PPI consumers:
- Which signature features do you need PPI to recognize that currently are not?
- Which try features do you need PPI to recognize that currently are not?
- Which other perl parsing features would you like to see supported?
- Which common CPAN modules should be recognized as enabling specific features?
For consumers of PPI, in addition to the above:
- What changes, if any, would you like to the custom feature includes facility?
- What tree of elements would you like to see for signature?
- What tree of elements would you like to see for try?
- What tree of elements would you like to see for other parsing features?
BACKGROUND
Doing this took a while, since Perl is fundamentally impossible to statically parse accurately due to various features like prototypes and nested, implicit or indirect imports, and PPI tries to only parse it as a document.
The implementation currently does however, to its best ability, use the tree as emitted to track lexically enabled parsing features.
However the more tricky part was the fact that typically PPI only gets a single file as input and no further arguments that modify what is outputted. This release breaks with that by allowing consumers of PPI to insert a variety of arguments that either affect the document as a whole, or modify how modules includes affect the rest of the document.
If this works out well, PPI might make use of that for future features, which is becoming increasingly important with Paul Evans (LeoNerd)'s work on perl keywords, features like try, and in conjunction with Ovid, the work on Corinna, Object::Pad, the class keyword and others coming in the future.
If you desire to read more of the considerations on this overall topic, please read this github issue, as well as the ones linked in it that preceded it.
TESTING
In addition to the features added to PPI directly, with a lot of help by Olaf Alders, we now also have a reverse dependency testing script that runs as a Github action and runs the test suites not only for modules that use PPI directly, but also for as many downstream modules that end up having PPI in their dependency chain.
Due to the nature of the beast, i had to add a lot of modules to the exclusion list. If you see your modules, or modules you care about, on that list and would like to get them removed, do feel free to contact me.
Since my main goal was getting this out in a reasonable time, i did not investigate many of the failing modules at all. Heck, some of them might even be pointing out actual problems right now.
FEEDBACK
Please leave thoughts, feedback and comments optimally on the github repository, but comments here, in email to me, or other venues in which i am able to respond are appreciated the same.
I would post this to perl sub-reddit as well, but three years ago i spoke out aggressively against allowing r/perl to be used to publicize a post by the TPF that effectively spread false antisemitism accusations, and subsequently the moderators decided to ban me.
The TPF has since retracted the post and others, but the r/perl moderation team remains unmoved, so i cannot post there.
My newest module Perl::Version::Bumper makes heavy use of PPI to help "bump" the version in
use VERSION
in any Perl code.As part of the module, I wrote a script that builds a table of all features. It's not included in the distribution yet, but you can find it here: build_feature_data.pl.
Thanks BooK, that actually seems super useful and like a nice time-saver. I see you hard-coded the features. Maybe those could be parsed from feature.pm? I think i would also like, for completeness' sake, to recognize perl pre-release versions for including relevant features. :)
Great info. I wouldn't comment, but you wrote ...
> [r/perl] moderators decided to ban me
I feel your pain, am also perma-banned due to mod overreach. FWIW, new incantation of the CAT doesn't even bother to issue transparency reports, ask me how I know xD going back to the summer'24. I wonder how many others have been cancelled similarly without a peep.