Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / PPI::Statement.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::Statement 3"
.TH PPI::Statement 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::Statement \- The base class for Perl statements
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 3
\&  PPI::Statement
\&  isa PPI::Node
\&      isa PPI::Element
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
PPI::Statement is the root class for all Perl statements. This includes (from
perlsyn) \*(L"Declarations\*(R", \*(L"Simple Statements\*(R" and \*(L"Compound Statements\*(R".
.PP
The class PPI::Statement itself represents a \*(L"Simple Statement\*(R" as defined
in the perlsyn manpage.
.SH "STATEMENT CLASSES"
.IX Header "STATEMENT CLASSES"
Please note that unless documented themselves, these classes are yet to be
frozen/finalised. Names may change slightly or be added or removed.
.SS "PPI::Statement::Scheduled"
.IX Subsection "PPI::Statement::Scheduled"
This covers all \*(L"scheduled\*(R" blocks, chunks of code that are executed separately
from the main body of the code, at a particular time. This includes all
\&\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.
.SS "PPI::Statement::Package"
.IX Subsection "PPI::Statement::Package"
A package declaration, as defined in perlfunc.
.SS "PPI::Statement::Include"
.IX Subsection "PPI::Statement::Include"
A statement that loads or unloads another module.
.PP
This includes 'use', 'no', and 'require' statements.
.SS "PPI::Statement::Sub"
.IX Subsection "PPI::Statement::Sub"
A named subroutine declaration, or forward declaration
.SS "PPI::Statement::Variable"
.IX Subsection "PPI::Statement::Variable"
A variable declaration statement. This could be either a straight
declaration or also be an expression.
.PP
This includes all 'my', 'state', 'local' and 'our' statements.
.SS "PPI::Statement::Compound"
.IX Subsection "PPI::Statement::Compound"
This covers the whole family of 'compound' statements, as described in
perlsyn.
.PP
This includes all statements starting with 'if', 'unless', 'for', 'foreach'
and 'while'. Note that this does \s-1NOT\s0 include 'do', as it is treated
differently.
.PP
All compound statements have implicit ends. That is, they do not end with
a ';' statement terminator.
.SS "PPI::Statement::Break"
.IX Subsection "PPI::Statement::Break"
A statement that breaks out of a structure.
.PP
This includes all of 'redo', 'next', 'last' and 'return' statements.
.SS "PPI::Statement::Given"
.IX Subsection "PPI::Statement::Given"
The kind of statement introduced in Perl 5.10 that starts with 'given'.  This
has an implicit end.
.SS "PPI::Statement::When"
.IX Subsection "PPI::Statement::When"
The kind of statement introduced in Perl 5.10 that starts with 'when' or
\&'default'.  This also has an implicit end.
.SS "PPI::Statement::Data"
.IX Subsection "PPI::Statement::Data"
A special statement which encompasses an entire \f(CW\*(C`_\|_DATA_\|_\*(C'\fR block, including
the initial \f(CW\*(Aq_\|_DATA_\|_\*(Aq\fR token itself and the entire contents.
.SS "PPI::Statement::End"
.IX Subsection "PPI::Statement::End"
A special statement which encompasses an entire _\|_END_\|_ block, including
the initial '_\|_END_\|_' token itself and the entire contents, including any
parsed PPI::Token::POD that may occur in it.
.SS "PPI::Statement::Expression"
.IX Subsection "PPI::Statement::Expression"
PPI::Statement::Expression is a little more speculative, and is intended
to help represent the special rules relating to \*(L"expressions\*(R" such as in:
.PP
.Vb 1
\&  # Several examples of expression statements
\&  
\&  # Boolean conditions
\&  if ( expression ) { ... }
\&  
\&  # Lists, such as for arguments
\&  Foo\->bar( expression )
.Ve
.SS "PPI::Statement::Null"
.IX Subsection "PPI::Statement::Null"
A null statement is a special case for where we encounter two consecutive
statement terminators. ( ;; )
.PP
The second terminator is given an entire statement of its own, but one
that serves no purpose. Hence a 'null' statement.
.PP
Theoretically, assuming a correct parsing of a perl file, all null statements
are superfluous and should be able to be removed without damage to the file.
.PP
But don't do that, in case \s-1PPI\s0 has parsed something wrong.
.SS "PPI::Statement::UnmatchedBrace"
.IX Subsection "PPI::Statement::UnmatchedBrace"
Because \s-1PPI\s0 is intended for use when parsing incorrect or incomplete code,
the problem arises of what to do with a stray closing brace.
.PP
Rather than die, it is allocated its own \*(L"unmatched brace\*(R" statement,
which really means \*(L"unmatched closing brace\*(R". An unmatched open brace at the
end of a file would become a structure with no contents and no closing brace.
.PP
If the document loaded is intended to be correct and valid, finding a
PPI::Statement::UnmatchedBrace in the \s-1PDOM\s0 is generally indicative of a
misparse.
.SS "PPI::Statement::Unknown"
.IX Subsection "PPI::Statement::Unknown"
This is used temporarily mid-parsing to hold statements for which the lexer
cannot yet determine what class it should be, usually because there are
insufficient clues, or it might be more than one thing.
.PP
You should never encounter these in a fully parsed \s-1PDOM\s0 tree.
.SH "METHODS"
.IX Header "METHODS"
\&\f(CW\*(C`PPI::Statement\*(C'\fR itself has very few methods. Most of the time, you will be
working with the more generic PPI::Element or PPI::Node methods, or one
of the methods that are subclass-specific.
.SS "label"
.IX Subsection "label"
One factor common to most statements is their ability to be labeled.
.PP
The \f(CW\*(C`label\*(C'\fR method returns the label for a statement, if one has been
defined, but without the trailing colon. Take the following example
.PP
.Vb 1
\&  MYLABEL: while ( 1 .. 10 ) { last MYLABEL if $_ > 5 }
.Ve
.PP
For the above statement, the \f(CW\*(C`label\*(C'\fR method would return '\s-1MYLABEL\s0'.
.PP
Returns false if the statement does not have a label.
.SS "specialized"
.IX Subsection "specialized"
Answer whether this is a plain statement or one that has more
significance.
.PP
Returns true if the statement is a subclass of this one, false
otherwise.
.SS "stable"
.IX Subsection "stable"
Much like the PPI::Document method of the same name, the \->stable
method converts a statement to source and back again, to determine if
a modified statement is still legal, and won't be interpreted in a
different way.
.PP
Returns true if the statement is stable, false if not, or \f(CW\*(C`undef\*(C'\fR on
error.
.SH "TO DO"
.IX Header "TO DO"
\&\- Complete, freeze and document the remaining classes
.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.