The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PPI-0.993
River stage four • 195 direct dependents • 1581 total dependents
58 ++
/ PPI::Document

NAME

PPI::Document - Object representation of a Perl document

INHERITANCE

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

SYNOPSIS

  use PPI;
  
  # Load a document from a file
  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 PPI::Document object acts as a root PPI::Node, with some additional methods for loading and saving, and working with the line/column locations of Elements within a file.

The exemption to its PPI::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.

METHODS

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 $file, \$source

The new constructor takes as argument a variety of different sources of Perl code, and attempt to create a single cohesive Perl PPI::Document for it.

If passed a file name as a normal string, it will attempt to load the document from the file.

If passed a reference to a SCALAR, this is taken to be source code and parsed directly to create the document.

If passed zero arguments, a "blank" document will be created that contains no content at all.

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

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.

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.

normalized

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.

errstr

For error that occur when loading and saving documents, you can use errstr, as either a static or object method, to access the error message.

If a Document loads or saves without error, errstr will return false.

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 module

AUTHOR

Adam Kennedy, http://ali.as/, cpan@ali.as

COPYRIGHT

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.