1PPI::Document(3)      User Contributed Perl Documentation     PPI::Document(3)
2
3
4

NAME

6       PPI::Document - Object representation of a Perl document
7

INHERITANCE

9         PPI::Document
10         isa PPI::Node
11             isa PPI::Element
12

SYNOPSIS

14         use PPI;
15
16         # Load a document from a file
17         my $Document = PPI::Document->new('My/Module.pm');
18
19         # Strip out comments
20         $Document->prune('PPI::Token::Comment');
21
22         # 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
28         # Save the file
29         $Document->save('My/Module.pm.stripped');
30

DESCRIPTION

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
37       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
41   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
46       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

METHODS

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
55       The methods listed here are the remaining few methods that are truly
56       Document-specific.
57
58   new
59         # Simple construction
60         $doc = PPI::Document->new( $filename );
61         $doc = PPI::Document->new( \$source  );
62
63         # With the readonly attribute set
64         $doc = PPI::Document->new( $filename,
65                 readonly => 1,
66         );
67
68       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
72       If passed a file name as a normal string, it will attempt to load the
73       document from the file.
74
75       If passed a reference to a "SCALAR", this is taken to be source code
76       and parsed directly to create the document.
77
78       If passed zero arguments, a "blank" document will be created that
79       contains no content at all.
80
81       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
86       The constructor also takes attribute flags.
87
88       At this time, the only available attribute is the "readonly" flag.
89
90       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
95       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
99   set_cache $cache
100       As of PPI 1.100, "PPI::Document" supports parser caching.
101
102       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
105       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
109       If passed "undef", this method will stop using the current cache, if
110       any.
111
112       For more information on caching, see PPI::Cache.
113
114       Returns true on success, or "undef" if not passed a valid param.
115
116   get_cache
117       If a document cache is currently set, the "get_cache" method will
118       return it.
119
120       Returns a PPI::Cache object, or "undef" if there is no cache currently
121       set for "PPI::Document".
122
123   filename
124       The "filename" accessor returns the name of the file in which the
125       document is stored.
126
127   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
133       Returns true if the document is read-only or false if not.
134
135   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
140       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
144       Returns the tab width as an integer, or "die"s if you attempt to set
145       the tab width.
146
147   save
148         $document->save( $file )
149
150       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
154   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
159       When doing this we need to take into account some additional factors.
160
161       Primarily, we need to handle here-docs correctly, so that are written
162       to the file in the expected place.
163
164       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
168       Returns the serialized document as a string.
169
170   hex_id
171       The "hex_id" method generates an unique identifier for the Perl
172       document.
173
174       This identifier is basically just the serialized document, with Unix-
175       specific newlines, passed through MD5 to produce a hexadecimal string.
176
177       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
181       Returns a 32 character hexadecimal string.
182
183   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
189       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
195       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
200   flush_locations
201       When no longer needed, the "flush_locations" method clears all location
202       data from the tokens.
203
204   normalized
205       The "normalized" method is used to generate a "Layer 1"
206       PPI::Document::Normalized object for the current Document.
207
208       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
213       See PPI::Normal for more information on document normalization and the
214       tasks for which it is useful.
215
216       Returns a PPI::Document::Normalized object, or "undef" on error.
217

complete

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
223       Returns true if the document is complete or false if not.
224
225   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
230       If a Document loads or saves without error, "errstr" will return false.
231

TO DO

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

SUPPORT

237       See the support section in the main module.
238

AUTHOR

240       Adam Kennedy <adamk@cpan.org>
241

SEE ALSO

243       PPI, <http://ali.as/>
244
246       Copyright 2001 - 2011 Adam Kennedy.
247
248       This program is free software; you can redistribute it and/or modify it
249       under the same terms as Perl itself.
250
251       The full text of the license can be found in the LICENSE file included
252       with this module.
253
254
255
256perl v5.36.0                      2023-01-20                  PPI::Document(3)
Impressum