local-lib5/man/man3/PPI::Document.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "PPI::Document 3"
 127 .TH PPI::Document 3 "2009-08-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 PPI::Document \- Object representation of a Perl document
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 3
 137 \&  PPI::Document
 138 \&  isa PPI::Node
 139 \&      isa PPI::Element
 140 .Ve
 141 .SH "SYNOPSIS"
 142 .IX Header "SYNOPSIS"
 143 .Vb 1
 144 \&  use PPI;
 145 \&
 146 \&  # Load a document from a file
 147 \&  my $Document = PPI::Document\->new(\*(AqMy/Module.pm\*(Aq);
 148 \&
 149 \&  # Strip out comments
 150 \&  $Document\->prune(\*(AqPPI::Token::Comment\*(Aq);
 151 \&
 152 \&  # Find all the named subroutines
 153 \&  my $sub_nodes = $Document\->find(
 154 \&        sub { $_[1]\->isa(\*(AqPPI::Statement::Sub\*(Aq) and $_[1]\->name }
 155 \&  );
 156 \&  my @sub_names = map { $_\->name } @$sub_nodes;
 157 \&
 158 \&  # Save the file
 159 \&  $Document\->save(\*(AqMy/Module.pm.stripped\*(Aq);
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 The \f(CW\*(C`PPI::Document\*(C'\fR class represents a single Perl \*(L"document\*(R". A
 164 \&\f(CW\*(C`PPI::Document\*(C'\fR object acts as a root PPI::Node, with some
 165 additional methods for loading and saving, and working with
 166 the line/column locations of Elements within a file.
 167 .PP
 168 The exemption to its PPI::Node\-like behavior this is that a
 169 \&\f(CW\*(C`PPI::Document\*(C'\fR object can \s-1NEVER\s0 have a parent node, and is always
 170 the root node in a tree.
 171 .SS "Storable Support"
 172 .IX Subsection "Storable Support"
 173 \&\f(CW\*(C`PPI::Document\*(C'\fR implements the necessary \f(CW\*(C`STORABLE_freeze\*(C'\fR and
 174 \&\f(CW\*(C`STORABLE_thaw\*(C'\fR hooks to provide native support for Storable,
 175 if you have it installed.
 176 .PP
 177 However if you want to clone clone a Document, you are highly recommended
 178 to use the internal \f(CW\*(C`$Document\->clone\*(C'\fR method rather than Storable's
 179 \&\f(CW\*(C`dclone\*(C'\fR function (although \f(CW\*(C`dclone\*(C'\fR should still work).
 180 .SH "METHODS"
 181 .IX Header "METHODS"
 182 Most of the things you are likely to want to do with a Document are
 183 probably going to involve the methods from PPI::Node class, of which
 184 this is a subclass.
 185 .PP
 186 The methods listed here are the remaining few methods that are truly
 187 Document-specific.
 188 .SS "new"
 189 .IX Subsection "new"
 190 .Vb 3
 191 \&  # Simple construction
 192 \&  $doc = PPI::Document\->new( $filename );
 193 \&  $doc = PPI::Document\->new( \e$source  );
 194 \&
 195 \&  # With the readonly attribute set
 196 \&  $doc = PPI::Document\->new( $filename,
 197 \&          readonly => 1,
 198 \&  );
 199 .Ve
 200 .PP
 201 The \f(CW\*(C`new\*(C'\fR constructor takes as argument a variety of different sources of
 202 Perl code, and creates a single cohesive Perl \f(CW\*(C`PPI::Document\*(C'\fR
 203 for it.
 204 .PP
 205 If passed a file name as a normal string, it will attempt to load the
 206 document from the file.
 207 .PP
 208 If passed a reference to a \f(CW\*(C`SCALAR\*(C'\fR, this is taken to be source code and
 209 parsed directly to create the document.
 210 .PP
 211 If passed zero arguments, a \*(L"blank\*(R" document will be created that contains
 212 no content at all.
 213 .PP
 214 In all cases, the document is considered to be \*(L"anonymous\*(R" and not tied back
 215 to where it was created from. Specifically, if you create a PPI::Document from
 216 a filename, the document will \fBnot\fR remember where it was created from.
 217 .PP
 218 The constructor also takes attribute flags.
 219 .PP
 220 At this time, the only available attribute is the \f(CW\*(C`readonly\*(C'\fR flag.
 221 .PP
 222 Setting \f(CW\*(C`readonly\*(C'\fR to true will allow various systems to provide
 223 additional optimisations and caching. Note that because \f(CW\*(C`readonly\*(C'\fR is an
 224 optimisation flag, it is off by default and you will need to explicitly
 225 enable it.
 226 .PP
 227 Returns a \f(CW\*(C`PPI::Document\*(C'\fR object, or \f(CW\*(C`undef\*(C'\fR if parsing fails.
 228 .ie n .SS "set_cache $cache"
 229 .el .SS "set_cache \f(CW$cache\fP"
 230 .IX Subsection "set_cache $cache"
 231 As of \s-1PPI\s0 1.100, \f(CW\*(C`PPI::Document\*(C'\fR supports parser caching.
 232 .PP
 233 The default cache class PPI::Cache provides a Storable\-based
 234 caching or the parsed document based on the \s-1MD5\s0 hash of the document as
 235 a string.
 236 .PP
 237 The static \f(CW\*(C`set_cache\*(C'\fR method is used to set the cache object for
 238 \&\f(CW\*(C`PPI::Document\*(C'\fR to use when loading documents. It takes as argument
 239 a PPI::Cache object (or something that \f(CW\*(C`isa\*(C'\fR the same).
 240 .PP
 241 If passed \f(CW\*(C`undef\*(C'\fR, this method will stop using the current cache, if any.
 242 .PP
 243 For more information on caching, see PPI::Cache.
 244 .PP
 245 Returns true on success, or \f(CW\*(C`undef\*(C'\fR if not passed a valid param.
 246 .SS "get_cache"
 247 .IX Subsection "get_cache"
 248 If a document cache is currently set, the \f(CW\*(C`get_cache\*(C'\fR method will
 249 return it.
 250 .PP
 251 Returns a PPI::Cache object, or \f(CW\*(C`undef\*(C'\fR if there is no cache
 252 currently set for \f(CW\*(C`PPI::Document\*(C'\fR.
 253 .SS "readonly"
 254 .IX Subsection "readonly"
 255 The \f(CW\*(C`readonly\*(C'\fR attribute indicates if the document is intended to be
 256 read-only, and will never be modified. This is an advisory flag, that
 257 writers of \s-1PPI\s0\-related systems may or may not use to enable
 258 optimisations and caches for your document.
 259 .PP
 260 Returns true if the document is read-only or false if not.
 261 .ie n .SS "tab_width [ $width ]"
 262 .el .SS "tab_width [ \f(CW$width\fP ]"
 263 .IX Subsection "tab_width [ $width ]"
 264 In order to handle support for \f(CW\*(C`location\*(C'\fR correctly, \f(CW\*(C`Documents\*(C'\fR
 265 need to understand the concept of tabs and tab width. The \f(CW\*(C`tab_width\*(C'\fR
 266 method is used to get and set the size of the tab width.
 267 .PP
 268 At the present time, \s-1PPI\s0 only supports \*(L"naive\*(R" (width 1) tabs, but we do
 269 plan on supporting arbitrary, default and auto-sensing tab widths later.
 270 .PP
 271 Returns the tab width as an integer, or \f(CW\*(C`die\*(C'\fRs if you attempt to set the
 272 tab width.
 273 .SS "save"
 274 .IX Subsection "save"
 275 .Vb 1
 276 \&  $document\->save( $file )
 277 .Ve
 278 .PP
 279 The \f(CW\*(C`save\*(C'\fR method serializes the \f(CW\*(C`PPI::Document\*(C'\fR object and saves the
 280 resulting Perl document to a file. Returns \f(CW\*(C`undef\*(C'\fR on failure to open
 281 or write to the file.
 282 .SS "serialize"
 283 .IX Subsection "serialize"
 284 Unlike the \f(CW\*(C`content\*(C'\fR method, which shows only the immediate content
 285 within an element, Document objects also have to be able to be written
 286 out to a file again.
 287 .PP
 288 When doing this we need to take into account some additional factors.
 289 .PP
 290 Primarily, we need to handle here-docs correctly, so that are written
 291 to the file in the expected place.
 292 .PP
 293 The \f(CW\*(C`serialize\*(C'\fR method generates the actual file content for a given
 294 Document object. The resulting string can be written straight to a file.
 295 .PP
 296 Returns the serialized document as a string.
 297 .SS "hex_id"
 298 .IX Subsection "hex_id"
 299 The \f(CW\*(C`hex_id\*(C'\fR method generates an unique identifier for the Perl document.
 300 .PP
 301 This identifier is basically just the serialized document, with
 302 Unix-specific newlines, passed through \s-1MD5\s0 to produce a hexadecimal string.
 303 .PP
 304 This identifier is used by a variety of systems (such as PPI::Cache
 305 and Perl::Metrics) as a unique key against which to store or cache
 306 information about a document (or indeed, to cache the document itself).
 307 .PP
 308 Returns a 32 character hexadecimal string.
 309 .SS "index_locations"
 310 .IX Subsection "index_locations"
 311 Within a document, all PPI::Element objects can be considered to have a
 312 \&\*(L"location\*(R", a line/column position within the document when considered as a
 313 file. This position is primarily useful for debugging type activities.
 314 .PP
 315 The method for finding the position of a single Element is a bit laborious,
 316 and very slow if you need to do it a lot. So the \f(CW\*(C`index_locations\*(C'\fR method
 317 will index and save the locations of every Element within the Document in
 318 advance, making future calls to <PPI::Element::location> virtually free.
 319 .PP
 320 Please note that this index should always be cleared using \f(CW\*(C`flush_locations\*(C'\fR
 321 once you are finished with the locations. If content is added to or removed
 322 from the file, these indexed locations will be \fBwrong\fR.
 323 .SS "flush_locations"
 324 .IX Subsection "flush_locations"
 325 When no longer needed, the \f(CW\*(C`flush_locations\*(C'\fR method clears all location data
 326 from the tokens.
 327 .SS "normalized"
 328 .IX Subsection "normalized"
 329 The \f(CW\*(C`normalized\*(C'\fR method is used to generate a \*(L"Layer 1\*(R"
 330 PPI::Document::Normalized object for the current Document.
 331 .PP
 332 A \*(L"normalized\*(R" Perl Document is an arbitrary structure that removes any
 333 irrelevant parts of the document and refactors out variations in style,
 334 to attempt to approach something that is closer to the \*(L"true meaning\*(R"
 335 of the Document.
 336 .PP
 337 See PPI::Normal for more information on document normalization and
 338 the tasks for which it is useful.
 339 .PP
 340 Returns a PPI::Document::Normalized object, or \f(CW\*(C`undef\*(C'\fR on error.
 341 .SH "complete"
 342 .IX Header "complete"
 343 The \f(CW\*(C`complete\*(C'\fR method is used to determine if a document is cleanly
 344 structured, all braces are closed, the final statement is
 345 fully terminated and all heredocs are fully entered.
 346 .PP
 347 Returns true if the document is complete or false if not.
 348 .SS "errstr"
 349 .IX Subsection "errstr"
 350 For error that occur when loading and saving documents, you can use
 351 \&\f(CW\*(C`errstr\*(C'\fR, as either a static or object method, to access the error message.
 352 .PP
 353 If a Document loads or saves without error, \f(CW\*(C`errstr\*(C'\fR will return false.
 354 .SH "TO DO"
 355 .IX Header "TO DO"
 356 \&\- May need to overload some methods to forcefully prevent Document
 357 objects becoming children of another Node.
 358 .SH "SUPPORT"
 359 .IX Header "SUPPORT"
 360 See the support section in the main module.
 361 .SH "AUTHOR"
 362 .IX Header "AUTHOR"
 363 Adam Kennedy <adamk@cpan.org>
 364 .SH "SEE ALSO"
 365 .IX Header "SEE ALSO"
 366 \&\s-1PPI\s0, <http://ali.as/>
 367 .SH "COPYRIGHT"
 368 .IX Header "COPYRIGHT"
 369 Copyright 2001 \- 2009 Adam Kennedy.
 370 .PP
 371 This program is free software; you can redistribute
 372 it and/or modify it under the same terms as Perl itself.
 373 .PP
 374 The full text of the license can be found in the
 375 \&\s-1LICENSE\s0 file included with this module.