NAME

PPI::Document - A single Perl document

INHERITANCE

  PPI::Base
  \--> PPI::Element
       \--> PPI::Node
            \--> PPI::Document

SYNOPSIS

  # Load a document from a file
  use PPI::Document;
  my $Document = PPI::Document->load('My/Module.pm');
  
  # Strip out comments
  $Document->prune( 'PPI::Token::Comment' );
  
  # Find all the named subroutines
  my @subs = $Document->find( 
        sub { isa($_[1], 'PPI::Statement::Sub') and $_[1]->name }
        );
  
  # Save the file
  $Document->save('My/Module.pm.stripped');

DESCRIPTION

The PPI::Document class represents a single Perl "document". A Document object acts as a normal PPI::Node, with some additional convenience methods for loading and saving, and working with the line/column locations of Elements within a file.

The exemption to it's ::Node behaviour this is that a PPI::Document object can NEVER have a parent node, and is always the root node in a tree.

METHODS

Most of the things you are likely to want to do with a Document are probably going to involve the methods of the PPI::Node class, of which this is a subclass.

The methods listed here are the remaining few methods that are truly Document-specific.

load $file

The load constructor loads a Perl document from a file, parses it, and returns a new PPI::Document object. Returns undef on error.

save $file

The save method serializes the PPI::Document object and saves the resulting Perl document to a file. Returns undef on error.

index_locations

Within a document, all PPI::Element objects can be considered to have a "location", a line/column position within the document when considered as a file. This position is primarily useful for debugging type activities.

The method for finding the position of a single Element is a bit laborious, and very slow if you need to do it a lot. So the index_locations method will index and save the locations of every Element within the Document in advance, making future calls to <PPI::Element::location> virtually free.

Please note that this is index should always be cleared using flush_locations once you are finished with the locations. If content is added to or removed from the file, these indexed locations will be wrong.

When no longer needed, the flush_locations method clears all location data from the tokens.

TO DO

May need to overload some methods to forcefully prevent Document objects becoming children of another Node.

SUPPORT

See the support section in the main PPI Manual

AUTHOR

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

Thank you to Phase N (http://phase-n.com/) for permitting the open sourcing and release of this distribution.

COPYRIGHT

Copyright (c) 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.

cpanm PPI

perl -MCPAN -e shell
install PPI