PPI::Document(3pm)

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   readonly
124       The "readonly" attribute indicates if the document is intended to be
125       read-only, and will never be modified. This is an advisory flag, that
126       writers of PPI-related systems may or may not use to enable
127       optimisations and caches for your document.
128
129       Returns true if the document is read-only or false if not.
130
131   tab_width [ $width ]
132       In order to handle support for "location" correctly, "Documents" need
133       to understand the concept of tabs and tab width. The "tab_width" method
134       is used to get and set the size of the tab width.
135
136       At the present time, PPI only supports "naive" (width 1) tabs, but we
137       do plan on supporting arbitrary, default and auto-sensing tab widths
138       later.
139
140       Returns the tab width as an integer, or "die"s if you attempt to set
141       the tab width.
142
143   save
144         $document->save( $file )
145
146       The "save" method serializes the "PPI::Document" object and saves the
147       resulting Perl document to a file. Returns "undef" on failure to open
148       or write to the file.
149
150   serialize
151       Unlike the "content" method, which shows only the immediate content
152       within an element, Document objects also have to be able to be written
153       out to a file again.
154
155       When doing this we need to take into account some additional factors.
156
157       Primarily, we need to handle here-docs correctly, so that are written
158       to the file in the expected place.
159
160       The "serialize" method generates the actual file content for a given
161       Document object. The resulting string can be written straight to a
162       file.
163
164       Returns the serialized document as a string.
165
166   hex_id
167       The "hex_id" method generates an unique identifier for the Perl
168       document.
169
170       This identifier is basically just the serialized document, with Unix-
171       specific newlines, passed through MD5 to produce a hexadecimal string.
172
173       This identifier is used by a variety of systems (such as PPI::Cache and
174       Perl::Metrics) as a unique key against which to store or cache
175       information about a document (or indeed, to cache the document itself).
176
177       Returns a 32 character hexadecimal string.
178
179   index_locations
180       Within a document, all PPI::Element objects can be considered to have a
181       "location", a line/column position within the document when considered
182       as a file. This position is primarily useful for debugging type
183       activities.
184
185       The method for finding the position of a single Element is a bit
186       laborious, and very slow if you need to do it a lot. So the
187       "index_locations" method will index and save the locations of every
188       Element within the Document in advance, making future calls to
189       <PPI::Element::location> virtually free.
190
191       Please note that this index should always be cleared using
192       "flush_locations" once you are finished with the locations. If content
193       is added to or removed from the file, these indexed locations will be
194       wrong.
195
196   flush_locations
197       When no longer needed, the "flush_locations" method clears all location
198       data from the tokens.
199
200   normalized
201       The "normalized" method is used to generate a "Layer 1"
202       PPI::Document::Normalized object for the current Document.
203
204       A "normalized" Perl Document is an arbitrary structure that removes any
205       irrelevant parts of the document and refactors out variations in style,
206       to attempt to approach something that is closer to the "true meaning"
207       of the Document.
208
209       See PPI::Normal for more information on document normalization and the
210       tasks for which it is useful.
211
212       Returns a PPI::Document::Normalized object, or "undef" on error.
213

complete

215       The "complete" method is used to determine if a document is cleanly
216       structured, all braces are closed, the final statement is fully
217       terminated and all heredocs are fully entered.
218
219       Returns true if the document is complete or false if not.
220
221   errstr
222       For error that occur when loading and saving documents, you can use
223       "errstr", as either a static or object method, to access the error
224       message.
225
226       If a Document loads or saves without error, "errstr" will return false.
227

TO DO

229       - May need to overload some methods to forcefully prevent Document
230       objects becoming children of another Node.
231

SUPPORT

233       See the support section in the main module.
234

AUTHOR

236       Adam Kennedy <adamk@cpan.org>
237

COPYRIGHT

242       Copyright 2001 - 2011 Adam Kennedy.
243
244       This program is free software; you can redistribute it and/or modify it
245       under the same terms as Perl itself.
246
247       The full text of the license can be found in the LICENSE file included
248       with this module.
249
250
251
252perl v5.28.0                      2017-06-22                  PPI::Document(3)