/ 
PPI-0.826
River stage four • 197 direct dependents • 1592 total dependents
/ PPI

NAME

PPI - Parse and manipulate Perl code non-destructively, without using perl itself

DESCRIPTION

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.

STATUS

Tokenizer

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. :)

Lexer

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.

Syntax Highlighting

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.

Other Functionality

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.

Documentation

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.

STRUCTURE

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

TO DO

Tokenizer

Minor bug fixes and improvements are expected to be done as needed over time.

Lexer

- 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.

Other Stuff

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.

Documentation

Both user manuals and API documentation needs to get written.

SUPPORT

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.

AUTHOR

Adam Kennedy (Maintainer), http://ali.as/, cpan@ali.as

COPYRIGHT

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.