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)
        cpan@ali.as
        http//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.