Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLMOD 1" | |
132 | .TH PERLMOD 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlmod \- Perl modules (packages and symbol tables) | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | .Sh "Packages" | |
138 | .IX Xref "package namespace variable, global global variable global" | |
139 | .IX Subsection "Packages" | |
140 | Perl provides a mechanism for alternative namespaces to protect | |
141 | packages from stomping on each other's variables. In fact, there's | |
142 | really no such thing as a global variable in Perl. The package | |
143 | statement declares the compilation unit as being in the given | |
144 | namespace. The scope of the package declaration is from the | |
145 | declaration itself through the end of the enclosing block, \f(CW\*(C`eval\*(C'\fR, | |
146 | or file, whichever comes first (the same scope as the \fImy()\fR and | |
147 | \&\fIlocal()\fR operators). Unqualified dynamic identifiers will be in | |
148 | this namespace, except for those few identifiers that if unqualified, | |
149 | default to the main package instead of the current one as described | |
150 | below. A package statement affects only dynamic variables\*(--including | |
151 | those you've used \fIlocal()\fR on\*(--but \fInot\fR lexical variables created | |
152 | with \fImy()\fR. Typically it would be the first declaration in a file | |
153 | included by the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators. You can | |
154 | switch into a package in more than one place; it merely influences | |
155 | which symbol table is used by the compiler for the rest of that | |
156 | block. You can refer to variables and filehandles in other packages | |
157 | by prefixing the identifier with the package name and a double | |
158 | colon: \f(CW$Package::Variable\fR. If the package name is null, the | |
159 | \&\f(CW\*(C`main\*(C'\fR package is assumed. That is, \f(CW$::sail\fR is equivalent to | |
160 | \&\f(CW$main::sail\fR. | |
161 | .PP | |
162 | The old package delimiter was a single quote, but double colon is now the | |
163 | preferred delimiter, in part because it's more readable to humans, and | |
164 | in part because it's more readable to \fBemacs\fR macros. It also makes \*(C+ | |
165 | programmers feel like they know what's going on\*(--as opposed to using the | |
166 | single quote as separator, which was there to make Ada programmers feel | |
167 | like they knew what was going on. Because the old-fashioned syntax is still | |
168 | supported for backwards compatibility, if you try to use a string like | |
169 | \&\f(CW"This is $owner's house"\fR, you'll be accessing \f(CW$owner::s\fR; that is, | |
170 | the \f(CW$s\fR variable in package \f(CW\*(C`owner\*(C'\fR, which is probably not what you meant. | |
171 | Use braces to disambiguate, as in \f(CW"This is ${owner}'s house"\fR. | |
172 | .IX Xref ":: '" | |
173 | .PP | |
174 | Packages may themselves contain package separators, as in | |
175 | \&\f(CW$OUTER::INNER::var\fR. This implies nothing about the order of | |
176 | name lookups, however. There are no relative packages: all symbols | |
177 | are either local to the current package, or must be fully qualified | |
178 | from the outer package name down. For instance, there is nowhere | |
179 | within package \f(CW\*(C`OUTER\*(C'\fR that \f(CW$INNER::var\fR refers to | |
180 | \&\f(CW$OUTER::INNER::var\fR. \f(CW\*(C`INNER\*(C'\fR refers to a totally | |
181 | separate global package. | |
182 | .PP | |
183 | Only identifiers starting with letters (or underscore) are stored | |
184 | in a package's symbol table. All other symbols are kept in package | |
185 | \&\f(CW\*(C`main\*(C'\fR, including all punctuation variables, like \f(CW$_\fR. In addition, | |
186 | when unqualified, the identifiers \s-1STDIN\s0, \s-1STDOUT\s0, \s-1STDERR\s0, \s-1ARGV\s0, | |
187 | \&\s-1ARGVOUT\s0, \s-1ENV\s0, \s-1INC\s0, and \s-1SIG\s0 are forced to be in package \f(CW\*(C`main\*(C'\fR, | |
188 | even when used for other purposes than their built-in ones. If you | |
189 | have a package called \f(CW\*(C`m\*(C'\fR, \f(CW\*(C`s\*(C'\fR, or \f(CW\*(C`y\*(C'\fR, then you can't use the | |
190 | qualified form of an identifier because it would be instead interpreted | |
191 | as a pattern match, a substitution, or a transliteration. | |
192 | .IX Xref "variable, punctuation" | |
193 | .PP | |
194 | Variables beginning with underscore used to be forced into package | |
195 | main, but we decided it was more useful for package writers to be able | |
196 | to use leading underscore to indicate private variables and method names. | |
197 | However, variables and functions named with a single \f(CW\*(C`_\*(C'\fR, such as | |
198 | \&\f(CW$_\fR and \f(CW\*(C`sub _\*(C'\fR, are still forced into the package \f(CW\*(C`main\*(C'\fR. See also | |
199 | \&\*(L"Technical Note on the Syntax of Variable Names\*(R" in perlvar. | |
200 | .PP | |
201 | \&\f(CW\*(C`eval\*(C'\fRed strings are compiled in the package in which the \fIeval()\fR was | |
202 | compiled. (Assignments to \f(CW$SIG{}\fR, however, assume the signal | |
203 | handler specified is in the \f(CW\*(C`main\*(C'\fR package. Qualify the signal handler | |
204 | name if you wish to have a signal handler in a package.) For an | |
205 | example, examine \fIperldb.pl\fR in the Perl library. It initially switches | |
206 | to the \f(CW\*(C`DB\*(C'\fR package so that the debugger doesn't interfere with variables | |
207 | in the program you are trying to debug. At various points, however, it | |
208 | temporarily switches back to the \f(CW\*(C`main\*(C'\fR package to evaluate various | |
209 | expressions in the context of the \f(CW\*(C`main\*(C'\fR package (or wherever you came | |
210 | from). See perldebug. | |
211 | .PP | |
212 | The special symbol \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR contains the current package, but cannot | |
213 | (easily) be used to construct variable names. | |
214 | .PP | |
215 | See perlsub for other scoping issues related to \fImy()\fR and \fIlocal()\fR, | |
216 | and perlref regarding closures. | |
217 | .Sh "Symbol Tables" | |
218 | .IX Xref "symbol table stash %:: %main:: typeglob glob alias" | |
219 | .IX Subsection "Symbol Tables" | |
220 | The symbol table for a package happens to be stored in the hash of that | |
221 | name with two colons appended. The main symbol table's name is thus | |
222 | \&\f(CW%main::\fR, or \f(CW%::\fR for short. Likewise the symbol table for the nested | |
223 | package mentioned earlier is named \f(CW%OUTER::INNER::\fR. | |
224 | .PP | |
225 | The value in each entry of the hash is what you are referring to when you | |
226 | use the \f(CW*name\fR typeglob notation. In fact, the following have the same | |
227 | effect, though the first is more efficient because it does the symbol | |
228 | table lookups at compile time: | |
229 | .PP | |
230 | .Vb 2 | |
231 | \& local *main::foo = *main::bar; | |
232 | \& local $main::{foo} = $main::{bar}; | |
233 | .Ve | |
234 | .PP | |
235 | (Be sure to note the \fBvast\fR difference between the second line above | |
236 | and \f(CW\*(C`local $main::foo = $main::bar\*(C'\fR. The former is accessing the hash | |
237 | \&\f(CW%main::\fR, which is the symbol table of package \f(CW\*(C`main\*(C'\fR. The latter is | |
238 | simply assigning scalar \f(CW$bar\fR in package \f(CW\*(C`main\*(C'\fR to scalar \f(CW$foo\fR of | |
239 | the same package.) | |
240 | .PP | |
241 | You can use this to print out all the variables in a package, for | |
242 | instance. The standard but antiquated \fIdumpvar.pl\fR library and | |
243 | the \s-1CPAN\s0 module Devel::Symdump make use of this. | |
244 | .PP | |
245 | Assignment to a typeglob performs an aliasing operation, i.e., | |
246 | .PP | |
247 | .Vb 1 | |
248 | \& *dick = *richard; | |
249 | .Ve | |
250 | .PP | |
251 | causes variables, subroutines, formats, and file and directory handles | |
252 | accessible via the identifier \f(CW\*(C`richard\*(C'\fR also to be accessible via the | |
253 | identifier \f(CW\*(C`dick\*(C'\fR. If you want to alias only a particular variable or | |
254 | subroutine, assign a reference instead: | |
255 | .PP | |
256 | .Vb 1 | |
257 | \& *dick = \e$richard; | |
258 | .Ve | |
259 | .PP | |
260 | Which makes \f(CW$richard\fR and \f(CW$dick\fR the same variable, but leaves | |
261 | \&\f(CW@richard\fR and \f(CW@dick\fR as separate arrays. Tricky, eh? | |
262 | .PP | |
263 | There is one subtle difference between the following statements: | |
264 | .PP | |
265 | .Vb 2 | |
266 | \& *foo = *bar; | |
267 | \& *foo = \e$bar; | |
268 | .Ve | |
269 | .PP | |
270 | \&\f(CW\*(C`*foo = *bar\*(C'\fR makes the typeglobs themselves synonymous while | |
271 | \&\f(CW\*(C`*foo = \e$bar\*(C'\fR makes the \s-1SCALAR\s0 portions of two distinct typeglobs | |
272 | refer to the same scalar value. This means that the following code: | |
273 | .PP | |
274 | .Vb 2 | |
275 | \& $bar = 1; | |
276 | \& *foo = \e$bar; # Make $foo an alias for $bar | |
277 | .Ve | |
278 | .PP | |
279 | .Vb 4 | |
280 | \& { | |
281 | \& local $bar = 2; # Restrict changes to block | |
282 | \& print $foo; # Prints '1'! | |
283 | \& } | |
284 | .Ve | |
285 | .PP | |
286 | Would print '1', because \f(CW$foo\fR holds a reference to the \fIoriginal\fR | |
287 | \&\f(CW$bar\fR \*(-- the one that was stuffed away by \f(CW\*(C`local()\*(C'\fR and which will be | |
288 | restored when the block ends. Because variables are accessed through the | |
289 | typeglob, you can use \f(CW\*(C`*foo = *bar\*(C'\fR to create an alias which can be | |
290 | localized. (But be aware that this means you can't have a separate | |
291 | \&\f(CW@foo\fR and \f(CW@bar\fR, etc.) | |
292 | .PP | |
293 | What makes all of this important is that the Exporter module uses glob | |
294 | aliasing as the import/export mechanism. Whether or not you can properly | |
295 | localize a variable that has been exported from a module depends on how | |
296 | it was exported: | |
297 | .PP | |
298 | .Vb 2 | |
299 | \& @EXPORT = qw($FOO); # Usual form, can't be localized | |
300 | \& @EXPORT = qw(*FOO); # Can be localized | |
301 | .Ve | |
302 | .PP | |
303 | You can work around the first case by using the fully qualified name | |
304 | (\f(CW$Package::FOO\fR) where you need a local value, or by overriding it | |
305 | by saying \f(CW\*(C`*FOO = *Package::FOO\*(C'\fR in your script. | |
306 | .PP | |
307 | The \f(CW\*(C`*x = \e$y\*(C'\fR mechanism may be used to pass and return cheap references | |
308 | into or from subroutines if you don't want to copy the whole | |
309 | thing. It only works when assigning to dynamic variables, not | |
310 | lexicals. | |
311 | .PP | |
312 | .Vb 9 | |
313 | \& %some_hash = (); # can't be my() | |
314 | \& *some_hash = fn( \e%another_hash ); | |
315 | \& sub fn { | |
316 | \& local *hashsym = shift; | |
317 | \& # now use %hashsym normally, and you | |
318 | \& # will affect the caller's %another_hash | |
319 | \& my %nhash = (); # do what you want | |
320 | \& return \e%nhash; | |
321 | \& } | |
322 | .Ve | |
323 | .PP | |
324 | On return, the reference will overwrite the hash slot in the | |
325 | symbol table specified by the *some_hash typeglob. This | |
326 | is a somewhat tricky way of passing around references cheaply | |
327 | when you don't want to have to remember to dereference variables | |
328 | explicitly. | |
329 | .PP | |
330 | Another use of symbol tables is for making \*(L"constant\*(R" scalars. | |
331 | .IX Xref "constant scalar, constant" | |
332 | .PP | |
333 | .Vb 1 | |
334 | \& *PI = \e3.14159265358979; | |
335 | .Ve | |
336 | .PP | |
337 | Now you cannot alter \f(CW$PI\fR, which is probably a good thing all in all. | |
338 | This isn't the same as a constant subroutine, which is subject to | |
339 | optimization at compile\-time. A constant subroutine is one prototyped | |
340 | to take no arguments and to return a constant expression. See | |
341 | perlsub for details on these. The \f(CW\*(C`use constant\*(C'\fR pragma is a | |
342 | convenient shorthand for these. | |
343 | .PP | |
344 | You can say \f(CW*foo{PACKAGE}\fR and \f(CW*foo{NAME}\fR to find out what name and | |
345 | package the *foo symbol table entry comes from. This may be useful | |
346 | in a subroutine that gets passed typeglobs as arguments: | |
347 | .PP | |
348 | .Vb 6 | |
349 | \& sub identify_typeglob { | |
350 | \& my $glob = shift; | |
351 | \& print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\en"; | |
352 | \& } | |
353 | \& identify_typeglob *foo; | |
354 | \& identify_typeglob *bar::baz; | |
355 | .Ve | |
356 | .PP | |
357 | This prints | |
358 | .PP | |
359 | .Vb 2 | |
360 | \& You gave me main::foo | |
361 | \& You gave me bar::baz | |
362 | .Ve | |
363 | .PP | |
364 | The \f(CW*foo{THING}\fR notation can also be used to obtain references to the | |
365 | individual elements of *foo. See perlref. | |
366 | .PP | |
367 | Subroutine definitions (and declarations, for that matter) need | |
368 | not necessarily be situated in the package whose symbol table they | |
369 | occupy. You can define a subroutine outside its package by | |
370 | explicitly qualifying the name of the subroutine: | |
371 | .PP | |
372 | .Vb 2 | |
373 | \& package main; | |
374 | \& sub Some_package::foo { ... } # &foo defined in Some_package | |
375 | .Ve | |
376 | .PP | |
377 | This is just a shorthand for a typeglob assignment at compile time: | |
378 | .PP | |
379 | .Vb 1 | |
380 | \& BEGIN { *Some_package::foo = sub { ... } } | |
381 | .Ve | |
382 | .PP | |
383 | and is \fInot\fR the same as writing: | |
384 | .PP | |
385 | .Vb 4 | |
386 | \& { | |
387 | \& package Some_package; | |
388 | \& sub foo { ... } | |
389 | \& } | |
390 | .Ve | |
391 | .PP | |
392 | In the first two versions, the body of the subroutine is | |
393 | lexically in the main package, \fInot\fR in Some_package. So | |
394 | something like this: | |
395 | .PP | |
396 | .Vb 1 | |
397 | \& package main; | |
398 | .Ve | |
399 | .PP | |
400 | .Vb 2 | |
401 | \& $Some_package::name = "fred"; | |
402 | \& $main::name = "barney"; | |
403 | .Ve | |
404 | .PP | |
405 | .Vb 3 | |
406 | \& sub Some_package::foo { | |
407 | \& print "in ", __PACKAGE__, ": \e$name is '$name'\en"; | |
408 | \& } | |
409 | .Ve | |
410 | .PP | |
411 | .Vb 1 | |
412 | \& Some_package::foo(); | |
413 | .Ve | |
414 | .PP | |
415 | prints: | |
416 | .PP | |
417 | .Vb 1 | |
418 | \& in main: $name is 'barney' | |
419 | .Ve | |
420 | .PP | |
421 | rather than: | |
422 | .PP | |
423 | .Vb 1 | |
424 | \& in Some_package: $name is 'fred' | |
425 | .Ve | |
426 | .PP | |
427 | This also has implications for the use of the \s-1SUPER::\s0 qualifier | |
428 | (see perlobj). | |
429 | .Sh "\s-1BEGIN\s0, \s-1CHECK\s0, \s-1INIT\s0 and \s-1END\s0" | |
430 | .IX Xref "BEGIN CHECK INIT END" | |
431 | .IX Subsection "BEGIN, CHECK, INIT and END" | |
432 | Four specially named code blocks are executed at the beginning and at the end | |
433 | of a running Perl program. These are the \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, and | |
434 | \&\f(CW\*(C`END\*(C'\fR blocks. | |
435 | .PP | |
436 | These code blocks can be prefixed with \f(CW\*(C`sub\*(C'\fR to give the appearance of a | |
437 | subroutine (although this is not considered good style). One should note | |
438 | that these code blocks don't really exist as named subroutines (despite | |
439 | their appearance). The thing that gives this away is the fact that you can | |
440 | have \fBmore than one\fR of these code blocks in a program, and they will get | |
441 | \&\fBall\fR executed at the appropriate moment. So you can't execute any of | |
442 | these code blocks by name. | |
443 | .PP | |
444 | A \f(CW\*(C`BEGIN\*(C'\fR code block is executed as soon as possible, that is, the moment | |
445 | it is completely defined, even before the rest of the containing file (or | |
446 | string) is parsed. You may have multiple \f(CW\*(C`BEGIN\*(C'\fR blocks within a file (or | |
447 | eval'ed string) \*(-- they will execute in order of definition. Because a \f(CW\*(C`BEGIN\*(C'\fR | |
448 | code block executes immediately, it can pull in definitions of subroutines | |
449 | and such from other files in time to be visible to the rest of the compile | |
450 | and run time. Once a \f(CW\*(C`BEGIN\*(C'\fR has run, it is immediately undefined and any | |
451 | code it used is returned to Perl's memory pool. | |
452 | .PP | |
453 | It should be noted that \f(CW\*(C`BEGIN\*(C'\fR code blocks \fBare\fR executed inside string | |
454 | \&\f(CW\*(C`eval()\*(C'\fR's. The \f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR code blocks are \fBnot\fR executed inside | |
455 | a string eval, which e.g. can be a problem in a mod_perl environment. | |
456 | .PP | |
457 | An \f(CW\*(C`END\*(C'\fR code block is executed as late as possible, that is, after | |
458 | perl has finished running the program and just before the interpreter | |
459 | is being exited, even if it is exiting as a result of a \fIdie()\fR function. | |
460 | (But not if it's morphing into another program via \f(CW\*(C`exec\*(C'\fR, or | |
461 | being blown out of the water by a signal\*(--you have to trap that yourself | |
462 | (if you can).) You may have multiple \f(CW\*(C`END\*(C'\fR blocks within a file\*(--they | |
463 | will execute in reverse order of definition; that is: last in, first | |
464 | out (\s-1LIFO\s0). \f(CW\*(C`END\*(C'\fR blocks are not executed when you run perl with the | |
465 | \&\f(CW\*(C`\-c\*(C'\fR switch, or if compilation fails. | |
466 | .PP | |
467 | Note that \f(CW\*(C`END\*(C'\fR code blocks are \fBnot\fR executed at the end of a string | |
468 | \&\f(CW\*(C`eval()\*(C'\fR: if any \f(CW\*(C`END\*(C'\fR code blocks are created in a string \f(CW\*(C`eval()\*(C'\fR, | |
469 | they will be executed just as any other \f(CW\*(C`END\*(C'\fR code block of that package | |
470 | in \s-1LIFO\s0 order just before the interpreter is being exited. | |
471 | .PP | |
472 | Inside an \f(CW\*(C`END\*(C'\fR code block, \f(CW$?\fR contains the value that the program is | |
473 | going to pass to \f(CW\*(C`exit()\*(C'\fR. You can modify \f(CW$?\fR to change the exit | |
474 | value of the program. Beware of changing \f(CW$?\fR by accident (e.g. by | |
475 | running something via \f(CW\*(C`system\*(C'\fR). | |
476 | .IX Xref "$?" | |
477 | .PP | |
478 | \&\f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR code blocks are useful to catch the transition between | |
479 | the compilation phase and the execution phase of the main program. | |
480 | .PP | |
481 | \&\f(CW\*(C`CHECK\*(C'\fR code blocks are run just after the \fBinitial\fR Perl compile phase ends | |
482 | and before the run time begins, in \s-1LIFO\s0 order. \f(CW\*(C`CHECK\*(C'\fR code blocks are used | |
483 | in the Perl compiler suite to save the compiled state of the program. | |
484 | .PP | |
485 | \&\f(CW\*(C`INIT\*(C'\fR blocks are run just before the Perl runtime begins execution, in | |
486 | \&\*(L"first in, first out\*(R" (\s-1FIFO\s0) order. For example, the code generators | |
487 | documented in perlcc make use of \f(CW\*(C`INIT\*(C'\fR blocks to initialize and | |
488 | resolve pointers to XSUBs. | |
489 | .PP | |
490 | When you use the \fB\-n\fR and \fB\-p\fR switches to Perl, \f(CW\*(C`BEGIN\*(C'\fR and | |
491 | \&\f(CW\*(C`END\*(C'\fR work just as they do in \fBawk\fR, as a degenerate case. | |
492 | Both \f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`CHECK\*(C'\fR blocks are run when you use the \fB\-c\fR | |
493 | switch for a compile-only syntax check, although your main code | |
494 | is not. | |
495 | .PP | |
496 | The \fBbegincheck\fR program makes it all clear, eventually: | |
497 | .PP | |
498 | .Vb 1 | |
499 | \& #!/usr/bin/perl | |
500 | .Ve | |
501 | .PP | |
502 | .Vb 1 | |
503 | \& # begincheck | |
504 | .Ve | |
505 | .PP | |
506 | .Vb 1 | |
507 | \& print " 8. Ordinary code runs at runtime.\en"; | |
508 | .Ve | |
509 | .PP | |
510 | .Vb 3 | |
511 | \& END { print "14. So this is the end of the tale.\en" } | |
512 | \& INIT { print " 5. INIT blocks run FIFO just before runtime.\en" } | |
513 | \& CHECK { print " 4. So this is the fourth line.\en" } | |
514 | .Ve | |
515 | .PP | |
516 | .Vb 1 | |
517 | \& print " 9. It runs in order, of course.\en"; | |
518 | .Ve | |
519 | .PP | |
520 | .Vb 4 | |
521 | \& BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\en" } | |
522 | \& END { print "13. Read perlmod for the rest of the story.\en" } | |
523 | \& CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\en" } | |
524 | \& INIT { print " 6. Run this again, using Perl's -c switch.\en" } | |
525 | .Ve | |
526 | .PP | |
527 | .Vb 1 | |
528 | \& print "10. This is anti-obfuscated code.\en"; | |
529 | .Ve | |
530 | .PP | |
531 | .Vb 3 | |
532 | \& END { print "12. END blocks run LIFO at quitting time.\en" } | |
533 | \& BEGIN { print " 2. So this line comes out second.\en" } | |
534 | \& INIT { print " 7. You'll see the difference right away.\en" } | |
535 | .Ve | |
536 | .PP | |
537 | .Vb 1 | |
538 | \& print "11. It merely _looks_ like it should be confusing.\en"; | |
539 | .Ve | |
540 | .PP | |
541 | .Vb 1 | |
542 | \& __END__ | |
543 | .Ve | |
544 | .Sh "Perl Classes" | |
545 | .IX Xref "class @ISA" | |
546 | .IX Subsection "Perl Classes" | |
547 | There is no special class syntax in Perl, but a package may act | |
548 | as a class if it provides subroutines to act as methods. Such a | |
549 | package may also derive some of its methods from another class (package) | |
550 | by listing the other package name(s) in its global \f(CW@ISA\fR array (which | |
551 | must be a package global, not a lexical). | |
552 | .PP | |
553 | For more on this, see perltoot and perlobj. | |
554 | .Sh "Perl Modules" | |
555 | .IX Xref "module" | |
556 | .IX Subsection "Perl Modules" | |
557 | A module is just a set of related functions in a library file, i.e., | |
558 | a Perl package with the same name as the file. It is specifically | |
559 | designed to be reusable by other modules or programs. It may do this | |
560 | by providing a mechanism for exporting some of its symbols into the | |
561 | symbol table of any package using it, or it may function as a class | |
562 | definition and make its semantics available implicitly through | |
563 | method calls on the class and its objects, without explicitly | |
564 | exporting anything. Or it can do a little of both. | |
565 | .PP | |
566 | For example, to start a traditional, non-OO module called Some::Module, | |
567 | create a file called \fISome/Module.pm\fR and start with this template: | |
568 | .PP | |
569 | .Vb 1 | |
570 | \& package Some::Module; # assumes Some/Module.pm | |
571 | .Ve | |
572 | .PP | |
573 | .Vb 2 | |
574 | \& use strict; | |
575 | \& use warnings; | |
576 | .Ve | |
577 | .PP | |
578 | .Vb 3 | |
579 | \& BEGIN { | |
580 | \& use Exporter (); | |
581 | \& our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); | |
582 | .Ve | |
583 | .PP | |
584 | .Vb 4 | |
585 | \& # set the version for version checking | |
586 | \& $VERSION = 1.00; | |
587 | \& # if using RCS/CVS, this may be preferred | |
588 | \& $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\ed+)/g; | |
589 | .Ve | |
590 | .PP | |
591 | .Vb 3 | |
592 | \& @ISA = qw(Exporter); | |
593 | \& @EXPORT = qw(&func1 &func2 &func4); | |
594 | \& %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], | |
595 | .Ve | |
596 | .PP | |
597 | .Vb 5 | |
598 | \& # your exported package globals go here, | |
599 | \& # as well as any optionally exported functions | |
600 | \& @EXPORT_OK = qw($Var1 %Hashit &func3); | |
601 | \& } | |
602 | \& our @EXPORT_OK; | |
603 | .Ve | |
604 | .PP | |
605 | .Vb 3 | |
606 | \& # exported package globals go here | |
607 | \& our $Var1; | |
608 | \& our %Hashit; | |
609 | .Ve | |
610 | .PP | |
611 | .Vb 3 | |
612 | \& # non-exported package globals go here | |
613 | \& our @more; | |
614 | \& our $stuff; | |
615 | .Ve | |
616 | .PP | |
617 | .Vb 3 | |
618 | \& # initialize package globals, first exported ones | |
619 | \& $Var1 = ''; | |
620 | \& %Hashit = (); | |
621 | .Ve | |
622 | .PP | |
623 | .Vb 3 | |
624 | \& # then the others (which are still accessible as $Some::Module::stuff) | |
625 | \& $stuff = ''; | |
626 | \& @more = (); | |
627 | .Ve | |
628 | .PP | |
629 | .Vb 2 | |
630 | \& # all file-scoped lexicals must be created before | |
631 | \& # the functions below that use them. | |
632 | .Ve | |
633 | .PP | |
634 | .Vb 3 | |
635 | \& # file-private lexicals go here | |
636 | \& my $priv_var = ''; | |
637 | \& my %secret_hash = (); | |
638 | .Ve | |
639 | .PP | |
640 | .Vb 5 | |
641 | \& # here's a file-private function as a closure, | |
642 | \& # callable as &$priv_func; it cannot be prototyped. | |
643 | \& my $priv_func = sub { | |
644 | \& # stuff goes here. | |
645 | \& }; | |
646 | .Ve | |
647 | .PP | |
648 | .Vb 5 | |
649 | \& # make all your functions, whether exported or not; | |
650 | \& # remember to put something interesting in the {} stubs | |
651 | \& sub func1 {} # no prototype | |
652 | \& sub func2() {} # proto'd void | |
653 | \& sub func3($$) {} # proto'd to 2 scalars | |
654 | .Ve | |
655 | .PP | |
656 | .Vb 2 | |
657 | \& # this one isn't exported, but could be called! | |
658 | \& sub func4(\e%) {} # proto'd to 1 hash ref | |
659 | .Ve | |
660 | .PP | |
661 | .Vb 1 | |
662 | \& END { } # module clean-up code here (global destructor) | |
663 | .Ve | |
664 | .PP | |
665 | .Vb 1 | |
666 | \& ## YOUR CODE GOES HERE | |
667 | .Ve | |
668 | .PP | |
669 | .Vb 1 | |
670 | \& 1; # don't forget to return a true value from the file | |
671 | .Ve | |
672 | .PP | |
673 | Then go on to declare and use your variables in functions without | |
674 | any qualifications. See Exporter and the perlmodlib for | |
675 | details on mechanics and style issues in module creation. | |
676 | .PP | |
677 | Perl modules are included into your program by saying | |
678 | .PP | |
679 | .Vb 1 | |
680 | \& use Module; | |
681 | .Ve | |
682 | .PP | |
683 | or | |
684 | .PP | |
685 | .Vb 1 | |
686 | \& use Module LIST; | |
687 | .Ve | |
688 | .PP | |
689 | This is exactly equivalent to | |
690 | .PP | |
691 | .Vb 1 | |
692 | \& BEGIN { require Module; import Module; } | |
693 | .Ve | |
694 | .PP | |
695 | or | |
696 | .PP | |
697 | .Vb 1 | |
698 | \& BEGIN { require Module; import Module LIST; } | |
699 | .Ve | |
700 | .PP | |
701 | As a special case | |
702 | .PP | |
703 | .Vb 1 | |
704 | \& use Module (); | |
705 | .Ve | |
706 | .PP | |
707 | is exactly equivalent to | |
708 | .PP | |
709 | .Vb 1 | |
710 | \& BEGIN { require Module; } | |
711 | .Ve | |
712 | .PP | |
713 | All Perl module files have the extension \fI.pm\fR. The \f(CW\*(C`use\*(C'\fR operator | |
714 | assumes this so you don't have to spell out "\fIModule.pm\fR" in quotes. | |
715 | This also helps to differentiate new modules from old \fI.pl\fR and | |
716 | \&\fI.ph\fR files. Module names are also capitalized unless they're | |
717 | functioning as pragmas; pragmas are in effect compiler directives, | |
718 | and are sometimes called \*(L"pragmatic modules\*(R" (or even \*(L"pragmata\*(R" | |
719 | if you're a classicist). | |
720 | .PP | |
721 | The two statements: | |
722 | .PP | |
723 | .Vb 2 | |
724 | \& require SomeModule; | |
725 | \& require "SomeModule.pm"; | |
726 | .Ve | |
727 | .PP | |
728 | differ from each other in two ways. In the first case, any double | |
729 | colons in the module name, such as \f(CW\*(C`Some::Module\*(C'\fR, are translated | |
730 | into your system's directory separator, usually \*(L"/\*(R". The second | |
731 | case does not, and would have to be specified literally. The other | |
732 | difference is that seeing the first \f(CW\*(C`require\*(C'\fR clues in the compiler | |
733 | that uses of indirect object notation involving \*(L"SomeModule\*(R", as | |
734 | in \f(CW\*(C`$ob = purge SomeModule\*(C'\fR, are method calls, not function calls. | |
735 | (Yes, this really can make a difference.) | |
736 | .PP | |
737 | Because the \f(CW\*(C`use\*(C'\fR statement implies a \f(CW\*(C`BEGIN\*(C'\fR block, the importing | |
738 | of semantics happens as soon as the \f(CW\*(C`use\*(C'\fR statement is compiled, | |
739 | before the rest of the file is compiled. This is how it is able | |
740 | to function as a pragma mechanism, and also how modules are able to | |
741 | declare subroutines that are then visible as list or unary operators for | |
742 | the rest of the current file. This will not work if you use \f(CW\*(C`require\*(C'\fR | |
743 | instead of \f(CW\*(C`use\*(C'\fR. With \f(CW\*(C`require\*(C'\fR you can get into this problem: | |
744 | .PP | |
745 | .Vb 2 | |
746 | \& require Cwd; # make Cwd:: accessible | |
747 | \& $here = Cwd::getcwd(); | |
748 | .Ve | |
749 | .PP | |
750 | .Vb 2 | |
751 | \& use Cwd; # import names from Cwd:: | |
752 | \& $here = getcwd(); | |
753 | .Ve | |
754 | .PP | |
755 | .Vb 2 | |
756 | \& require Cwd; # make Cwd:: accessible | |
757 | \& $here = getcwd(); # oops! no main::getcwd() | |
758 | .Ve | |
759 | .PP | |
760 | In general, \f(CW\*(C`use Module ()\*(C'\fR is recommended over \f(CW\*(C`require Module\*(C'\fR, | |
761 | because it determines module availability at compile time, not in the | |
762 | middle of your program's execution. An exception would be if two modules | |
763 | each tried to \f(CW\*(C`use\*(C'\fR each other, and each also called a function from | |
764 | that other module. In that case, it's easy to use \f(CW\*(C`require\*(C'\fR instead. | |
765 | .PP | |
766 | Perl packages may be nested inside other package names, so we can have | |
767 | package names containing \f(CW\*(C`::\*(C'\fR. But if we used that package name | |
768 | directly as a filename it would make for unwieldy or impossible | |
769 | filenames on some systems. Therefore, if a module's name is, say, | |
770 | \&\f(CW\*(C`Text::Soundex\*(C'\fR, then its definition is actually found in the library | |
771 | file \fIText/Soundex.pm\fR. | |
772 | .PP | |
773 | Perl modules always have a \fI.pm\fR file, but there may also be | |
774 | dynamically linked executables (often ending in \fI.so\fR) or autoloaded | |
775 | subroutine definitions (often ending in \fI.al\fR) associated with the | |
776 | module. If so, these will be entirely transparent to the user of | |
777 | the module. It is the responsibility of the \fI.pm\fR file to load | |
778 | (or arrange to autoload) any additional functionality. For example, | |
779 | although the \s-1POSIX\s0 module happens to do both dynamic loading and | |
780 | autoloading, the user can say just \f(CW\*(C`use POSIX\*(C'\fR to get it all. | |
781 | .Sh "Making your module threadsafe" | |
782 | .IX Xref "threadsafe thread safe module, threadsafe module, thread safe CLONE CLONE_SKIP thread threads ithread" | |
783 | .IX Subsection "Making your module threadsafe" | |
784 | Since 5.6.0, Perl has had support for a new type of threads called | |
785 | interpreter threads (ithreads). These threads can be used explicitly | |
786 | and implicitly. | |
787 | .PP | |
788 | Ithreads work by cloning the data tree so that no data is shared | |
789 | between different threads. These threads can be used by using the \f(CW\*(C`threads\*(C'\fR | |
790 | module or by doing \fIfork()\fR on win32 (fake \fIfork()\fR support). When a | |
791 | thread is cloned all Perl data is cloned, however non-Perl data cannot | |
792 | be cloned automatically. Perl after 5.7.2 has support for the \f(CW\*(C`CLONE\*(C'\fR | |
793 | special subroutine. In \f(CW\*(C`CLONE\*(C'\fR you can do whatever | |
794 | you need to do, | |
795 | like for example handle the cloning of non-Perl data, if necessary. | |
796 | \&\f(CW\*(C`CLONE\*(C'\fR will be called once as a class method for every package that has it | |
797 | defined (or inherits it). It will be called in the context of the new thread, | |
798 | so all modifications are made in the new area. Currently \s-1CLONE\s0 is called with | |
799 | no parameters other than the invocant package name, but code should not assume | |
800 | that this will remain unchanged, as it is likely that in future extra parameters | |
801 | will be passed in to give more information about the state of cloning. | |
802 | .PP | |
803 | If you want to \s-1CLONE\s0 all objects you will need to keep track of them per | |
804 | package. This is simply done using a hash and \fIScalar::Util::weaken()\fR. | |
805 | .PP | |
806 | Perl after 5.8.7 has support for the \f(CW\*(C`CLONE_SKIP\*(C'\fR special subroutine. | |
807 | Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is called once per package; however, it is | |
808 | called just before cloning starts, and in the context of the parent | |
809 | thread. If it returns a true value, then no objects of that class will | |
810 | be cloned; or rather, they will be copied as unblessed, undef values. | |
811 | This provides a simple mechanism for making a module threadsafe; just add | |
812 | \&\f(CW\*(C`sub CLONE_SKIP { 1 }\*(C'\fR at the top of the class, and \f(CW\*(C`DESTROY()\*(C'\fR will be | |
813 | now only be called once per object. Of course, if the child thread needs | |
814 | to make use of the objects, then a more sophisticated approach is | |
815 | needed. | |
816 | .PP | |
817 | Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is currently called with no parameters other | |
818 | than the invocant package name, although that may change. Similarly, to | |
819 | allow for future expansion, the return value should be a single \f(CW0\fR or | |
820 | \&\f(CW1\fR value. | |
821 | .SH "SEE ALSO" | |
822 | .IX Header "SEE ALSO" | |
823 | See perlmodlib for general style issues related to building Perl | |
824 | modules and classes, as well as descriptions of the standard library | |
825 | and \s-1CPAN\s0, Exporter for how Perl's standard import/export mechanism | |
826 | works, perltoot and perltooc for an in-depth tutorial on | |
827 | creating classes, perlobj for a hard-core reference document on | |
828 | objects, perlsub for an explanation of functions and scoping, | |
829 | and perlxstut and perlguts for more information on writing | |
830 | extension modules. |