local-lib5/man/man3/PPI::Statement::Sub.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::Sub 3"
 127 .TH PPI::Statement::Sub 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::Sub \- Subroutine declaration
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 4
 137 \&  PPI::Statement::Sub
 138 \&  isa PPI::Statement
 139 \&      isa PPI::Node
 140 \&          isa PPI::Element
 141 .Ve
 142 .SH "DESCRIPTION"
 143 .IX Header "DESCRIPTION"
 144 Except for the special \s-1BEGIN\s0, \s-1CHECK\s0, \s-1UNITCHECK\s0, \s-1INIT\s0, and \s-1END\s0 subroutines
 145 (which are part of PPI::Statement::Scheduled) all subroutine declarations
 146 are lexed as a PPI::Statement::Sub object.
 147 .PP
 148 Primarily, this means all of the various \f(CW\*(C`sub foo {}\*(C'\fR statements, but also
 149 forward declarations such as \f(CW\*(C`sub foo;\*(C'\fR or \f(CW\*(C`sub foo($);\*(C'\fR. It \fBdoes not\fR
 150 include anonymous subroutines, as these are merely part of a normal statement.
 151 .SH "METHODS"
 152 .IX Header "METHODS"
 153 \&\f(CW\*(C`PPI::Statement::Sub\*(C'\fR has a number of methods in addition to the standard
 154 PPI::Statement, PPI::Node and PPI::Element methods.
 155 .SS "name"
 156 .IX Subsection "name"
 157 The \f(CW\*(C`name\*(C'\fR method returns the name of the subroutine being declared.
 158 .PP
 159 In some rare cases such as a naked \f(CW\*(C`sub\*(C'\fR at the end of the file, this may return
 160 false.
 161 .SS "prototype"
 162 .IX Subsection "prototype"
 163 If it has one, the \f(CW\*(C`prototype\*(C'\fR method returns the subroutine's prototype.
 164 It is returned in the same format as \*(L"prototype\*(R" in PPI::Token::Prototype,
 165 cleaned and removed from its brackets.
 166 .PP
 167 Returns false if the subroutine does not define a prototype
 168 .SS "block"
 169 .IX Subsection "block"
 170 With its name and implementation shared with PPI::Statement::Scheduled,
 171 the \f(CW\*(C`block\*(C'\fR method finds and returns the actual Structure object of the
 172 code block for this subroutine.
 173 .PP
 174 Returns false if this is a forward declaration, or otherwise does not have a
 175 code block.
 176 .SS "forward"
 177 .IX Subsection "forward"
 178 The \f(CW\*(C`forward\*(C'\fR method returns true if the subroutine declaration is a
 179 forward declaration.
 180 .PP
 181 That is, it returns false if the subroutine has a code block, or true
 182 if it does not.
 183 .SS "reserved"
 184 .IX Subsection "reserved"
 185 The \f(CW\*(C`reserved\*(C'\fR method provides a convenience method for checking to see
 186 if this is a special reserved subroutine. It does not check against any
 187 particular list of reserved sub names, but just returns true if the name
 188 is all uppercase, as defined in perlsub.
 189 .PP
 190 Note that in the case of \s-1BEGIN\s0, \s-1CHECK\s0, \s-1UNITCHECK\s0, \s-1INIT\s0 and \s-1END\s0, these will be
 191 defined as PPI::Statement::Scheduled objects, not subroutines.
 192 .PP
 193 Returns true if it is a special reserved subroutine, or false if not.
 194 .SH "TO DO"
 195 .IX Header "TO DO"
 196 \&\- Write unit tests for this package
 197 .SH "SUPPORT"
 198 .IX Header "SUPPORT"
 199 See the support section in the main module.
 200 .SH "AUTHOR"
 201 .IX Header "AUTHOR"
 202 Adam Kennedy <adamk@cpan.org>
 203 .SH "COPYRIGHT"
 204 .IX Header "COPYRIGHT"
 205 Copyright 2001 \- 2009 Adam Kennedy.
 206 .PP
 207 This program is free software; you can redistribute
 208 it and/or modify it under the same terms as Perl itself.
 209 .PP
 210 The full text of the license can be found in the
 211 \&\s-1LICENSE\s0 file included with this module.