NAME

PPI::Document - A single cohesive 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 additions for loading/saving, and working with the line/column locations of tokens 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

This method should be generally acted upon using the PPI::Node API, of which it is a subclass.

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, if it were to be printed to a file. This position is primarily useful for debugging type activities.

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 objects becoming children of another Node.

SUPPORT

See PPI

AUTHOR

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

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.