--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "PPI::Document 3"
+.TH PPI::Document 3 "2009-08-08" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+PPI::Document \- Object representation of a Perl document
+.SH "INHERITANCE"
+.IX Header "INHERITANCE"
+.Vb 3
+\& PPI::Document
+\& isa PPI::Node
+\& isa PPI::Element
+.Ve
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use PPI;
+\&
+\& # Load a document from a file
+\& my $Document = PPI::Document\->new(\*(AqMy/Module.pm\*(Aq);
+\&
+\& # Strip out comments
+\& $Document\->prune(\*(AqPPI::Token::Comment\*(Aq);
+\&
+\& # Find all the named subroutines
+\& my $sub_nodes = $Document\->find(
+\& sub { $_[1]\->isa(\*(AqPPI::Statement::Sub\*(Aq) and $_[1]\->name }
+\& );
+\& my @sub_names = map { $_\->name } @$sub_nodes;
+\&
+\& # Save the file
+\& $Document\->save(\*(AqMy/Module.pm.stripped\*(Aq);
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`PPI::Document\*(C'\fR class represents a single Perl \*(L"document\*(R". A
+\&\f(CW\*(C`PPI::Document\*(C'\fR object acts as a root PPI::Node, with some
+additional methods for loading and saving, and working with
+the line/column locations of Elements within a file.
+.PP
+The exemption to its PPI::Node\-like behavior this is that a
+\&\f(CW\*(C`PPI::Document\*(C'\fR object can \s-1NEVER\s0 have a parent node, and is always
+the root node in a tree.
+.SS "Storable Support"
+.IX Subsection "Storable Support"
+\&\f(CW\*(C`PPI::Document\*(C'\fR implements the necessary \f(CW\*(C`STORABLE_freeze\*(C'\fR and
+\&\f(CW\*(C`STORABLE_thaw\*(C'\fR hooks to provide native support for Storable,
+if you have it installed.
+.PP
+However if you want to clone clone a Document, you are highly recommended
+to use the internal \f(CW\*(C`$Document\->clone\*(C'\fR method rather than Storable's
+\&\f(CW\*(C`dclone\*(C'\fR function (although \f(CW\*(C`dclone\*(C'\fR should still work).
+.SH "METHODS"
+.IX Header "METHODS"
+Most of the things you are likely to want to do with a Document are
+probably going to involve the methods from PPI::Node class, of which
+this is a subclass.
+.PP
+The methods listed here are the remaining few methods that are truly
+Document-specific.
+.SS "new"
+.IX Subsection "new"
+.Vb 3
+\& # Simple construction
+\& $doc = PPI::Document\->new( $filename );
+\& $doc = PPI::Document\->new( \e$source );
+\&
+\& # With the readonly attribute set
+\& $doc = PPI::Document\->new( $filename,
+\& readonly => 1,
+\& );
+.Ve
+.PP
+The \f(CW\*(C`new\*(C'\fR constructor takes as argument a variety of different sources of
+Perl code, and creates a single cohesive Perl \f(CW\*(C`PPI::Document\*(C'\fR
+for it.
+.PP
+If passed a file name as a normal string, it will attempt to load the
+document from the file.
+.PP
+If passed a reference to a \f(CW\*(C`SCALAR\*(C'\fR, this is taken to be source code and
+parsed directly to create the document.
+.PP
+If passed zero arguments, a \*(L"blank\*(R" document will be created that contains
+no content at all.
+.PP
+In all cases, the document is considered to be \*(L"anonymous\*(R" and not tied back
+to where it was created from. Specifically, if you create a PPI::Document from
+a filename, the document will \fBnot\fR remember where it was created from.
+.PP
+The constructor also takes attribute flags.
+.PP
+At this time, the only available attribute is the \f(CW\*(C`readonly\*(C'\fR flag.
+.PP
+Setting \f(CW\*(C`readonly\*(C'\fR to true will allow various systems to provide
+additional optimisations and caching. Note that because \f(CW\*(C`readonly\*(C'\fR is an
+optimisation flag, it is off by default and you will need to explicitly
+enable it.
+.PP
+Returns a \f(CW\*(C`PPI::Document\*(C'\fR object, or \f(CW\*(C`undef\*(C'\fR if parsing fails.
+.ie n .SS "set_cache $cache"
+.el .SS "set_cache \f(CW$cache\fP"
+.IX Subsection "set_cache $cache"
+As of \s-1PPI\s0 1.100, \f(CW\*(C`PPI::Document\*(C'\fR supports parser caching.
+.PP
+The default cache class PPI::Cache provides a Storable\-based
+caching or the parsed document based on the \s-1MD5\s0 hash of the document as
+a string.
+.PP
+The static \f(CW\*(C`set_cache\*(C'\fR method is used to set the cache object for
+\&\f(CW\*(C`PPI::Document\*(C'\fR to use when loading documents. It takes as argument
+a PPI::Cache object (or something that \f(CW\*(C`isa\*(C'\fR the same).
+.PP
+If passed \f(CW\*(C`undef\*(C'\fR, this method will stop using the current cache, if any.
+.PP
+For more information on caching, see PPI::Cache.
+.PP
+Returns true on success, or \f(CW\*(C`undef\*(C'\fR if not passed a valid param.
+.SS "get_cache"
+.IX Subsection "get_cache"
+If a document cache is currently set, the \f(CW\*(C`get_cache\*(C'\fR method will
+return it.
+.PP
+Returns a PPI::Cache object, or \f(CW\*(C`undef\*(C'\fR if there is no cache
+currently set for \f(CW\*(C`PPI::Document\*(C'\fR.
+.SS "readonly"
+.IX Subsection "readonly"
+The \f(CW\*(C`readonly\*(C'\fR attribute indicates if the document is intended to be
+read-only, and will never be modified. This is an advisory flag, that
+writers of \s-1PPI\s0\-related systems may or may not use to enable
+optimisations and caches for your document.
+.PP
+Returns true if the document is read-only or false if not.
+.ie n .SS "tab_width [ $width ]"
+.el .SS "tab_width [ \f(CW$width\fP ]"
+.IX Subsection "tab_width [ $width ]"
+In order to handle support for \f(CW\*(C`location\*(C'\fR correctly, \f(CW\*(C`Documents\*(C'\fR
+need to understand the concept of tabs and tab width. The \f(CW\*(C`tab_width\*(C'\fR
+method is used to get and set the size of the tab width.
+.PP
+At the present time, \s-1PPI\s0 only supports \*(L"naive\*(R" (width 1) tabs, but we do
+plan on supporting arbitrary, default and auto-sensing tab widths later.
+.PP
+Returns the tab width as an integer, or \f(CW\*(C`die\*(C'\fRs if you attempt to set the
+tab width.
+.SS "save"
+.IX Subsection "save"
+.Vb 1
+\& $document\->save( $file )
+.Ve
+.PP
+The \f(CW\*(C`save\*(C'\fR method serializes the \f(CW\*(C`PPI::Document\*(C'\fR object and saves the
+resulting Perl document to a file. Returns \f(CW\*(C`undef\*(C'\fR on failure to open
+or write to the file.
+.SS "serialize"
+.IX Subsection "serialize"
+Unlike the \f(CW\*(C`content\*(C'\fR method, which shows only the immediate content
+within an element, Document objects also have to be able to be written
+out to a file again.
+.PP
+When doing this we need to take into account some additional factors.
+.PP
+Primarily, we need to handle here-docs correctly, so that are written
+to the file in the expected place.
+.PP
+The \f(CW\*(C`serialize\*(C'\fR method generates the actual file content for a given
+Document object. The resulting string can be written straight to a file.
+.PP
+Returns the serialized document as a string.
+.SS "hex_id"
+.IX Subsection "hex_id"
+The \f(CW\*(C`hex_id\*(C'\fR method generates an unique identifier for the Perl document.
+.PP
+This identifier is basically just the serialized document, with
+Unix-specific newlines, passed through \s-1MD5\s0 to produce a hexadecimal string.
+.PP
+This identifier is used by a variety of systems (such as PPI::Cache
+and Perl::Metrics) as a unique key against which to store or cache
+information about a document (or indeed, to cache the document itself).
+.PP
+Returns a 32 character hexadecimal string.
+.SS "index_locations"
+.IX Subsection "index_locations"
+Within a document, all PPI::Element objects can be considered to have a
+\&\*(L"location\*(R", a line/column position within the document when considered as a
+file. This position is primarily useful for debugging type activities.
+.PP
+The method for finding the position of a single Element is a bit laborious,
+and very slow if you need to do it a lot. So the \f(CW\*(C`index_locations\*(C'\fR method
+will index and save the locations of every Element within the Document in
+advance, making future calls to <PPI::Element::location> virtually free.
+.PP
+Please note that this index should always be cleared using \f(CW\*(C`flush_locations\*(C'\fR
+once you are finished with the locations. If content is added to or removed
+from the file, these indexed locations will be \fBwrong\fR.
+.SS "flush_locations"
+.IX Subsection "flush_locations"
+When no longer needed, the \f(CW\*(C`flush_locations\*(C'\fR method clears all location data
+from the tokens.
+.SS "normalized"
+.IX Subsection "normalized"
+The \f(CW\*(C`normalized\*(C'\fR method is used to generate a \*(L"Layer 1\*(R"
+PPI::Document::Normalized object for the current Document.
+.PP
+A \*(L"normalized\*(R" Perl Document is an arbitrary structure that removes any
+irrelevant parts of the document and refactors out variations in style,
+to attempt to approach something that is closer to the \*(L"true meaning\*(R"
+of the Document.
+.PP
+See PPI::Normal for more information on document normalization and
+the tasks for which it is useful.
+.PP
+Returns a PPI::Document::Normalized object, or \f(CW\*(C`undef\*(C'\fR on error.
+.SH "complete"
+.IX Header "complete"
+The \f(CW\*(C`complete\*(C'\fR method is used to determine if a document is cleanly
+structured, all braces are closed, the final statement is
+fully terminated and all heredocs are fully entered.
+.PP
+Returns true if the document is complete or false if not.
+.SS "errstr"
+.IX Subsection "errstr"
+For error that occur when loading and saving documents, you can use
+\&\f(CW\*(C`errstr\*(C'\fR, as either a static or object method, to access the error message.
+.PP
+If a Document loads or saves without error, \f(CW\*(C`errstr\*(C'\fR will return false.
+.SH "TO DO"
+.IX Header "TO DO"
+\&\- May need to overload some methods to forcefully prevent Document
+objects becoming children of another Node.
+.SH "SUPPORT"
+.IX Header "SUPPORT"
+See the support section in the main module.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Adam Kennedy <adamk@cpan.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\s-1PPI\s0, <http://ali.as/>
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2001 \- 2009 Adam Kennedy.
+.PP
+This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+.PP
+The full text of the license can be found in the
+\&\s-1LICENSE\s0 file included with this module.
projects / catagits/Gitalist.git / blobdiff