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 @subs = $Document->find(
24               sub { $_[1]->isa('PPI::Statement::Sub') and $_[1]->name }
25               );
26
27         # Save the file
28         $Document->save('My/Module.pm.stripped');
29

DESCRIPTION

31       The "PPI::Document" class represents a single Perl "document". A
32       "PPI::Document" object acts as a root PPI::Node, with some additional
33       methods for loading and saving, and working with the line/column loca‐
34       tions of Elements within a file.
35
36       The exemption to its PPI::Node-like behavior this is that a "PPI::Docu‐
37       ment" object can NEVER have a parent node, and is always the root node
38       in a tree.
39
40       Storable Support
41
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 clone a Document, you are highly recom‐
47       mended to use the internal "$Document->clone" method rather than
48       Storable's "dclone" 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
60         # Simple construction
61         $doc = PPI::Document->new( $filename );
62         $doc = PPI::Document->new( \$source  );
63
64         # With the readonly attribute set
65         $doc = PPI::Document->new( $filename,
66                 readonly => 1,
67                 );
68
69       The "new" constructor takes as argument a variety of different sources
70       of Perl code, and creates a single cohesive Perl "PPI::Document" for
71       it.
72
73       If passed a file name as a normal string, it will attempt to load the
74       document from the file.
75
76       If passed a reference to a "SCALAR", this is taken to be source code
77       and parsed directly to create the document.
78
79       If passed zero arguments, a "blank" document will be created that con‐
80       tains no content at all.
81
82       In all cases, the document is considered to be "anonymous" and not tied
83       back to where it was created from. Specifically, if you create a
84       PPI::Document from a filename, the document will not remember where it
85       was created from.
86
87       The constructor also takes attribute flags.
88
89       At this time, the only available attribute is the "readonly" flag.
90
91       Setting "readonly" to true will allow various systems to provide addi‐
92       tional optimisations and caching. Note that because "readonly" is an
93       optimisation flag, it is off by default and you will need to explicitly
94       enable it.
95
96       Returns a "PPI::Document" object, or "undef" if parsing fails.
97
98       set_cache $cache
99
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
118       If a document cache is currently set, the "get_cache" method will
119       return it.
120
121       Returns a PPI::Cache object, or "undef" if there is no cache currently
122       set for "PPI::Document".
123
124       readonly
125
126       The "readonly" attribute indicates if the document is intended to be
127       read-only, and will never be modified. This is an advisory flag, that
128       writers of PPI-related systems may or may not use to enable optimisa‐
129       tions and caches for your document.
130
131       Returns true if the document is read-only or false if not.
132
133       tab_width [ $width ]
134
135       In order to handle support for "location" correctly, "Documents" need
136       to understand the concept of tabs and tab width. The "tab_width" method
137       is used to get and set the size of the tab width.
138
139       At the present time, PPI only supports "naive" (width 1) tabs, but we
140       do plan on supporting arbitrary, default and auto-sensing tab widths
141       later.
142
143       Returns the tab width as an integer, or "die"s if you attempt to set
144       the tab width.
145
146       save
147
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
156       Unlike the "content" method, which shows only the immediate content
157       within an element, Document objects also have to be able to be written
158       out to a file again.
159
160       When doing this we need to take into account some additional factors.
161
162       Primarily, we need to handle here-docs correctly, so that are written
163       to the file in the expected place.
164
165       The "serialize" method generates the actual file content for a given
166       Document object. The resulting string can be written straight to a
167       file.
168
169       Returns the serialized document as a string.
170
171       hex_id
172
173       The "hex_id" method generates an unique identifier for the Perl docu‐
174       ment.
175
176       This identifier is basically just the serialized document, with Unix-
177       specific newlines, passed through MD5 to produce a hexadecimal string.
178
179       This identifier is used by a variety of systems (such as PPI::Cache and
180       Perl::Metrics) as a unique key against which to store or cache informa‐
181       tion about a document (or indeed, to cache the document itself).
182
183       Returns a 32 character hexadecimal string.
184
185       index_locations
186
187       Within a document, all PPI::Element objects can be considered to have a
188       "location", a line/column position within the document when considered
189       as a file. This position is primarily useful for debugging type activi‐
190       ties.
191
192       The method for finding the position of a single Element is a bit labo‐
193       rious, and very slow if you need to do it a lot. So the "index_loca‐
194       tions" method will index and save the locations of every Element within
195       the Document in advance, making future calls to <PPI::Element::loca‐
196       tion> virtually free.
197
198       Please note that this is index should always be cleared using
199       "flush_locations" once you are finished with the locations. If content
200       is added to or removed from the file, these indexed locations will be
201       wrong.
202
203       flush_locations
204
205       When no longer needed, the "flush_locations" method clears all location
206       data from the tokens.
207
208       normalized
209
210       The "normalized" method is used to generate a "Layer 1" PPI::Docu‐
211       ment::Normalized object for the current Document.
212
213       A "normalized" Perl Document is an arbitrary structure that removes any
214       irrelevant parts of the document and refactors out variations in style,
215       to attempt to approach something that is closer to the "true meaning"
216       of the Document.
217
218       See PPI::Normal for more information on document normalization and the
219       tasks for which it is useful.
220
221       Returns a PPI::Document::Normalized object, or "undef" on error.
222
223       errstr
224
225       For error that occur when loading and saving documents, you can use
226       "errstr", as either a static or object method, to access the error mes‐
227       sage.
228
229       If a Document loads or saves without error, "errstr" will return false.
230

TO DO

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

SUPPORT

236       See the support section in the main module.
237

AUTHOR

239       Adam Kennedy <adamk@cpan.org>
240

COPYRIGHT

245       Copyright 2001 - 2006 Adam Kennedy.
246
247       This program is free software; you can redistribute it and/or modify it
248       under the same terms as Perl itself.
249
250       The full text of the license can be found in the LICENSE file included
251       with this module.
252
253
254
255perl v5.8.8                       2006-09-23                  PPI::Document(3)