++ed by:

26 PAUSE users
19 non-PAUSE users.

Adam Kennedy
and 1 contributors


PPI::Document - Object representation of a Perl document


  isa PPI::Node
      isa PPI::Element


  # 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


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-like behavior this is that a PPI::Document object can NEVER have a parent node, and is always the root node in a tree.


Most of the things you are likely to want to do with a Document are probably going to involve the methods from 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.

tab_width [ $width ]

In order to handle support for location correctly, Documents need to understand the concept of tabs and tab width. The tab_width method is used to get and set the size of the tab width.

At the present time, PPI only support "naive" (width 1) tabs, but we do plan on supporting artibtrary, default and auto-sensing tab widths.

Returns the tab width as an integer, or dies if you attempt to set the tab width.


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.


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.


The normalized method is used to generate a "Layer 1" PPI::Document::Normalized object for the current Document.

A "normalized" Perl Document is an arbitrary structure that removes any irrelevant parts of the document and refactors out variations in style, to attempt to approach something that is closer to the "true meaning" of the Document.

See PPI::Normal for more information on document normalization and the tasks for which it is useful.

Returns a PPI::Document::Normalized object, or undef on error.


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


See the support section in the main module


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


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