local-lib5/man/man3/PPI::Statement.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::Statement 3"
 127 .TH PPI::Statement 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::Statement \- The base class for Perl statements
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 3
 137 \&  PPI::Statement
 138 \&  isa PPI::Node
 139 \&      isa PPI::Element
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 PPI::Statement is the root class for all Perl statements. This includes (from
 144 perlsyn) \*(L"Declarations\*(R", \*(L"Simple Statements\*(R" and \*(L"Compound Statements\*(R".
 145 .PP
 146 The class PPI::Statement itself represents a \*(L"Simple Statement\*(R" as defined
 147 in the perlsyn manpage.
 148 .SH "STATEMENT CLASSES"
 149 .IX Header "STATEMENT CLASSES"
 150 Please note that unless documented themselves, these classes are yet to be
 151 frozen/finalised. Names may change slightly or be added or removed.
 152 .SS "PPI::Statement::Scheduled"
 153 .IX Subsection "PPI::Statement::Scheduled"
 154 This covers all \*(L"scheduled\*(R" blocks, chunks of code that are executed separately
 155 from the main body of the code, at a particular time. This includes all
 156 \&\f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR blocks.
 157 .SS "PPI::Statement::Package"
 158 .IX Subsection "PPI::Statement::Package"
 159 A package declaration, as defined in perlfunc.
 160 .SS "PPI::Statement::Include"
 161 .IX Subsection "PPI::Statement::Include"
 162 A statement that loads or unloads another module.
 163 .PP
 164 This includes 'use', 'no', and 'require' statements.
 165 .SS "PPI::Statement::Sub"
 166 .IX Subsection "PPI::Statement::Sub"
 167 A named subroutine declaration, or forward declaration
 168 .SS "PPI::Statement::Variable"
 169 .IX Subsection "PPI::Statement::Variable"
 170 A variable declaration statement. This could be either a straight
 171 declaration or also be an expression.
 172 .PP
 173 This includes all 'my', 'state', 'local' and 'our' statements.
 174 .SS "PPI::Statement::Compound"
 175 .IX Subsection "PPI::Statement::Compound"
 176 This covers the whole family of 'compound' statements, as described in
 177 perlsyn.
 178 .PP
 179 This includes all statements starting with 'if', 'unless', 'for', 'foreach'
 180 and 'while'. Note that this does \s-1NOT\s0 include 'do', as it is treated
 181 differently.
 182 .PP
 183 All compound statements have implicit ends. That is, they do not end with
 184 a ';' statement terminator.
 185 .SS "PPI::Statement::Break"
 186 .IX Subsection "PPI::Statement::Break"
 187 A statement that breaks out of a structure.
 188 .PP
 189 This includes all of 'redo', 'next', 'last' and 'return' statements.
 190 .SS "PPI::Statement::Given"
 191 .IX Subsection "PPI::Statement::Given"
 192 The kind of statement introduced in Perl 5.10 that starts with 'given'.  This
 193 has an implicit end.
 194 .SS "PPI::Statement::When"
 195 .IX Subsection "PPI::Statement::When"
 196 The kind of statement introduced in Perl 5.10 that starts with 'when' or
 197 \&'default'.  This also has an implicit end.
 198 .SS "PPI::Statement::Data"
 199 .IX Subsection "PPI::Statement::Data"
 200 A special statement which encompasses an entire \f(CW\*(C`_\|_DATA_\|_\*(C'\fR block, including
 201 the initial \f(CW\*(Aq_\|_DATA_\|_\*(Aq\fR token itself and the entire contents.
 202 .SS "PPI::Statement::End"
 203 .IX Subsection "PPI::Statement::End"
 204 A special statement which encompasses an entire _\|_END_\|_ block, including
 205 the initial '_\|_END_\|_' token itself and the entire contents, including any
 206 parsed PPI::Token::POD that may occur in it.
 207 .SS "PPI::Statement::Expression"
 208 .IX Subsection "PPI::Statement::Expression"
 209 PPI::Statement::Expression is a little more speculative, and is intended
 210 to help represent the special rules relating to \*(L"expressions\*(R" such as in:
 211 .PP
 212 .Vb 1
 213 \&  # Several examples of expression statements
 214 \&
 215 \&  # Boolean conditions
 216 \&  if ( expression ) { ... }
 217 \&
 218 \&  # Lists, such as for arguments
 219 \&  Foo\->bar( expression )
 220 .Ve
 221 .SS "PPI::Statement::Null"
 222 .IX Subsection "PPI::Statement::Null"
 223 A null statement is a special case for where we encounter two consecutive
 224 statement terminators. ( ;; )
 225 .PP
 226 The second terminator is given an entire statement of its own, but one
 227 that serves no purpose. Hence a 'null' statement.
 228 .PP
 229 Theoretically, assuming a correct parsing of a perl file, all null statements
 230 are superfluous and should be able to be removed without damage to the file.
 231 .PP
 232 But don't do that, in case \s-1PPI\s0 has parsed something wrong.
 233 .SS "PPI::Statement::UnmatchedBrace"
 234 .IX Subsection "PPI::Statement::UnmatchedBrace"
 235 Because \s-1PPI\s0 is intended for use when parsing incorrect or incomplete code,
 236 the problem arises of what to do with a stray closing brace.
 237 .PP
 238 Rather than die, it is allocated its own \*(L"unmatched brace\*(R" statement,
 239 which really means \*(L"unmatched closing brace\*(R". An unmatched open brace at the
 240 end of a file would become a structure with no contents and no closing brace.
 241 .PP
 242 If the document loaded is intended to be correct and valid, finding a
 243 PPI::Statement::UnmatchedBrace in the \s-1PDOM\s0 is generally indicative of a
 244 misparse.
 245 .SS "PPI::Statement::Unknown"
 246 .IX Subsection "PPI::Statement::Unknown"
 247 This is used temporarily mid-parsing to hold statements for which the lexer
 248 cannot yet determine what class it should be, usually because there are
 249 insufficient clues, or it might be more than one thing.
 250 .PP
 251 You should never encounter these in a fully parsed \s-1PDOM\s0 tree.
 252 .SH "METHODS"
 253 .IX Header "METHODS"
 254 \&\f(CW\*(C`PPI::Statement\*(C'\fR itself has very few methods. Most of the time, you will be
 255 working with the more generic PPI::Element or PPI::Node methods, or one
 256 of the methods that are subclass-specific.
 257 .SS "label"
 258 .IX Subsection "label"
 259 One factor common to most statements is their ability to be labeled.
 260 .PP
 261 The \f(CW\*(C`label\*(C'\fR method returns the label for a statement, if one has been
 262 defined, but without the trailing colon. Take the following example
 263 .PP
 264 .Vb 1
 265 \&  MYLABEL: while ( 1 .. 10 ) { last MYLABEL if $_ > 5 }
 266 .Ve
 267 .PP
 268 For the above statement, the \f(CW\*(C`label\*(C'\fR method would return '\s-1MYLABEL\s0'.
 269 .PP
 270 Returns false if the statement does not have a label.
 271 .SS "specialized"
 272 .IX Subsection "specialized"
 273 Answer whether this is a plain statement or one that has more
 274 significance.
 275 .PP
 276 Returns true if the statement is a subclass of this one, false
 277 otherwise.
 278 .SS "stable"
 279 .IX Subsection "stable"
 280 Much like the PPI::Document method of the same name, the \->stable
 281 method converts a statement to source and back again, to determine if
 282 a modified statement is still legal, and won't be interpreted in a
 283 different way.
 284 .PP
 285 Returns true if the statement is stable, false if not, or \f(CW\*(C`undef\*(C'\fR on
 286 error.
 287 .SH "TO DO"
 288 .IX Header "TO DO"
 289 \&\- Complete, freeze and document the remaining classes
 290 .SH "SUPPORT"
 291 .IX Header "SUPPORT"
 292 See the support section in the main module.
 293 .SH "AUTHOR"
 294 .IX Header "AUTHOR"
 295 Adam Kennedy <adamk@cpan.org>
 296 .SH "COPYRIGHT"
 297 .IX Header "COPYRIGHT"
 298 Copyright 2001 \- 2009 Adam Kennedy.
 299 .PP
 300 This program is free software; you can redistribute
 301 it and/or modify it under the same terms as Perl itself.
 302 .PP
 303 The full text of the license can be found in the
 304 \&\s-1LICENSE\s0 file included with this module.