PPI - Parse and manipulate Perl code non-destructively, without using perl itself
This is an in-development package for parsing, manipulating and saving perl code, without using the perl interpreter, the B modules, or any other hacks that use perl's inbuilt grammar.
Please note that is project it intended as a mechanism for working with perl content, NOT to actually compile and run working perl applications. Thus, it provides only an approximation of the detail and flexibility available to the real perl parser, if a quite close approximation.
It has been shown many times that it is impossible to FULLY "parse" Perl code without also executing it. We do not intend to fully parse it, just get enough details to analyse it, alter it, and save it back without losing details like whitespace, comments and other stuff lost when using the B:: modules.
The Tokenizer can be considered complete, but with some remaining bugs that will be fixed over time. This should get gradually more accurate as special cases are found and handled, and more cruft is added. :)
The basic framework of the lexer has been completely replaced. The new lexer should be sufficient, but the lex logic is far from complete, and so the parse tree may look kind of odd, but works for very basic statements.
The classes and methods are roughly completed for the basic parse tree manipulation, but more advanced filters and such are yet to be written. Overall, the lexer is considered about three quarters complete.
The syntax highlighter is virtually unchanged, except that instead of working from an ( old style ) PPI::Document object, it pulls directly from a Tokenizer. This is temporary, and you should expect the entire PPI::Format tree to be overhauled and largely replaced once the lexer is completed.
Given their current state, I have removed the entire PPI::Transform and PPI::Analysis trees from the upload. They are totally out of date, and will be replaced as the Lexer gets closer.
One rewritten module, PPI::Analysis::Compare, is largely done and is currently in CPAN on it's own, as it relies on additional modules not needed by the core.
I have started on the very beginning of the manual, which can be found at PPI::Manual. It's raw, incomplete, and subject to change.
This section provides a quick overview of all the classes in PPI, and their general layout and inheritance. We start with the main data classes, and then move on to the functional classes
PPI::Base PPI::Element PPI::Node PPI::Document PPI::Statement PPI::Statement::Package PPI::Statement::Scheduled PPI::Statement::Expression PPI::Statement::Include PPI::Statement::Sub PPI::Statement::Variable PPI::Statement::Compound PPI::Statement::Break PPI::Statement::Null PPI::Structure PPI::Token
Minor bug fixes and improvements are expected to be done as needed over time.
- Finish the non-if compound statement lexing.
- Add lex and statement support for labels.
- Add support for statements that start with a block.
Also, a rewritten filter/transform framework needs to be created on top of the basic lexer, to provide for the ability to add higher lever logic and capabilities.
PPI::Format needs to be created properly, based on lex output rather than the raw token stream. PPI::Analysis packages will need to be rewritten... but they are likely to be largely third party, later. However, a base collection of search/find/filter/replace type methods probably need to be written centrally.
Somewhere in there we also need a SAX filter to generate events based on perl structures, so various more complex processing tools can be written.
Replacements or equivalents are needed for current methods that do POD extraction... some form of auto-doc can probably be written on top of that.
Both user manuals and API documentation needs to get written.
None. Don't use this for anything you don't want to have to rewrite. As this is changing, you probably need to be in contact with the author if you want to be using this.
Adam Kennedy (Maintainer) cpan@ali.as http//ali.as/
Copyright (c) 2002-2004 Adam Kennedy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
To install PPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PPI
CPAN shell
perl -MCPAN -e shell install PPI
For more information on module installation, please visit the detailed CPAN module installation guide.