local-lib5/man/man3/PPI::Token::Comment.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::Comment 3"
 127 .TH PPI::Token::Comment 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::Comment \- A comment in Perl source code
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 3
 137 \&  PPI::Token::Comment
 138 \&  isa PPI::Token
 139 \&      isa PPI::Element
 140 .Ve
 141 .SH "SYNOPSIS"
 142 .IX Header "SYNOPSIS"
 143 .Vb 1
 144 \&  # This is a PPI::Token::Comment
 145 \&
 146 \&  print "Hello World!"; # So it this
 147 \&
 148 \&  $string =~ s/ foo  # This, unfortunately, is not :(
 149 \&        bar
 150 \&        /w;
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 In \s-1PPI\s0, comments are represented by \f(CW\*(C`PPI::Token::Comment\*(C'\fR objects.
 155 .PP
 156 These come in two flavours, line comment and inline comments.
 157 .PP
 158 A \f(CW\*(C`line comment\*(C'\fR is a comment that stands on its own line. These comments
 159 hold their own newline and whitespace (both leading and trailing) as part
 160 of the one \f(CW\*(C`PPI::Token::Comment\*(C'\fR object.
 161 .PP
 162 An inline comment is a comment that appears after some code, and
 163 continues to the end of the line. This does \fBnot\fR include whitespace,
 164 and the terminating newlines is considered a separate
 165 PPI::Token::Whitespace token.
 166 .PP
 167 This is largely a convenience, simplifying a lot of normal code relating
 168 to the common things people do with comments.
 169 .PP
 170 Most commonly, it means when you \f(CW\*(C`prune\*(C'\fR or \f(CW\*(C`delete\*(C'\fR a comment, a line
 171 comment disappears taking the entire line with it, and an inline comment
 172 is removed from the inside of the line, allowing the newline to drop
 173 back onto the end of the code, as you would expect.
 174 .PP
 175 It also means you can move comments around in blocks much more easily.
 176 .PP
 177 For now, this is a suitably handy way to do things. However, I do reserve
 178 the right to change my mind on this one if it gets dangerously
 179 anachronistic somewhere down the line.
 180 .SH "METHODS"
 181 .IX Header "METHODS"
 182 Only very limited methods are available, beyond those provided by our
 183 parent PPI::Token and PPI::Element classes.
 184 .SS "line"
 185 .IX Subsection "line"
 186 The \f(CW\*(C`line\*(C'\fR accessor returns true if the \f(CW\*(C`PPI::Token::Comment\*(C'\fR is a
 187 line comment, or false if it is an inline comment.
 188 .SH "SUPPORT"
 189 .IX Header "SUPPORT"
 190 See the support section in the main module.
 191 .SH "AUTHOR"
 192 .IX Header "AUTHOR"
 193 Adam Kennedy <adamk@cpan.org>
 194 .SH "COPYRIGHT"
 195 .IX Header "COPYRIGHT"
 196 Copyright 2001 \- 2009 Adam Kennedy.
 197 .PP
 198 This program is free software; you can redistribute
 199 it and/or modify it under the same terms as Perl itself.
 200 .PP
 201 The full text of the license can be found in the
 202 \&\s-1LICENSE\s0 file included with this module.