NAME
PPI::Document - Object representation of a Perl document
INHERITANCE
PPI::Document
isa PPI::Node
isa PPI::ElementSYNOPSIS
use PPI;
# Load a document from a file
my $Document = PPI::Document->new('My/Module.pm');
# Strip out comments
$Document->prune('PPI::Token::Comment');
# Find all the named subroutines
my $sub_nodes = $Document->find(
sub { $_[1]->isa('PPI::Statement::Sub') and $_[1]->name }
);
my @sub_names = map { $_->name } @$sub_nodes;
# 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.
Storable Support
PPI::Document implements the necessary STORABLE_freeze and STORABLE_thaw hooks to provide native support for Storable, if you have it installed.
However if you want to clone a Document, you are highly recommended to use the $Document->clone method rather than Storable's dclone function (although dclone should still work).
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
# Simple construction
$doc = PPI::Document->new( $filename );
$doc = PPI::Document->new( \$source );
# With the readonly attribute set
$doc = PPI::Document->new( $filename,
readonly => 1,
);The new constructor takes as argument a variety of different sources of Perl code, and creates 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.
In all cases, the document is considered to be "anonymous" and not tied back to where it was created from. Specifically, if you create a PPI::Document from a filename, the document will not remember where it was created from.
Returns a PPI::Document object, or undef if parsing fails. PPI::Exception objects can also be thrown if there are parsing problems.
The constructor also takes attribute flags.
readonly
Setting readonly to true will allow various systems to provide additional optimisations and caching. Note that because readonly is an optimisation flag, it is off by default and you will need to explicitly enable it.
feature_mods
Setting feature_mods with a hashref allows defining perl parsing features to be enabled for the whole document. (e.g. when the code is assumed to be run as a oneliner)
custom_feature_includes
custom_feature_includes =>
{ strEct => { signatures => "Syntax::Keyword::Try" } }Setting custom_feature_includes with a hashref allows defining include names which act like pragmas that enable parsing features within their scope.
This is mostly useful when your work project has its own boilerplate module.
It can also be provided in the environment variable PPI_CUSTOM_FEATURE_INCLUDES, like so:
PPI_CUSTOM_FEATURE_INCLUDES='{strEct=>{signatures=>"perl"}}' \
perlcritic lib/OurModule.pmcustom_feature_include_cb
custom_feature_include_cb => sub {
my ($statement) = @_;
return $statement->module eq "strEct" ? { signatures => "perl" } : ();
},Setting custom_feature_include_cb with a code reference causes all inspections on includes to call that sub before doing any other inspections. The sub can decide to either return a hashref of features to be enabled or disabled, which will be used for the scope the include was called in, or undef to continue with the default inspections. The argument to the sub will be the PPI::Statement::Include object.
This can be useful when your work project has a complex boilerplate module.
set_cache $cache
As of PPI 1.100, PPI::Document supports parser caching.
The default cache class PPI::Cache provides a Storable-based caching or the parsed document based on the MD5 hash of the document as a string.
The static set_cache method is used to set the cache object for PPI::Document to use when loading documents. It takes as argument a PPI::Cache object (or something that isa the same).
If passed undef, this method will stop using the current cache, if any.
For more information on caching, see PPI::Cache.
Returns true on success, or undef if not passed a valid param.
get_cache
If a document cache is currently set, the get_cache method will return it.
Returns a PPI::Cache object, or undef if there is no cache currently set for PPI::Document.
filename
The filename accessor returns the name of the file in which the document is stored.
readonly
The readonly attribute indicates if the document is intended to be read-only, and will never be modified. This is an advisory flag, that writers of PPI-related systems may or may not use to enable optimisations and caches for your document.
Returns true if the document is read-only or false if not.
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 supports "naive" (width 1) tabs, but we do plan on supporting arbitrary, default and auto-sensing tab widths later.
Returns the tab width as an integer, or dies if you attempt to set the tab width.
feature_mods { feature_name => $provider }
custom_feature_includes { module_name => { feature_name => $provider } }
custom_feature_include_cb sub { ... }
save
$document->save( $file )The save method serializes the PPI::Document object and saves the resulting Perl document to a file. Returns undef on failure to open or write to the file.
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.
hex_id
The hex_id method generates an unique identifier for the Perl document.
This identifier is basically just the serialized document, with Unix-specific newlines, passed through MD5 to produce a hexadecimal string.
This identifier is used by a variety of systems (such as PPI::Cache and Perl::Metrics) as a unique key against which to store or cache information about a document (or indeed, to cache the document itself).
Returns a 32 character hexadecimal 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 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.
complete
The complete method is used to determine if a document is cleanly structured, all braces are closed, the final statement is fully terminated and all heredocs are fully entered.
Returns true if the document is complete or false if not.
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 <adamk@cpan.org>
SEE ALSO
PPI, https://web.archive.org/web/20230911221703/http://ali.as/
COPYRIGHT
Copyright 2001 - 2011 Adam Kennedy.
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.