| 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. |