1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
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<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
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.
53 . tm Index:\\$1\t\\n%\t"\\$2"
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
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
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'
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 \
124 .\" ========================================================================
126 .IX Title "PPI::Statement::Include 3"
127 .TH PPI::Statement::Include 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.
133 PPI::Statement::Include \- Statements that include other code
135 .IX Header "SYNOPSIS"
137 \& # The following are all includes
141 \& use constant FOO => \*(AqFoo\*(Aq;
143 \& require "Foo/Bar.pm";
144 \& require $foo if 1;
145 \& no strict \*(Aqrefs\*(Aq;
148 .IX Header "INHERITANCE"
150 \& PPI::Statement::Include
151 \& isa PPI::Statement
156 .IX Header "DESCRIPTION"
157 Despite its name, the \f(CW\*(C`PPI::Statement::Include\*(C'\fR class covers a number
158 of different types of statement that cover all statements starting with
159 \&\f(CW\*(C`use\*(C'\fR, \f(CW\*(C`no\*(C'\fR and \f(CW\*(C`require\*(C'\fR.
161 But basically, they cover three situations.
163 Firstly, a dependency on a particular version of perl (for which the
164 \&\f(CW\*(C`version\*(C'\fR method returns true), a pragma (for which the \f(CW\*(C`pragma\*(C'\fR method
165 returns true, or the loading (and unloading via no) of modules.
168 \&\f(CW\*(C`PPI::Statement::Include\*(C'\fR has a number of methods in addition to the standard
169 PPI::Statement, PPI::Node and PPI::Element methods.
171 .IX Subsection "type"
172 The \f(CW\*(C`type\*(C'\fR method returns the general type of statement (\f(CW\*(Aquse\*(Aq\fR, \f(CW\*(Aqno\*(Aq\fR
173 or \f(CW\*(Aqrequire\*(Aq\fR).
175 Returns the type as a string, or \f(CW\*(C`undef\*(C'\fR if the type cannot be detected.
177 .IX Subsection "module"
178 The \f(CW\*(C`module\*(C'\fR method returns the module name specified in any include
179 statement. This \f(CW\*(C`includes\*(C'\fR pragma names, because pragma are implemented
180 as modules. (And lets face it, the definition of a pragma can be fuzzy
181 at the best of times in any case)
183 This covers all of these...
189 \& require My::Module;
192 \&...but does not cover any of these...
197 \& require "explicit/file/name.pl";
200 Returns the module name as a string, or \f(CW\*(C`undef\*(C'\fR if the include does
201 not specify a module name.
203 .IX Subsection "module_version"
204 The \f(CW\*(C`module_version\*(C'\fR method returns the minimum version of the module
205 required by the statement, if there is one.
207 .IX Subsection "pragma"
208 The \f(CW\*(C`pragma\*(C'\fR method checks for an include statement's use as a
209 pragma, and returns it if so.
211 Or at least, it claims to. In practice it's a lot harder to say exactly
212 what is or isn't a pragma, because the definition is fuzzy.
214 The \f(CW\*(C`intent\*(C'\fR of a pragma is to modify the way in which the parser works.
215 This is done though the use of modules that do various types of internals
218 For now, \s-1PPI\s0 assumes that any \*(L"module name\*(R" that is only a set of
219 lowercase letters (and perhaps numbers, like \f(CW\*(C`use utf8;\*(C'\fR). This
220 behaviour is expected to change, most likely to something that knows
221 the specific names of the various \*(L"pragmas\*(R".
223 Returns the name of the pragma, or false ('') if the include is not a
226 .IX Subsection "version"
227 The \f(CW\*(C`version\*(C'\fR method checks for an include statement that introduces a
228 dependency on the version of \f(CW\*(C`perl\*(C'\fR the code is compatible with.
230 This covers two specific statements.
237 Currently the version is returned as a string, although in future the version
238 may be returned as a version object. If you want a numeric representation,
239 use \f(CW\*(C`version_literal()\*(C'\fR. Returns false if the statement is not a version
241 .SS "version_literal"
242 .IX Subsection "version_literal"
243 The \f(CW\*(C`version_literal\*(C'\fR method has the same behavior as \f(CW\*(C`version()\*(C'\fR, but the
244 version is returned as a numeric literal. Returns false if the statement is
245 not a version dependency.
247 The \f(CW\*(C`arguments\*(C'\fR method gives you the rest of the statement after the the
248 module/pragma and module version, i.e. the stuff that will be used to
249 construct what gets passed to the module's \f(CW\*(C`import()\*(C'\fR subroutine. This does
250 include the comma, etc. operators, but doesn't include non-significant direct
251 children or any final semicolon.
254 \&\- Write specific unit tests for this package
257 See the support section in the main module.
260 Adam Kennedy <adamk@cpan.org>
262 .IX Header "COPYRIGHT"
263 Copyright 2001 \- 2009 Adam Kennedy.
265 This program is free software; you can redistribute
266 it and/or modify it under the same terms as Perl itself.
268 The full text of the license can be found in the
269 \&\s-1LICENSE\s0 file included with this module.