Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / PPI::Token::Whitespace.3pm

.\" 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::Token::Whitespace 3"
.TH PPI::Token::Whitespace 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::Token::Whitespace \- Tokens representing ordinary white space
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 3
\&  PPI::Token::Whitespace
\&  isa PPI::Token
\&      isa PPI::Element
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
As a full \*(L"round-trip\*(R" parser, \s-1PPI\s0 records every last byte in a
file and ensure that it is included in the PPI::Document object.
.PP
This even includes whitespace. In fact, Perl documents are seen
as \*(L"floating in a sea of whitespace\*(R", and thus any document will
contain vast quantities of \f(CW\*(C`PPI::Token::Whitespace\*(C'\fR objects.
.PP
For the most part, you shouldn't notice them. Or at least, you
shouldn't \fBhave\fR to notice them.
.PP
This means doing things like consistently using the \*(L"S for significant\*(R"
series of PPI::Node and PPI::Element methods to do things.
.PP
If you want the nth child element, you should be using \f(CW\*(C`schild\*(C'\fR rather
than \f(CW\*(C`child\*(C'\fR, and likewise \f(CW\*(C`snext_sibling\*(C'\fR, \f(CW\*(C`sprevious_sibling\*(C'\fR, and
so on and so forth.
.SH "METHODS"
.IX Header "METHODS"
Again, for the most part you should really \fBnot\fR need to do anything
very significant with whitespace.
.PP
But there are a couple of convenience methods provided, beyond those
provided by the parent PPI::Token and PPI::Element classes.
.SS "null"
.IX Subsection "null"
Because \s-1PPI\s0 sees documents as sitting on a sort of substrate made of
whitespace, there are a couple of corner cases that get particularly
nasty if they don't find whitespace in certain places.
.PP
Imagine walking down the beach to go into the ocean, and then quite
unexpectedly falling off the side of the planet. Well it's somewhat
equivalent to that, including the whole screaming death bit.
.PP
The \f(CW\*(C`null\*(C'\fR method is a convenience provided to get some internals
out of some of these corner cases.
.PP
Specifically it create a whitespace token that represents nothing,
or at least the null string \f(CW\*(Aq\*(Aq\fR. It's a handy way to have some
\&\*(L"whitespace\*(R" right where you need it, without having to have any
actual characters.
.SS "tidy"
.IX Subsection "tidy"
\&\f(CW\*(C`tidy\*(C'\fR is a convenience method for removing unneeded whitespace.
.PP
Specifically, it removes any whitespace from the end of a line.
.PP
Note that this \fBdoesn't\fR include \s-1POD\s0, where you may well need
to keep certain types of whitespace. The entire \s-1POD\s0 chunk lives
in its own PPI::Token::Pod object.
.SH "SUPPORT"
.IX Header "SUPPORT"
See the support section in the main module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.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.