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

complete

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

TO DO

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

SUPPORT

231       See the support section in the main module.
232

AUTHOR

234       Adam Kennedy <adamk@cpan.org>
235

COPYRIGHT

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