local-lib5/man/man3/PPI::Token::Whitespace.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::Token::Whitespace 3"
 127 .TH PPI::Token::Whitespace 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::Token::Whitespace \- Tokens representing ordinary white space
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 3
 137 \&  PPI::Token::Whitespace
 138 \&  isa PPI::Token
 139 \&      isa PPI::Element
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 As a full \*(L"round-trip\*(R" parser, \s-1PPI\s0 records every last byte in a
 144 file and ensure that it is included in the PPI::Document object.
 145 .PP
 146 This even includes whitespace. In fact, Perl documents are seen
 147 as \*(L"floating in a sea of whitespace\*(R", and thus any document will
 148 contain vast quantities of \f(CW\*(C`PPI::Token::Whitespace\*(C'\fR objects.
 149 .PP
 150 For the most part, you shouldn't notice them. Or at least, you
 151 shouldn't \fBhave\fR to notice them.
 152 .PP
 153 This means doing things like consistently using the \*(L"S for significant\*(R"
 154 series of PPI::Node and PPI::Element methods to do things.
 155 .PP
 156 If you want the nth child element, you should be using \f(CW\*(C`schild\*(C'\fR rather
 157 than \f(CW\*(C`child\*(C'\fR, and likewise \f(CW\*(C`snext_sibling\*(C'\fR, \f(CW\*(C`sprevious_sibling\*(C'\fR, and
 158 so on and so forth.
 159 .SH "METHODS"
 160 .IX Header "METHODS"
 161 Again, for the most part you should really \fBnot\fR need to do anything
 162 very significant with whitespace.
 163 .PP
 164 But there are a couple of convenience methods provided, beyond those
 165 provided by the parent PPI::Token and PPI::Element classes.
 166 .SS "null"
 167 .IX Subsection "null"
 168 Because \s-1PPI\s0 sees documents as sitting on a sort of substrate made of
 169 whitespace, there are a couple of corner cases that get particularly
 170 nasty if they don't find whitespace in certain places.
 171 .PP
 172 Imagine walking down the beach to go into the ocean, and then quite
 173 unexpectedly falling off the side of the planet. Well it's somewhat
 174 equivalent to that, including the whole screaming death bit.
 175 .PP
 176 The \f(CW\*(C`null\*(C'\fR method is a convenience provided to get some internals
 177 out of some of these corner cases.
 178 .PP
 179 Specifically it create a whitespace token that represents nothing,
 180 or at least the null string \f(CW\*(Aq\*(Aq\fR. It's a handy way to have some
 181 \&\*(L"whitespace\*(R" right where you need it, without having to have any
 182 actual characters.
 183 .SS "tidy"
 184 .IX Subsection "tidy"
 185 \&\f(CW\*(C`tidy\*(C'\fR is a convenience method for removing unneeded whitespace.
 186 .PP
 187 Specifically, it removes any whitespace from the end of a line.
 188 .PP
 189 Note that this \fBdoesn't\fR include \s-1POD\s0, where you may well need
 190 to keep certain types of whitespace. The entire \s-1POD\s0 chunk lives
 191 in its own PPI::Token::Pod object.
 192 .SH "SUPPORT"
 193 .IX Header "SUPPORT"
 194 See the support section in the main module.
 195 .SH "AUTHOR"
 196 .IX Header "AUTHOR"
 197 Adam Kennedy <adamk@cpan.org>
 198 .SH "COPYRIGHT"
 199 .IX Header "COPYRIGHT"
 200 Copyright 2001 \- 2009 Adam Kennedy.
 201 .PP
 202 This program is free software; you can redistribute
 203 it and/or modify it under the same terms as Perl itself.
 204 .PP
 205 The full text of the license can be found in the
 206 \&\s-1LICENSE\s0 file included with this module.