local-lib5/man/man3/PPI::Structure.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::Structure 3"
 127 .TH PPI::Structure 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::Structure \- The base class for Perl braced structures
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 3
 137 \&  PPI::Structure
 138 \&  isa PPI::Node
 139 \&      isa PPI::Element
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 PPI::Structure is the root class for all Perl bracing structures. This
 144 covers all forms of \f(CW\*(C` [ ... ] \*(C'\fR, \f(CW\*(C` { ... } \*(C'\fR, and \f(CW\*(C` ( ... ) \*(C'\fR brace
 145 types, and includes cases where only one half of the pair exist.
 146 .PP
 147 The class PPI::Structure itself is full abstract and no objects of that
 148 type should actually exist in the tree.
 149 .SS "Elements vs Children"
 150 .IX Subsection "Elements vs Children"
 151 A \fBPPI::Structure\fR has an unusual existance. Unlike a PPI::Document
 152 or PPI::Statement, which both simply contain other elements, a
 153 structure \fBboth\fR contains and consists of content.
 154 .PP
 155 That is, the brace tokens are \fBnot\fR considered to be \*(L"children\*(R" of the
 156 structure, but are part of it.
 157 .PP
 158 In practice, this will mean that while the \->elements and \->tokens
 159 methods (and related) \fBwill\fR return a list with the brace tokens at either
 160 end, the \->children method explicitly will \fBnot\fR return the brace.
 161 .SH "STRUCTURE CLASSES"
 162 .IX Header "STRUCTURE CLASSES"
 163 Excluding the transient PPI::Structure::Unknown that exists briefly
 164 inside the parser, there are eight types of structure.
 165 .SS "PPI::Structure::List"
 166 .IX Subsection "PPI::Structure::List"
 167 This covers all round braces used for function arguments, in \f(CW\*(C`foreach\*(C'\fR
 168 loops, literal lists, and braces used for precedence-ordering purposes.
 169 .SS "PPI::Structure::For"
 170 .IX Subsection "PPI::Structure::For"
 171 Although \fBnot\fR used for the \f(CW\*(C`foreach\*(C'\fR loop list, this \fBis\fR used for
 172 the special case of the round-brace three-part semicolon-seperated \f(CW\*(C`for\*(C'\fR
 173 loop expression (the traditional C style for loop).
 174 .SS "PPI::Structure::Given"
 175 .IX Subsection "PPI::Structure::Given"
 176 This is for the expression being matched in switch statements.
 177 .SS "PPI::Structure::When"
 178 .IX Subsection "PPI::Structure::When"
 179 This is for the matching expression in \*(L"when\*(R" statements.
 180 .SS "PPI::Structure::Condition"
 181 .IX Subsection "PPI::Structure::Condition"
 182 This round-brace structure covers boolean conditional braces, such as
 183 for \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`while\*(C'\fR blocks.
 184 .SS "PPI::Structure::Block"
 185 .IX Subsection "PPI::Structure::Block"
 186 This curly-brace and common structure is used for all form of code
 187 blocks. This includes those for \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`do\*(C'\fR and similar, as well
 188 as \f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, \f(CW\*(C`sub\*(C'\fR and (labelled or anonymous)
 189 scoping blocks.
 190 .SS "PPI::Structure::Constructor"
 191 .IX Subsection "PPI::Structure::Constructor"
 192 This class covers brace structures used for the construction of
 193 anonymous \f(CW\*(C`ARRAY\*(C'\fR and \f(CW\*(C`HASH\*(C'\fR references.
 194 .SS "PPI::Structure::Subscript"
 195 .IX Subsection "PPI::Structure::Subscript"
 196 This class covers square-braces and curly-braces used after a
 197 \&\-> pointer to access the subscript of an \f(CW\*(C`ARRAY\*(C'\fR or \f(CW\*(C`HASH\*(C'\fR.
 198 .SH "METHODS"
 199 .IX Header "METHODS"
 200 \&\f(CW\*(C`PPI::Structure\*(C'\fR itself has very few methods. Most of the time, you will be
 201 working with the more generic PPI::Element or PPI::Node methods, or one
 202 of the methods that are subclass-specific.
 203 .SS "start"
 204 .IX Subsection "start"
 205 For lack of better terminology (like \*(L"open\*(R" and \*(L"close\*(R") that has not
 206 already in use for some other more important purpose, the two individual
 207 braces for the structure are known within \s-1PPI\s0 as the \*(L"start\*(R" and \*(L"finish\*(R"
 208 braces (at least for method purposes).
 209 .PP
 210 The \f(CW\*(C`start\*(C'\fR method returns the start brace for the structure (i.e. the
 211 opening brace).
 212 .PP
 213 Returns the brace as a PPI::Token::Structure or \f(CW\*(C`undef\*(C'\fR if the
 214 structure does not have a starting brace.
 215 .PP
 216 Under normal parsing circumstances this should never occur, but may happen
 217 due to manipulation of the \s-1PDOM\s0 tree.
 218 .SS "finish"
 219 .IX Subsection "finish"
 220 The \f(CW\*(C`finish\*(C'\fR method returns the finish brace for the structure (i.e. the
 221 closing brace).
 222 .PP
 223 Returns the brace as a PPI::Token::Structure or \f(CW\*(C`undef\*(C'\fR if the
 224 structure does not have a starting brace. This can be quite common if
 225 the document is not complete (for example, from an editor where the user
 226 may be halfway through typeing a subroutine).
 227 .SS "braces"
 228 .IX Subsection "braces"
 229 The \f(CW\*(C`braces\*(C'\fR method is a utility method which returns the brace type,
 230 regardless of whether has both braces defined, or just the starting
 231 brace, or just the ending brace.
 232 .PP
 233 Returns on of the three strings \f(CW\*(Aq[]\*(Aq\fR, \f(CW\*(Aq{}\*(Aq\fR, or \f(CW\*(Aq()\*(Aq\fR, or \f(CW\*(C`undef\*(C'\fR
 234 on error (primarily not having a start brace, as mentioned above).
 235 .SH "complete"
 236 .IX Header "complete"
 237 The \f(CW\*(C`complete\*(C'\fR method is a convenience method that returns true if
 238 the both braces are defined for the structure, or false if only one
 239 brace is defined.
 240 .PP
 241 Unlike the top level \f(CW\*(C`complete\*(C'\fR method which checks for completeness
 242 in depth, the structure complete method \s-1ONLY\s0 confirms completeness
 243 for the braces, and does not recurse downwards.
 244 .SH "SUPPORT"
 245 .IX Header "SUPPORT"
 246 See the support section in the main module.
 247 .SH "AUTHOR"
 248 .IX Header "AUTHOR"
 249 Adam Kennedy <adamk@cpan.org>
 250 .SH "COPYRIGHT"
 251 .IX Header "COPYRIGHT"
 252 Copyright 2001 \- 2009 Adam Kennedy.
 253 .PP
 254 This program is free software; you can redistribute
 255 it and/or modify it under the same terms as Perl itself.
 256 .PP
 257 The full text of the license can be found in the
 258 \&\s-1LICENSE\s0 file included with this module.