NAME

PPI::Document - A single Perl document

INHERITANCE

  PPI::Document
  isa PPI::Node
      isa PPI::Element
          isa PPI::Base

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 its ::Node behavior 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.

new $source

The new constructor is slightly different for PPI::Document that for the base PPI::Node.

Although it behaves the same when called with no arguments, if you pass it a defined string as the only argument, as a convenience the string will be parsed, and the Document object returned will be for the source code in the string.

Returns a PPI::Document object, or undef if parsing fails.

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.

serialize

Unlike the content method, which shows only the immediate content within an element, Document objects also have to be able to be written out to a file again.

When doing this we need to take into account some additional factors.

Primarily, we need to handle here-docs correctly, so that are written to the file in the expected place.

The serialize method generates the actual file content for a given Document object. The resulting string can be written straight to a file.

Returns the serialized document as a string.

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.

flush_locations

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

TO DO

- Write proper unit and regression tests

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

- May be worth adding a PPI::Document::Normalized sub-class to formally recognise the normalisation work going on in Perl::Compare and the like.

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