1PPI::Document(3) User Contributed Perl Documentation PPI::Document(3)
2
6 PPI::Document - Object representation of a Perl document
7
9 PPI::Document
10 isa PPI::Node
11 isa PPI::Element
12
14 use PPI;
15 # Load a document from a file
17 my $Document = PPI::Document->new('My/Module.pm');
18 # Strip out comments
20 $Document->prune('PPI::Token::Comment');
21 # Find all the named subroutines
23 my $sub_nodes = $Document->find(
24 sub { $_[1]->isa('PPI::Statement::Sub') and $_[1]->name }
25 );
26 my @sub_names = map { $_->name } @$sub_nodes;
27 # Save the file
29 $Document->save('My/Module.pm.stripped');
30
32 The "PPI::Document" class represents a single Perl "document". A
33 "PPI::Document" object acts as a root PPI::Node, with some additional
34 methods for loading and saving, and working with the line/column
35 locations of Elements within a file.
36 The exemption to its PPI::Node-like behavior this is that a
38 "PPI::Document" object can NEVER have a parent node, and is always the
39 root node in a tree.
40 Storable Support
42 "PPI::Document" implements the necessary "STORABLE_freeze" and
43 "STORABLE_thaw" hooks to provide native support for Storable, if you
44 have it installed.
45 However if you want to clone a Document, you are highly recommended to
47 use the "$Document->clone" method rather than Storable's "dclone"
48 function (although "dclone" should still work).
49
51 Most of the things you are likely to want to do with a Document are
52 probably going to involve the methods from PPI::Node class, of which
53 this is a subclass.
54 The methods listed here are the remaining few methods that are truly
56 Document-specific.
57 new
59 # Simple construction
60 $doc = PPI::Document->new( $filename );
61 $doc = PPI::Document->new( \$source );
62 # With the readonly attribute set
64 $doc = PPI::Document->new( $filename,
65 readonly => 1,
66 );
67 The "new" constructor takes as argument a variety of different sources
69 of Perl code, and creates a single cohesive Perl "PPI::Document" for
70 it.
71 If passed a file name as a normal string, it will attempt to load the
73 document from the file.
74 If passed a reference to a "SCALAR", this is taken to be source code
76 and parsed directly to create the document.
77 If passed zero arguments, a "blank" document will be created that
79 contains no content at all.
80 In all cases, the document is considered to be "anonymous" and not tied
82 back to where it was created from. Specifically, if you create a
83 PPI::Document from a filename, the document will not remember where it
84 was created from.
85 The constructor also takes attribute flags.
87 At this time, the only available attribute is the "readonly" flag.
89 Setting "readonly" to true will allow various systems to provide
91 additional optimisations and caching. Note that because "readonly" is
92 an optimisation flag, it is off by default and you will need to
93 explicitly enable it.
94 Returns a "PPI::Document" object, or "undef" if parsing fails.
96 PPI::Exception objects can also be thrown if there are parsing
97 problems.
98 set_cache $cache
100 As of PPI 1.100, "PPI::Document" supports parser caching.
101 The default cache class PPI::Cache provides a Storable-based caching or
103 the parsed document based on the MD5 hash of the document as a string.
104 The static "set_cache" method is used to set the cache object for
106 "PPI::Document" to use when loading documents. It takes as argument a
107 PPI::Cache object (or something that "isa" the same).
108 If passed "undef", this method will stop using the current cache, if
110 any.
111 For more information on caching, see PPI::Cache.
113 Returns true on success, or "undef" if not passed a valid param.
115 get_cache
117 If a document cache is currently set, the "get_cache" method will
118 return it.
119 Returns a PPI::Cache object, or "undef" if there is no cache currently
121 set for "PPI::Document".
122 filename
124 The "filename" accessor returns the name of the file in which the
125 document is stored.
126 readonly
128 The "readonly" attribute indicates if the document is intended to be
129 read-only, and will never be modified. This is an advisory flag, that
130 writers of PPI-related systems may or may not use to enable
131 optimisations and caches for your document.
132 Returns true if the document is read-only or false if not.
134 tab_width [ $width ]
136 In order to handle support for "location" correctly, "Documents" need
137 to understand the concept of tabs and tab width. The "tab_width" method
138 is used to get and set the size of the tab width.
139 At the present time, PPI only supports "naive" (width 1) tabs, but we
141 do plan on supporting arbitrary, default and auto-sensing tab widths
142 later.
143 Returns the tab width as an integer, or "die"s if you attempt to set
145 the tab width.
146 save
148 $document->save( $file )
149 The "save" method serializes the "PPI::Document" object and saves the
151 resulting Perl document to a file. Returns "undef" on failure to open
152 or write to the file.
153 serialize
155 Unlike the "content" method, which shows only the immediate content
156 within an element, Document objects also have to be able to be written
157 out to a file again.
158 When doing this we need to take into account some additional factors.
160 Primarily, we need to handle here-docs correctly, so that are written
162 to the file in the expected place.
163 The "serialize" method generates the actual file content for a given
165 Document object. The resulting string can be written straight to a
166 file.
167 Returns the serialized document as a string.
169 hex_id
171 The "hex_id" method generates an unique identifier for the Perl
172 document.
173 This identifier is basically just the serialized document, with Unix-
175 specific newlines, passed through MD5 to produce a hexadecimal string.
176 This identifier is used by a variety of systems (such as PPI::Cache and
178 Perl::Metrics) as a unique key against which to store or cache
179 information about a document (or indeed, to cache the document itself).
180 Returns a 32 character hexadecimal string.
182 index_locations
184 Within a document, all PPI::Element objects can be considered to have a
185 "location", a line/column position within the document when considered
186 as a file. This position is primarily useful for debugging type
187 activities.
188 The method for finding the position of a single Element is a bit
190 laborious, and very slow if you need to do it a lot. So the
191 "index_locations" method will index and save the locations of every
192 Element within the Document in advance, making future calls to
193 <PPI::Element::location> virtually free.
194 Please note that this index should always be cleared using
196 "flush_locations" once you are finished with the locations. If content
197 is added to or removed from the file, these indexed locations will be
198 wrong.
199 flush_locations
201 When no longer needed, the "flush_locations" method clears all location
202 data from the tokens.
203 normalized
205 The "normalized" method is used to generate a "Layer 1"
206 PPI::Document::Normalized object for the current Document.
207 A "normalized" Perl Document is an arbitrary structure that removes any
209 irrelevant parts of the document and refactors out variations in style,
210 to attempt to approach something that is closer to the "true meaning"
211 of the Document.
212 See PPI::Normal for more information on document normalization and the
214 tasks for which it is useful.
215 Returns a PPI::Document::Normalized object, or "undef" on error.
217
219 The "complete" method is used to determine if a document is cleanly
220 structured, all braces are closed, the final statement is fully
221 terminated and all heredocs are fully entered.
222 Returns true if the document is complete or false if not.
224 errstr
226 For error that occur when loading and saving documents, you can use
227 "errstr", as either a static or object method, to access the error
228 message.
229 If a Document loads or saves without error, "errstr" will return false.
231
233 - May need to overload some methods to forcefully prevent Document
234 objects becoming children of another Node.
235
237 See the support section in the main module.
238
240 Adam Kennedy <adamk@cpan.org>
241
243 PPI, <http://ali.as/>
244
246 Copyright 2001 - 2011 Adam Kennedy.
247 This program is free software; you can redistribute it and/or modify it
249 under the same terms as Perl itself.
250 The full text of the license can be found in the LICENSE file included
252 with this module.
253perl v5.36.0 2023-01-20 PPI::Document(3)