Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
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 "2002-06-08" "perl v5.8.0" "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 Subsection "Packages" | |
139 | Perl provides a mechanism for alternative namespaces to protect | |
140 | packages from stomping on each other's variables. In fact, there's | |
141 | really no such thing as a global variable in Perl. The package | |
142 | statement declares the compilation unit as being in the given | |
143 | namespace. The scope of the package declaration is from the | |
144 | declaration itself through the end of the enclosing block, \f(CW\*(C`eval\*(C'\fR, | |
145 | or file, whichever comes first (the same scope as the \fImy()\fR and | |
146 | \&\fIlocal()\fR operators). Unqualified dynamic identifiers will be in | |
147 | this namespace, except for those few identifiers that if unqualified, | |
148 | default to the main package instead of the current one as described | |
149 | below. A package statement affects only dynamic variables\*(--including | |
150 | those you've used \fIlocal()\fR on\*(--but \fInot\fR lexical variables created | |
151 | with \fImy()\fR. Typically it would be the first declaration in a file | |
152 | 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 | |
153 | switch into a package in more than one place; it merely influences | |
154 | which symbol table is used by the compiler for the rest of that | |
155 | block. You can refer to variables and filehandles in other packages | |
156 | by prefixing the identifier with the package name and a double | |
157 | colon: \f(CW$Package::Variable\fR. If the package name is null, the | |
158 | \&\f(CW\*(C`main\*(C'\fR package is assumed. That is, \f(CW$::sail\fR is equivalent to | |
159 | \&\f(CW$main::sail\fR. | |
160 | .PP | |
161 | The old package delimiter was a single quote, but double colon is now the | |
162 | preferred delimiter, in part because it's more readable to humans, and | |
163 | in part because it's more readable to \fBemacs\fR macros. It also makes \*(C+ | |
164 | programmers feel like they know what's going on\*(--as opposed to using the | |
165 | single quote as separator, which was there to make Ada programmers feel | |
166 | like they knew what's going on. Because the old-fashioned syntax is still | |
167 | supported for backwards compatibility, if you try to use a string like | |
168 | \&\f(CW"This is $owner's house"\fR, you'll be accessing \f(CW$owner::s\fR; that is, | |
169 | the \f(CW$s\fR variable in package \f(CW\*(C`owner\*(C'\fR, which is probably not what you meant. | |
170 | Use braces to disambiguate, as in \f(CW"This is ${owner}'s house"\fR. | |
171 | .PP | |
172 | Packages may themselves contain package separators, as in | |
173 | \&\f(CW$OUTER::INNER::var\fR. This implies nothing about the order of | |
174 | name lookups, however. There are no relative packages: all symbols | |
175 | are either local to the current package, or must be fully qualified | |
176 | from the outer package name down. For instance, there is nowhere | |
177 | within package \f(CW\*(C`OUTER\*(C'\fR that \f(CW$INNER::var\fR refers to | |
178 | \&\f(CW$OUTER::INNER::var\fR. It would treat package \f(CW\*(C`INNER\*(C'\fR as a totally | |
179 | separate global package. | |
180 | .PP | |
181 | Only identifiers starting with letters (or underscore) are stored | |
182 | in a package's symbol table. All other symbols are kept in package | |
183 | \&\f(CW\*(C`main\*(C'\fR, including all punctuation variables, like \f(CW$_\fR. In addition, | |
184 | when unqualified, the identifiers \s-1STDIN\s0, \s-1STDOUT\s0, \s-1STDERR\s0, \s-1ARGV\s0, | |
185 | \&\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, | |
186 | even when used for other purposes than their built-in one. If you | |
187 | 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 | |
188 | qualified form of an identifier because it would be instead interpreted | |
189 | as a pattern match, a substitution, or a transliteration. | |
190 | .PP | |
191 | Variables beginning with underscore used to be forced into package | |
192 | main, but we decided it was more useful for package writers to be able | |
193 | to use leading underscore to indicate private variables and method names. | |
194 | \&\f(CW$_\fR is still global though. See also | |
195 | \&\*(L"Technical Note on the Syntax of Variable Names\*(R" in perlvar. | |
196 | .PP | |
197 | \&\f(CW\*(C`eval\*(C'\fRed strings are compiled in the package in which the \fIeval()\fR was | |
198 | compiled. (Assignments to \f(CW$SIG{}\fR, however, assume the signal | |
199 | handler specified is in the \f(CW\*(C`main\*(C'\fR package. Qualify the signal handler | |
200 | name if you wish to have a signal handler in a package.) For an | |
201 | example, examine \fIperldb.pl\fR in the Perl library. It initially switches | |
202 | to the \f(CW\*(C`DB\*(C'\fR package so that the debugger doesn't interfere with variables | |
203 | in the program you are trying to debug. At various points, however, it | |
204 | temporarily switches back to the \f(CW\*(C`main\*(C'\fR package to evaluate various | |
205 | expressions in the context of the \f(CW\*(C`main\*(C'\fR package (or wherever you came | |
206 | from). See perldebug. | |
207 | .PP | |
208 | The special symbol \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR contains the current package, but cannot | |
209 | (easily) be used to construct variables. | |
210 | .PP | |
211 | See perlsub for other scoping issues related to \fImy()\fR and \fIlocal()\fR, | |
212 | and perlref regarding closures. | |
213 | .Sh "Symbol Tables" | |
214 | .IX Subsection "Symbol Tables" | |
215 | The symbol table for a package happens to be stored in the hash of that | |
216 | name with two colons appended. The main symbol table's name is thus | |
217 | \&\f(CW%main::\fR, or \f(CW%::\fR for short. Likewise the symbol table for the nested | |
218 | package mentioned earlier is named \f(CW%OUTER::INNER::\fR. | |
219 | .PP | |
220 | The value in each entry of the hash is what you are referring to when you | |
221 | use the \f(CW*name\fR typeglob notation. In fact, the following have the same | |
222 | effect, though the first is more efficient because it does the symbol | |
223 | table lookups at compile time: | |
224 | .PP | |
225 | .Vb 2 | |
226 | \& local *main::foo = *main::bar; | |
227 | \& local $main::{foo} = $main::{bar}; | |
228 | .Ve | |
229 | .PP | |
230 | (Be sure to note the \fBvast\fR difference between the second line above | |
231 | and \f(CW\*(C`local $main::foo = $main::bar\*(C'\fR. The former is accessing the hash | |
232 | \&\f(CW%main::\fR, which is the symbol table of package \f(CW\*(C`main\*(C'\fR. The latter is | |
233 | simply assigning scalar \f(CW$bar\fR in package \f(CW\*(C`main\*(C'\fR to scalar \f(CW$foo\fR of | |
234 | the same package.) | |
235 | .PP | |
236 | You can use this to print out all the variables in a package, for | |
237 | instance. The standard but antiquated \fIdumpvar.pl\fR library and | |
238 | the \s-1CPAN\s0 module Devel::Symdump make use of this. | |
239 | .PP | |
240 | Assignment to a typeglob performs an aliasing operation, i.e., | |
241 | .PP | |
242 | .Vb 1 | |
243 | \& *dick = *richard; | |
244 | .Ve | |
245 | .PP | |
246 | causes variables, subroutines, formats, and file and directory handles | |
247 | accessible via the identifier \f(CW\*(C`richard\*(C'\fR also to be accessible via the | |
248 | identifier \f(CW\*(C`dick\*(C'\fR. If you want to alias only a particular variable or | |
249 | subroutine, assign a reference instead: | |
250 | .PP | |
251 | .Vb 1 | |
252 | \& *dick = \e$richard; | |
253 | .Ve | |
254 | .PP | |
255 | Which makes \f(CW$richard\fR and \f(CW$dick\fR the same variable, but leaves | |
256 | \&\f(CW@richard\fR and \f(CW@dick\fR as separate arrays. Tricky, eh? | |
257 | .PP | |
258 | There is one subtle difference between the following statements: | |
259 | .PP | |
260 | .Vb 2 | |
261 | \& *foo = *bar; | |
262 | \& *foo = \e$bar; | |
263 | .Ve | |
264 | .PP | |
265 | \&\f(CW\*(C`*foo = *bar\*(C'\fR makes the typeglobs themselves synonymous while | |
266 | \&\f(CW\*(C`*foo = \e$bar\*(C'\fR makes the \s-1SCALAR\s0 portions of two distinct typeglobs | |
267 | refer to the same scalar value. This means that the following code: | |
268 | .PP | |
269 | .Vb 2 | |
270 | \& $bar = 1; | |
271 | \& *foo = \e$bar; # Make $foo an alias for $bar | |
272 | .Ve | |
273 | .PP | |
274 | .Vb 4 | |
275 | \& { | |
276 | \& local $bar = 2; # Restrict changes to block | |
277 | \& print $foo; # Prints '1'! | |
278 | \& } | |
279 | .Ve | |
280 | .PP | |
281 | Would print '1', because \f(CW$foo\fR holds a reference to the \fIoriginal\fR | |
282 | \&\f(CW$bar\fR \*(-- the one that was stuffed away by \f(CW\*(C`local()\*(C'\fR and which will be | |
283 | restored when the block ends. Because variables are accessed through the | |
284 | typeglob, you can use \f(CW\*(C`*foo = *bar\*(C'\fR to create an alias which can be | |
285 | localized. (But be aware that this means you can't have a separate | |
286 | \&\f(CW@foo\fR and \f(CW@bar\fR, etc.) | |
287 | .PP | |
288 | What makes all of this important is that the Exporter module uses glob | |
289 | aliasing as the import/export mechanism. Whether or not you can properly | |
290 | localize a variable that has been exported from a module depends on how | |
291 | it was exported: | |
292 | .PP | |
293 | .Vb 2 | |
294 | \& @EXPORT = qw($FOO); # Usual form, can't be localized | |
295 | \& @EXPORT = qw(*FOO); # Can be localized | |
296 | .Ve | |
297 | .PP | |
298 | You can work around the first case by using the fully qualified name | |
299 | (\f(CW$Package::FOO\fR) where you need a local value, or by overriding it | |
300 | by saying \f(CW\*(C`*FOO = *Package::FOO\*(C'\fR in your script. | |
301 | .PP | |
302 | The \f(CW\*(C`*x = \e$y\*(C'\fR mechanism may be used to pass and return cheap references | |
303 | into or from subroutines if you don't want to copy the whole | |
304 | thing. It only works when assigning to dynamic variables, not | |
305 | lexicals. | |
306 | .PP | |
307 | .Vb 9 | |
308 | \& %some_hash = (); # can't be my() | |
309 | \& *some_hash = fn( \e%another_hash ); | |
310 | \& sub fn { | |
311 | \& local *hashsym = shift; | |
312 | \& # now use %hashsym normally, and you | |
313 | \& # will affect the caller's %another_hash | |
314 | \& my %nhash = (); # do what you want | |
315 | \& return \e%nhash; | |
316 | \& } | |
317 | .Ve | |
318 | .PP | |
319 | On return, the reference will overwrite the hash slot in the | |
320 | symbol table specified by the *some_hash typeglob. This | |
321 | is a somewhat tricky way of passing around references cheaply | |
322 | when you don't want to have to remember to dereference variables | |
323 | explicitly. | |
324 | .PP | |
325 | Another use of symbol tables is for making \*(L"constant\*(R" scalars. | |
326 | .PP | |
327 | .Vb 1 | |
328 | \& *PI = \e3.14159265358979; | |
329 | .Ve | |
330 | .PP | |
331 | Now you cannot alter \f(CW$PI\fR, which is probably a good thing all in all. | |
332 | This isn't the same as a constant subroutine, which is subject to | |
333 | optimization at compile\-time. A constant subroutine is one prototyped | |
334 | to take no arguments and to return a constant expression. See | |
335 | perlsub for details on these. The \f(CW\*(C`use constant\*(C'\fR pragma is a | |
336 | convenient shorthand for these. | |
337 | .PP | |
338 | You can say \f(CW*foo{PACKAGE}\fR and \f(CW*foo{NAME}\fR to find out what name and | |
339 | package the *foo symbol table entry comes from. This may be useful | |
340 | in a subroutine that gets passed typeglobs as arguments: | |
341 | .PP | |
342 | .Vb 6 | |
343 | \& sub identify_typeglob { | |
344 | \& my $glob = shift; | |
345 | \& print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\en"; | |
346 | \& } | |
347 | \& identify_typeglob *foo; | |
348 | \& identify_typeglob *bar::baz; | |
349 | .Ve | |
350 | .PP | |
351 | This prints | |
352 | .PP | |
353 | .Vb 2 | |
354 | \& You gave me main::foo | |
355 | \& You gave me bar::baz | |
356 | .Ve | |
357 | .PP | |
358 | The \f(CW*foo{THING}\fR notation can also be used to obtain references to the | |
359 | individual elements of *foo. See perlref. | |
360 | .PP | |
361 | Subroutine definitions (and declarations, for that matter) need | |
362 | not necessarily be situated in the package whose symbol table they | |
363 | occupy. You can define a subroutine outside its package by | |
364 | explicitly qualifying the name of the subroutine: | |
365 | .PP | |
366 | .Vb 2 | |
367 | \& package main; | |
368 | \& sub Some_package::foo { ... } # &foo defined in Some_package | |
369 | .Ve | |
370 | .PP | |
371 | This is just a shorthand for a typeglob assignment at compile time: | |
372 | .PP | |
373 | .Vb 1 | |
374 | \& BEGIN { *Some_package::foo = sub { ... } } | |
375 | .Ve | |
376 | .PP | |
377 | and is \fInot\fR the same as writing: | |
378 | .PP | |
379 | .Vb 4 | |
380 | \& { | |
381 | \& package Some_package; | |
382 | \& sub foo { ... } | |
383 | \& } | |
384 | .Ve | |
385 | .PP | |
386 | In the first two versions, the body of the subroutine is | |
387 | lexically in the main package, \fInot\fR in Some_package. So | |
388 | something like this: | |
389 | .PP | |
390 | .Vb 1 | |
391 | \& package main; | |
392 | .Ve | |
393 | .PP | |
394 | .Vb 2 | |
395 | \& $Some_package::name = "fred"; | |
396 | \& $main::name = "barney"; | |
397 | .Ve | |
398 | .PP | |
399 | .Vb 3 | |
400 | \& sub Some_package::foo { | |
401 | \& print "in ", __PACKAGE__, ": \e$name is '$name'\en"; | |
402 | \& } | |
403 | .Ve | |
404 | .PP | |
405 | .Vb 1 | |
406 | \& Some_package::foo(); | |
407 | .Ve | |
408 | .PP | |
409 | prints: | |
410 | .PP | |
411 | .Vb 1 | |
412 | \& in main: $name is 'barney' | |
413 | .Ve | |
414 | .PP | |
415 | rather than: | |
416 | .PP | |
417 | .Vb 1 | |
418 | \& in Some_package: $name is 'fred' | |
419 | .Ve | |
420 | .PP | |
421 | This also has implications for the use of the \s-1SUPER::\s0 qualifier | |
422 | (see perlobj). | |
423 | .Sh "Package Constructors and Destructors" | |
424 | .IX Subsection "Package Constructors and Destructors" | |
425 | Four special subroutines act as package constructors and destructors. | |
426 | These are the \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, and \f(CW\*(C`END\*(C'\fR routines. The | |
427 | \&\f(CW\*(C`sub\*(C'\fR is optional for these routines. | |
428 | .PP | |
429 | A \f(CW\*(C`BEGIN\*(C'\fR subroutine is executed as soon as possible, that is, the moment | |
430 | it is completely defined, even before the rest of the containing file | |
431 | is parsed. You may have multiple \f(CW\*(C`BEGIN\*(C'\fR blocks within a file\*(--they | |
432 | will execute in order of definition. Because a \f(CW\*(C`BEGIN\*(C'\fR block executes | |
433 | immediately, it can pull in definitions of subroutines and such from other | |
434 | files in time to be visible to the rest of the file. Once a \f(CW\*(C`BEGIN\*(C'\fR | |
435 | has run, it is immediately undefined and any code it used is returned to | |
436 | Perl's memory pool. This means you can't ever explicitly call a \f(CW\*(C`BEGIN\*(C'\fR. | |
437 | .PP | |
438 | An \f(CW\*(C`END\*(C'\fR subroutine is executed as late as possible, that is, after | |
439 | perl has finished running the program and just before the interpreter | |
440 | is being exited, even if it is exiting as a result of a \fIdie()\fR function. | |
441 | (But not if it's polymorphing into another program via \f(CW\*(C`exec\*(C'\fR, or | |
442 | being blown out of the water by a signal\*(--you have to trap that yourself | |
443 | (if you can).) You may have multiple \f(CW\*(C`END\*(C'\fR blocks within a file\*(--they | |
444 | will execute in reverse order of definition; that is: last in, first | |
445 | out (\s-1LIFO\s0). \f(CW\*(C`END\*(C'\fR blocks are not executed when you run perl with the | |
446 | \&\f(CW\*(C`\-c\*(C'\fR switch, or if compilation fails. | |
447 | .PP | |
448 | Inside an \f(CW\*(C`END\*(C'\fR subroutine, \f(CW$?\fR contains the value that the program is | |
449 | going to pass to \f(CW\*(C`exit()\*(C'\fR. You can modify \f(CW$?\fR to change the exit | |
450 | value of the program. Beware of changing \f(CW$?\fR by accident (e.g. by | |
451 | running something via \f(CW\*(C`system\*(C'\fR). | |
452 | .PP | |
453 | Similar to \f(CW\*(C`BEGIN\*(C'\fR blocks, \f(CW\*(C`INIT\*(C'\fR blocks are run just before the | |
454 | Perl runtime begins execution, in \*(L"first in, first out\*(R" (\s-1FIFO\s0) order. | |
455 | For example, the code generators documented in perlcc make use of | |
456 | \&\f(CW\*(C`INIT\*(C'\fR blocks to initialize and resolve pointers to XSUBs. | |
457 | .PP | |
458 | Similar to \f(CW\*(C`END\*(C'\fR blocks, \f(CW\*(C`CHECK\*(C'\fR blocks are run just after the | |
459 | Perl compile phase ends and before the run time begins, in | |
460 | \&\s-1LIFO\s0 order. \f(CW\*(C`CHECK\*(C'\fR blocks are again useful in the Perl compiler | |
461 | suite to save the compiled state of the program. | |
462 | .PP | |
463 | When you use the \fB\-n\fR and \fB\-p\fR switches to Perl, \f(CW\*(C`BEGIN\*(C'\fR and | |
464 | \&\f(CW\*(C`END\*(C'\fR work just as they do in \fBawk\fR, as a degenerate case. | |
465 | Both \f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`CHECK\*(C'\fR blocks are run when you use the \fB\-c\fR | |
466 | switch for a compile-only syntax check, although your main code | |
467 | is not. | |
468 | .Sh "Perl Classes" | |
469 | .IX Subsection "Perl Classes" | |
470 | There is no special class syntax in Perl, but a package may act | |
471 | as a class if it provides subroutines to act as methods. Such a | |
472 | package may also derive some of its methods from another class (package) | |
473 | by listing the other package name(s) in its global \f(CW@ISA\fR array (which | |
474 | must be a package global, not a lexical). | |
475 | .PP | |
476 | For more on this, see perltoot and perlobj. | |
477 | .Sh "Perl Modules" | |
478 | .IX Subsection "Perl Modules" | |
479 | A module is just a set of related functions in a library file, i.e., | |
480 | a Perl package with the same name as the file. It is specifically | |
481 | designed to be reusable by other modules or programs. It may do this | |
482 | by providing a mechanism for exporting some of its symbols into the | |
483 | symbol table of any package using it. Or it may function as a class | |
484 | definition and make its semantics available implicitly through | |
485 | method calls on the class and its objects, without explicitly | |
486 | exporting anything. Or it can do a little of both. | |
487 | .PP | |
488 | For example, to start a traditional, non-OO module called Some::Module, | |
489 | create a file called \fISome/Module.pm\fR and start with this template: | |
490 | .PP | |
491 | .Vb 1 | |
492 | \& package Some::Module; # assumes Some/Module.pm | |
493 | .Ve | |
494 | .PP | |
495 | .Vb 2 | |
496 | \& use strict; | |
497 | \& use warnings; | |
498 | .Ve | |
499 | .PP | |
500 | .Vb 3 | |
501 | \& BEGIN { | |
502 | \& use Exporter (); | |
503 | \& our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); | |
504 | .Ve | |
505 | .PP | |
506 | .Vb 4 | |
507 | \& # set the version for version checking | |
508 | \& $VERSION = 1.00; | |
509 | \& # if using RCS/CVS, this may be preferred | |
510 | \& $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\ed+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker | |
511 | .Ve | |
512 | .PP | |
513 | .Vb 3 | |
514 | \& @ISA = qw(Exporter); | |
515 | \& @EXPORT = qw(&func1 &func2 &func4); | |
516 | \& %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], | |
517 | .Ve | |
518 | .PP | |
519 | .Vb 5 | |
520 | \& # your exported package globals go here, | |
521 | \& # as well as any optionally exported functions | |
522 | \& @EXPORT_OK = qw($Var1 %Hashit &func3); | |
523 | \& } | |
524 | \& our @EXPORT_OK; | |
525 | .Ve | |
526 | .PP | |
527 | .Vb 3 | |
528 | \& # exported package globals go here | |
529 | \& our $Var1; | |
530 | \& our %Hashit; | |
531 | .Ve | |
532 | .PP | |
533 | .Vb 3 | |
534 | \& # non-exported package globals go here | |
535 | \& our @more; | |
536 | \& our $stuff; | |
537 | .Ve | |
538 | .PP | |
539 | .Vb 3 | |
540 | \& # initialize package globals, first exported ones | |
541 | \& $Var1 = ''; | |
542 | \& %Hashit = (); | |
543 | .Ve | |
544 | .PP | |
545 | .Vb 3 | |
546 | \& # then the others (which are still accessible as $Some::Module::stuff) | |
547 | \& $stuff = ''; | |
548 | \& @more = (); | |
549 | .Ve | |
550 | .PP | |
551 | .Vb 2 | |
552 | \& # all file-scoped lexicals must be created before | |
553 | \& # the functions below that use them. | |
554 | .Ve | |
555 | .PP | |
556 | .Vb 3 | |
557 | \& # file-private lexicals go here | |
558 | \& my $priv_var = ''; | |
559 | \& my %secret_hash = (); | |
560 | .Ve | |
561 | .PP | |
562 | .Vb 5 | |
563 | \& # here's a file-private function as a closure, | |
564 | \& # callable as &$priv_func; it cannot be prototyped. | |
565 | \& my $priv_func = sub { | |
566 | \& # stuff goes here. | |
567 | \& }; | |
568 | .Ve | |
569 | .PP | |
570 | .Vb 5 | |
571 | \& # make all your functions, whether exported or not; | |
572 | \& # remember to put something interesting in the {} stubs | |
573 | \& sub func1 {} # no prototype | |
574 | \& sub func2() {} # proto'd void | |
575 | \& sub func3($$) {} # proto'd to 2 scalars | |
576 | .Ve | |
577 | .PP | |
578 | .Vb 2 | |
579 | \& # this one isn't exported, but could be called! | |
580 | \& sub func4(\e%) {} # proto'd to 1 hash ref | |
581 | .Ve | |
582 | .PP | |
583 | .Vb 1 | |
584 | \& END { } # module clean-up code here (global destructor) | |
585 | .Ve | |
586 | .PP | |
587 | .Vb 1 | |
588 | \& ## YOUR CODE GOES HERE | |
589 | .Ve | |
590 | .PP | |
591 | .Vb 1 | |
592 | \& 1; # don't forget to return a true value from the file | |
593 | .Ve | |
594 | .PP | |
595 | Then go on to declare and use your variables in functions without | |
596 | any qualifications. See Exporter and the perlmodlib for | |
597 | details on mechanics and style issues in module creation. | |
598 | .PP | |
599 | Perl modules are included into your program by saying | |
600 | .PP | |
601 | .Vb 1 | |
602 | \& use Module; | |
603 | .Ve | |
604 | .PP | |
605 | or | |
606 | .PP | |
607 | .Vb 1 | |
608 | \& use Module LIST; | |
609 | .Ve | |
610 | .PP | |
611 | This is exactly equivalent to | |
612 | .PP | |
613 | .Vb 1 | |
614 | \& BEGIN { require Module; import Module; } | |
615 | .Ve | |
616 | .PP | |
617 | or | |
618 | .PP | |
619 | .Vb 1 | |
620 | \& BEGIN { require Module; import Module LIST; } | |
621 | .Ve | |
622 | .PP | |
623 | As a special case | |
624 | .PP | |
625 | .Vb 1 | |
626 | \& use Module (); | |
627 | .Ve | |
628 | .PP | |
629 | is exactly equivalent to | |
630 | .PP | |
631 | .Vb 1 | |
632 | \& BEGIN { require Module; } | |
633 | .Ve | |
634 | .PP | |
635 | All Perl module files have the extension \fI.pm\fR. The \f(CW\*(C`use\*(C'\fR operator | |
636 | assumes this so you don't have to spell out "\fIModule.pm\fR" in quotes. | |
637 | This also helps to differentiate new modules from old \fI.pl\fR and | |
638 | \&\fI.ph\fR files. Module names are also capitalized unless they're | |
639 | functioning as pragmas; pragmas are in effect compiler directives, | |
640 | and are sometimes called \*(L"pragmatic modules\*(R" (or even \*(L"pragmata\*(R" | |
641 | if you're a classicist). | |
642 | .PP | |
643 | The two statements: | |
644 | .PP | |
645 | .Vb 2 | |
646 | \& require SomeModule; | |
647 | \& require "SomeModule.pm"; | |
648 | .Ve | |
649 | .PP | |
650 | differ from each other in two ways. In the first case, any double | |
651 | colons in the module name, such as \f(CW\*(C`Some::Module\*(C'\fR, are translated | |
652 | into your system's directory separator, usually \*(L"/\*(R". The second | |
653 | case does not, and would have to be specified literally. The other | |
654 | difference is that seeing the first \f(CW\*(C`require\*(C'\fR clues in the compiler | |
655 | that uses of indirect object notation involving \*(L"SomeModule\*(R", as | |
656 | in \f(CW\*(C`$ob = purge SomeModule\*(C'\fR, are method calls, not function calls. | |
657 | (Yes, this really can make a difference.) | |
658 | .PP | |
659 | Because the \f(CW\*(C`use\*(C'\fR statement implies a \f(CW\*(C`BEGIN\*(C'\fR block, the importing | |
660 | of semantics happens as soon as the \f(CW\*(C`use\*(C'\fR statement is compiled, | |
661 | before the rest of the file is compiled. This is how it is able | |
662 | to function as a pragma mechanism, and also how modules are able to | |
663 | declare subroutines that are then visible as list or unary operators for | |
664 | the rest of the current file. This will not work if you use \f(CW\*(C`require\*(C'\fR | |
665 | instead of \f(CW\*(C`use\*(C'\fR. With \f(CW\*(C`require\*(C'\fR you can get into this problem: | |
666 | .PP | |
667 | .Vb 2 | |
668 | \& require Cwd; # make Cwd:: accessible | |
669 | \& $here = Cwd::getcwd(); | |
670 | .Ve | |
671 | .PP | |
672 | .Vb 2 | |
673 | \& use Cwd; # import names from Cwd:: | |
674 | \& $here = getcwd(); | |
675 | .Ve | |
676 | .PP | |
677 | .Vb 2 | |
678 | \& require Cwd; # make Cwd:: accessible | |
679 | \& $here = getcwd(); # oops! no main::getcwd() | |
680 | .Ve | |
681 | .PP | |
682 | In general, \f(CW\*(C`use Module ()\*(C'\fR is recommended over \f(CW\*(C`require Module\*(C'\fR, | |
683 | because it determines module availability at compile time, not in the | |
684 | middle of your program's execution. An exception would be if two modules | |
685 | each tried to \f(CW\*(C`use\*(C'\fR each other, and each also called a function from | |
686 | that other module. In that case, it's easy to use \f(CW\*(C`require\*(C'\fRs instead. | |
687 | .PP | |
688 | Perl packages may be nested inside other package names, so we can have | |
689 | package names containing \f(CW\*(C`::\*(C'\fR. But if we used that package name | |
690 | directly as a filename it would make for unwieldy or impossible | |
691 | filenames on some systems. Therefore, if a module's name is, say, | |
692 | \&\f(CW\*(C`Text::Soundex\*(C'\fR, then its definition is actually found in the library | |
693 | file \fIText/Soundex.pm\fR. | |
694 | .PP | |
695 | Perl modules always have a \fI.pm\fR file, but there may also be | |
696 | dynamically linked executables (often ending in \fI.so\fR) or autoloaded | |
697 | subroutine definitions (often ending in \fI.al\fR) associated with the | |
698 | module. If so, these will be entirely transparent to the user of | |
699 | the module. It is the responsibility of the \fI.pm\fR file to load | |
700 | (or arrange to autoload) any additional functionality. For example, | |
701 | although the \s-1POSIX\s0 module happens to do both dynamic loading and | |
702 | autoloading, the user can say just \f(CW\*(C`use POSIX\*(C'\fR to get it all. | |
703 | .Sh "Making your module threadsafe" | |
704 | .IX Subsection "Making your module threadsafe" | |
705 | Perl has since 5.6.0 support for a new type of threads called | |
706 | interpreter threads. These threads can be used explicitly and implicitly. | |
707 | .PP | |
708 | Ithreads work by cloning the data tree so that no data is shared | |
709 | between different threads. These threads can be used using the threads | |
710 | module or by doing \fIfork()\fR on win32 (fake \fIfork()\fR support). When a | |
711 | thread is cloned all Perl data is cloned, however non-Perl data cannot | |
712 | be cloned automatically. Perl after 5.7.2 has support for the \f(CW\*(C`CLONE\*(C'\fR | |
713 | special subroutine . In \f(CW\*(C`CLONE\*(C'\fR you can do whatever you need to do, | |
714 | like for example handle the cloning of non-Perl data, if necessary. | |
715 | \&\f(CW\*(C`CLONE\*(C'\fR will be executed once for every package that has it defined | |
716 | (or inherits it). It will be called in the context of the new thread, | |
717 | so all modifications are made in the new area. | |
718 | .PP | |
719 | If you want to \s-1CLONE\s0 all objects you will need to keep track of them per | |
720 | package. This is simply done using a hash and \fIScalar::Util::weaken()\fR. | |
721 | .SH "SEE ALSO" | |
722 | .IX Header "SEE ALSO" | |
723 | See perlmodlib for general style issues related to building Perl | |
724 | modules and classes, as well as descriptions of the standard library | |
725 | and \s-1CPAN\s0, Exporter for how Perl's standard import/export mechanism | |
726 | works, perltoot and perltooc for an in-depth tutorial on | |
727 | creating classes, perlobj for a hard-core reference document on | |
728 | objects, perlsub for an explanation of functions and scoping, | |
729 | and perlxstut and perlguts for more information on writing | |
730 | extension modules. |