1PPI::Statement(3)     User Contributed Perl Documentation    PPI::Statement(3)
2
3
4

NAME

6       PPI::Statement - The base class for Perl statements
7

INHERITANCE

9         PPI::Statement
10         isa PPI::Node
11             isa PPI::Element
12

DESCRIPTION

14       PPI::Statement is the root class for all Perl statements. This includes
15       (from perlsyn) "Declarations", "Simple Statements" and "Compound
16       Statements".
17
18       The class PPI::Statement itself represents a "Simple Statement" as
19       defined in the perlsyn manpage.
20

STATEMENT CLASSES

22       Please note that unless documented themselves, these classes are yet to
23       be frozen/finalised. Names may change slightly or be added or removed.
24
25   PPI::Statement::Scheduled
26       This covers all "scheduled" blocks, chunks of code that are executed
27       separately from the main body of the code, at a particular time. This
28       includes all "BEGIN", "CHECK", "UNITCHECK", "INIT" and "END" blocks.
29
30   PPI::Statement::Package
31       A package declaration, as defined in perlfunc.
32
33   PPI::Statement::Include
34       A statement that loads or unloads another module.
35
36       This includes 'use', 'no', and 'require' statements.
37
38   PPI::Statement::Sub
39       A named subroutine declaration, or forward declaration
40
41   PPI::Statement::Variable
42       A variable declaration statement. This could be either a straight
43       declaration or also be an expression.
44
45       This includes all 'my', 'state', 'local' and 'our' statements.
46
47   PPI::Statement::Compound
48       This covers the whole family of 'compound' statements, as described in
49       perlsyn.
50
51       This includes all statements starting with 'if', 'unless', 'for',
52       'foreach' and 'while'. Note that this does NOT include 'do', as it is
53       treated differently.
54
55       All compound statements have implicit ends. That is, they do not end
56       with a ';' statement terminator.
57
58   PPI::Statement::Break
59       A statement that breaks out of a structure.
60
61       This includes all of 'redo', 'next', 'last' and 'return' statements.
62
63   PPI::Statement::Given
64       The kind of statement introduced in Perl 5.10 that starts with 'given'.
65       This has an implicit end.
66
67   PPI::Statement::When
68       The kind of statement introduced in Perl 5.10 that starts with 'when'
69       or 'default'.  This also has an implicit end.
70
71   PPI::Statement::Data
72       A special statement which encompasses an entire "__DATA__" block,
73       including the initial '__DATA__' token itself and the entire contents.
74
75   PPI::Statement::End
76       A special statement which encompasses an entire __END__ block,
77       including the initial '__END__' token itself and the entire contents,
78       including any parsed PPI::Token::POD that may occur in it.
79
80   PPI::Statement::Expression
81       PPI::Statement::Expression is a little more speculative, and is
82       intended to help represent the special rules relating to "expressions"
83       such as in:
84
85         # Several examples of expression statements
86
87         # Boolean conditions
88         if ( expression ) { ... }
89
90         # Lists, such as for arguments
91         Foo->bar( expression )
92
93   PPI::Statement::Null
94       A null statement is a special case for where we encounter two
95       consecutive statement terminators. ( ;; )
96
97       The second terminator is given an entire statement of its own, but one
98       that serves no purpose. Hence a 'null' statement.
99
100       Theoretically, assuming a correct parsing of a perl file, all null
101       statements are superfluous and should be able to be removed without
102       damage to the file.
103
104       But don't do that, in case PPI has parsed something wrong.
105
106   PPI::Statement::UnmatchedBrace
107       Because PPI is intended for use when parsing incorrect or incomplete
108       code, the problem arises of what to do with a stray closing brace.
109
110       Rather than die, it is allocated its own "unmatched brace" statement,
111       which really means "unmatched closing brace". An unmatched open brace
112       at the end of a file would become a structure with no contents and no
113       closing brace.
114
115       If the document loaded is intended to be correct and valid, finding a
116       PPI::Statement::UnmatchedBrace in the PDOM is generally indicative of a
117       misparse.
118
119   PPI::Statement::Unknown
120       This is used temporarily mid-parsing to hold statements for which the
121       lexer cannot yet determine what class it should be, usually because
122       there are insufficient clues, or it might be more than one thing.
123
124       You should never encounter these in a fully parsed PDOM tree.
125

METHODS

127       "PPI::Statement" itself has very few methods. Most of the time, you
128       will be working with the more generic PPI::Element or PPI::Node
129       methods, or one of the methods that are subclass-specific.
130
131   label
132       One factor common to most statements is their ability to be labeled.
133
134       The "label" method returns the label for a statement, if one has been
135       defined, but without the trailing colon. Take the following example
136
137         MYLABEL: while ( 1 .. 10 ) { last MYLABEL if $_ > 5 }
138
139       For the above statement, the "label" method would return 'MYLABEL'.
140
141       Returns false if the statement does not have a label.
142
143   specialized
144       Answer whether this is a plain statement or one that has more
145       significance.
146
147       Returns true if the statement is a subclass of this one, false
148       otherwise.
149
150   stable
151       Much like the PPI::Document method of the same name, the ->stable
152       method converts a statement to source and back again, to determine if a
153       modified statement is still legal, and won't be interpreted in a
154       different way.
155
156       Returns true if the statement is stable, false if not, or "undef" on
157       error.
158

TO DO

160       - Complete, freeze and document the remaining classes
161

SUPPORT

163       See the support section in the main module.
164

AUTHOR

166       Adam Kennedy <adamk@cpan.org>
167

169       Copyright 2001 - 2011 Adam Kennedy.
170
171       This program is free software; you can redistribute it and/or modify it
172       under the same terms as Perl itself.
173
174       The full text of the license can be found in the LICENSE file included
175       with this module.
176
177
178
179perl v5.16.3                      2011-02-26                 PPI::Statement(3)
Impressum