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 "PERLSUB 1" | |
132 | .TH PERLSUB 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | .IX Xref "subroutine function" | |
135 | perlsub \- Perl subroutines | |
136 | .SH "SYNOPSIS" | |
137 | .IX Header "SYNOPSIS" | |
138 | To declare subroutines: | |
139 | .IX Xref "subroutine, declaration sub" | |
140 | .PP | |
141 | .Vb 4 | |
142 | \& sub NAME; # A "forward" declaration. | |
143 | \& sub NAME(PROTO); # ditto, but with prototypes | |
144 | \& sub NAME : ATTRS; # with attributes | |
145 | \& sub NAME(PROTO) : ATTRS; # with attributes and prototypes | |
146 | .Ve | |
147 | .PP | |
148 | .Vb 4 | |
149 | \& sub NAME BLOCK # A declaration and a definition. | |
150 | \& sub NAME(PROTO) BLOCK # ditto, but with prototypes | |
151 | \& sub NAME : ATTRS BLOCK # with attributes | |
152 | \& sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes | |
153 | .Ve | |
154 | .PP | |
155 | To define an anonymous subroutine at runtime: | |
156 | .IX Xref "subroutine, anonymous" | |
157 | .PP | |
158 | .Vb 4 | |
159 | \& $subref = sub BLOCK; # no proto | |
160 | \& $subref = sub (PROTO) BLOCK; # with proto | |
161 | \& $subref = sub : ATTRS BLOCK; # with attributes | |
162 | \& $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes | |
163 | .Ve | |
164 | .PP | |
165 | To import subroutines: | |
166 | .IX Xref "import" | |
167 | .PP | |
168 | .Vb 1 | |
169 | \& use MODULE qw(NAME1 NAME2 NAME3); | |
170 | .Ve | |
171 | .PP | |
172 | To call subroutines: | |
173 | .IX Xref "subroutine, call call" | |
174 | .PP | |
175 | .Vb 4 | |
176 | \& NAME(LIST); # & is optional with parentheses. | |
177 | \& NAME LIST; # Parentheses optional if predeclared/imported. | |
178 | \& &NAME(LIST); # Circumvent prototypes. | |
179 | \& &NAME; # Makes current @_ visible to called subroutine. | |
180 | .Ve | |
181 | .SH "DESCRIPTION" | |
182 | .IX Header "DESCRIPTION" | |
183 | Like many languages, Perl provides for user-defined subroutines. | |
184 | These may be located anywhere in the main program, loaded in from | |
185 | other files via the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR keywords, or | |
186 | generated on the fly using \f(CW\*(C`eval\*(C'\fR or anonymous subroutines. | |
187 | You can even call a function indirectly using a variable containing | |
188 | its name or a \s-1CODE\s0 reference. | |
189 | .PP | |
190 | The Perl model for function call and return values is simple: all | |
191 | functions are passed as parameters one single flat list of scalars, and | |
192 | all functions likewise return to their caller one single flat list of | |
193 | scalars. Any arrays or hashes in these call and return lists will | |
194 | collapse, losing their identities\*(--but you may always use | |
195 | pass-by-reference instead to avoid this. Both call and return lists may | |
196 | contain as many or as few scalar elements as you'd like. (Often a | |
197 | function without an explicit return statement is called a subroutine, but | |
198 | there's really no difference from Perl's perspective.) | |
199 | .IX Xref "subroutine, parameter parameter" | |
200 | .PP | |
201 | Any arguments passed in show up in the array \f(CW@_\fR. Therefore, if | |
202 | you called a function with two arguments, those would be stored in | |
203 | \&\f(CW$_[0]\fR and \f(CW$_[1]\fR. The array \f(CW@_\fR is a local array, but its | |
204 | elements are aliases for the actual scalar parameters. In particular, | |
205 | if an element \f(CW$_[0]\fR is updated, the corresponding argument is | |
206 | updated (or an error occurs if it is not updatable). If an argument | |
207 | is an array or hash element which did not exist when the function | |
208 | was called, that element is created only when (and if) it is modified | |
209 | or a reference to it is taken. (Some earlier versions of Perl | |
210 | created the element whether or not the element was assigned to.) | |
211 | Assigning to the whole array \f(CW@_\fR removes that aliasing, and does | |
212 | not update any arguments. | |
213 | .IX Xref "subroutine, argument argument @_" | |
214 | .PP | |
215 | A \f(CW\*(C`return\*(C'\fR statement may be used to exit a subroutine, optionally | |
216 | specifying the returned value, which will be evaluated in the | |
217 | appropriate context (list, scalar, or void) depending on the context of | |
218 | the subroutine call. If you specify no return value, the subroutine | |
219 | returns an empty list in list context, the undefined value in scalar | |
220 | context, or nothing in void context. If you return one or more | |
221 | aggregates (arrays and hashes), these will be flattened together into | |
222 | one large indistinguishable list. | |
223 | .PP | |
224 | If no \f(CW\*(C`return\*(C'\fR is found and if the last statement is an expression, its | |
225 | value is returned. If the last statement is a loop control structure | |
226 | like a \f(CW\*(C`foreach\*(C'\fR or a \f(CW\*(C`while\*(C'\fR, the returned value is unspecified. The | |
227 | empty sub returns the empty list. | |
228 | .IX Xref "subroutine, return value return value return" | |
229 | .PP | |
230 | Perl does not have named formal parameters. In practice all you | |
231 | do is assign to a \f(CW\*(C`my()\*(C'\fR list of these. Variables that aren't | |
232 | declared to be private are global variables. For gory details | |
233 | on creating private variables, see \*(L"Private Variables via \fImy()\fR\*(R" | |
234 | and \*(L"Temporary Values via \fIlocal()\fR\*(R". To create protected | |
235 | environments for a set of functions in a separate package (and | |
236 | probably a separate file), see \*(L"Packages\*(R" in perlmod. | |
237 | .IX Xref "formal parameter parameter, formal" | |
238 | .PP | |
239 | Example: | |
240 | .PP | |
241 | .Vb 8 | |
242 | \& sub max { | |
243 | \& my $max = shift(@_); | |
244 | \& foreach $foo (@_) { | |
245 | \& $max = $foo if $max < $foo; | |
246 | \& } | |
247 | \& return $max; | |
248 | \& } | |
249 | \& $bestday = max($mon,$tue,$wed,$thu,$fri); | |
250 | .Ve | |
251 | .PP | |
252 | Example: | |
253 | .PP | |
254 | .Vb 2 | |
255 | \& # get a line, combining continuation lines | |
256 | \& # that start with whitespace | |
257 | .Ve | |
258 | .PP | |
259 | .Vb 12 | |
260 | \& sub get_line { | |
261 | \& $thisline = $lookahead; # global variables! | |
262 | \& LINE: while (defined($lookahead = <STDIN>)) { | |
263 | \& if ($lookahead =~ /^[ \et]/) { | |
264 | \& $thisline .= $lookahead; | |
265 | \& } | |
266 | \& else { | |
267 | \& last LINE; | |
268 | \& } | |
269 | \& } | |
270 | \& return $thisline; | |
271 | \& } | |
272 | .Ve | |
273 | .PP | |
274 | .Vb 4 | |
275 | \& $lookahead = <STDIN>; # get first line | |
276 | \& while (defined($line = get_line())) { | |
277 | \& ... | |
278 | \& } | |
279 | .Ve | |
280 | .PP | |
281 | Assigning to a list of private variables to name your arguments: | |
282 | .PP | |
283 | .Vb 4 | |
284 | \& sub maybeset { | |
285 | \& my($key, $value) = @_; | |
286 | \& $Foo{$key} = $value unless $Foo{$key}; | |
287 | \& } | |
288 | .Ve | |
289 | .PP | |
290 | Because the assignment copies the values, this also has the effect | |
291 | of turning call-by-reference into call\-by\-value. Otherwise a | |
292 | function is free to do in-place modifications of \f(CW@_\fR and change | |
293 | its caller's values. | |
294 | .IX Xref "call-by-reference call-by-value" | |
295 | .PP | |
296 | .Vb 4 | |
297 | \& upcase_in($v1, $v2); # this changes $v1 and $v2 | |
298 | \& sub upcase_in { | |
299 | \& for (@_) { tr/a-z/A-Z/ } | |
300 | \& } | |
301 | .Ve | |
302 | .PP | |
303 | You aren't allowed to modify constants in this way, of course. If an | |
304 | argument were actually literal and you tried to change it, you'd take a | |
305 | (presumably fatal) exception. For example, this won't work: | |
306 | .IX Xref "call-by-reference call-by-value" | |
307 | .PP | |
308 | .Vb 1 | |
309 | \& upcase_in("frederick"); | |
310 | .Ve | |
311 | .PP | |
312 | It would be much safer if the \f(CW\*(C`upcase_in()\*(C'\fR function | |
313 | were written to return a copy of its parameters instead | |
314 | of changing them in place: | |
315 | .PP | |
316 | .Vb 7 | |
317 | \& ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2 | |
318 | \& sub upcase { | |
319 | \& return unless defined wantarray; # void context, do nothing | |
320 | \& my @parms = @_; | |
321 | \& for (@parms) { tr/a-z/A-Z/ } | |
322 | \& return wantarray ? @parms : $parms[0]; | |
323 | \& } | |
324 | .Ve | |
325 | .PP | |
326 | Notice how this (unprototyped) function doesn't care whether it was | |
327 | passed real scalars or arrays. Perl sees all arguments as one big, | |
328 | long, flat parameter list in \f(CW@_\fR. This is one area where | |
329 | Perl's simple argument-passing style shines. The \f(CW\*(C`upcase()\*(C'\fR | |
330 | function would work perfectly well without changing the \f(CW\*(C`upcase()\*(C'\fR | |
331 | definition even if we fed it things like this: | |
332 | .PP | |
333 | .Vb 2 | |
334 | \& @newlist = upcase(@list1, @list2); | |
335 | \& @newlist = upcase( split /:/, $var ); | |
336 | .Ve | |
337 | .PP | |
338 | Do not, however, be tempted to do this: | |
339 | .PP | |
340 | .Vb 1 | |
341 | \& (@a, @b) = upcase(@list1, @list2); | |
342 | .Ve | |
343 | .PP | |
344 | Like the flattened incoming parameter list, the return list is also | |
345 | flattened on return. So all you have managed to do here is stored | |
346 | everything in \f(CW@a\fR and made \f(CW@b\fR empty. See | |
347 | \&\*(L"Pass by Reference\*(R" for alternatives. | |
348 | .PP | |
349 | A subroutine may be called using an explicit \f(CW\*(C`&\*(C'\fR prefix. The | |
350 | \&\f(CW\*(C`&\*(C'\fR is optional in modern Perl, as are parentheses if the | |
351 | subroutine has been predeclared. The \f(CW\*(C`&\*(C'\fR is \fInot\fR optional | |
352 | when just naming the subroutine, such as when it's used as | |
353 | an argument to \fIdefined()\fR or \fIundef()\fR. Nor is it optional when you | |
354 | want to do an indirect subroutine call with a subroutine name or | |
355 | reference using the \f(CW\*(C`&$subref()\*(C'\fR or \f(CW\*(C`&{$subref}()\*(C'\fR constructs, | |
356 | although the \f(CW\*(C`$subref\->()\*(C'\fR notation solves that problem. | |
357 | See perlref for more about all that. | |
358 | .IX Xref "&" | |
359 | .PP | |
360 | Subroutines may be called recursively. If a subroutine is called | |
361 | using the \f(CW\*(C`&\*(C'\fR form, the argument list is optional, and if omitted, | |
362 | no \f(CW@_\fR array is set up for the subroutine: the \f(CW@_\fR array at the | |
363 | time of the call is visible to subroutine instead. This is an | |
364 | efficiency mechanism that new users may wish to avoid. | |
365 | .IX Xref "recursion" | |
366 | .PP | |
367 | .Vb 2 | |
368 | \& &foo(1,2,3); # pass three arguments | |
369 | \& foo(1,2,3); # the same | |
370 | .Ve | |
371 | .PP | |
372 | .Vb 2 | |
373 | \& foo(); # pass a null list | |
374 | \& &foo(); # the same | |
375 | .Ve | |
376 | .PP | |
377 | .Vb 2 | |
378 | \& &foo; # foo() get current args, like foo(@_) !! | |
379 | \& foo; # like foo() IFF sub foo predeclared, else "foo" | |
380 | .Ve | |
381 | .PP | |
382 | Not only does the \f(CW\*(C`&\*(C'\fR form make the argument list optional, it also | |
383 | disables any prototype checking on arguments you do provide. This | |
384 | is partly for historical reasons, and partly for having a convenient way | |
385 | to cheat if you know what you're doing. See Prototypes below. | |
386 | .IX Xref "&" | |
387 | .PP | |
388 | Subroutines whose names are in all upper case are reserved to the Perl | |
389 | core, as are modules whose names are in all lower case. A subroutine in | |
390 | all capitals is a loosely-held convention meaning it will be called | |
391 | indirectly by the run-time system itself, usually due to a triggered event. | |
392 | Subroutines that do special, pre-defined things include \f(CW\*(C`AUTOLOAD\*(C'\fR, \f(CW\*(C`CLONE\*(C'\fR, | |
393 | \&\f(CW\*(C`DESTROY\*(C'\fR plus all functions mentioned in perltie and PerlIO::via. | |
394 | .PP | |
395 | 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 subroutines are not so much | |
396 | subroutines as named special code blocks, of which you can have more | |
397 | than one in a package, and which you can \fBnot\fR call explicitly. See | |
398 | \&\*(L"\s-1BEGIN\s0, \s-1CHECK\s0, \s-1INIT\s0 and \s-1END\s0\*(R" in perlmod | |
399 | .Sh "Private Variables via \fImy()\fP" | |
400 | .IX Xref "my variable, lexical lexical lexical variable scope, lexical lexical scope attributes, my" | |
401 | .IX Subsection "Private Variables via my()" | |
402 | Synopsis: | |
403 | .PP | |
404 | .Vb 5 | |
405 | \& my $foo; # declare $foo lexically local | |
406 | \& my (@wid, %get); # declare list of variables local | |
407 | \& my $foo = "flurp"; # declare $foo lexical, and init it | |
408 | \& my @oof = @bar; # declare @oof lexical, and init it | |
409 | \& my $x : Foo = $y; # similar, with an attribute applied | |
410 | .Ve | |
411 | .PP | |
412 | \&\fB\s-1WARNING\s0\fR: The use of attribute lists on \f(CW\*(C`my\*(C'\fR declarations is still | |
413 | evolving. The current semantics and interface are subject to change. | |
414 | See attributes and Attribute::Handlers. | |
415 | .PP | |
416 | The \f(CW\*(C`my\*(C'\fR operator declares the listed variables to be lexically | |
417 | confined to the enclosing block, conditional (\f(CW\*(C`if/unless/elsif/else\*(C'\fR), | |
418 | loop (\f(CW\*(C`for/foreach/while/until/continue\*(C'\fR), subroutine, \f(CW\*(C`eval\*(C'\fR, | |
419 | or \f(CW\*(C`do/require/use\*(C'\fR'd file. If more than one value is listed, the | |
420 | list must be placed in parentheses. All listed elements must be | |
421 | legal lvalues. Only alphanumeric identifiers may be lexically | |
422 | scoped\*(--magical built-ins like \f(CW$/\fR must currently be \f(CW\*(C`local\*(C'\fRized | |
423 | with \f(CW\*(C`local\*(C'\fR instead. | |
424 | .PP | |
425 | Unlike dynamic variables created by the \f(CW\*(C`local\*(C'\fR operator, lexical | |
426 | variables declared with \f(CW\*(C`my\*(C'\fR are totally hidden from the outside | |
427 | world, including any called subroutines. This is true if it's the | |
428 | same subroutine called from itself or elsewhere\*(--every call gets | |
429 | its own copy. | |
430 | .IX Xref "local" | |
431 | .PP | |
432 | This doesn't mean that a \f(CW\*(C`my\*(C'\fR variable declared in a statically | |
433 | enclosing lexical scope would be invisible. Only dynamic scopes | |
434 | are cut off. For example, the \f(CW\*(C`bumpx()\*(C'\fR function below has access | |
435 | to the lexical \f(CW$x\fR variable because both the \f(CW\*(C`my\*(C'\fR and the \f(CW\*(C`sub\*(C'\fR | |
436 | occurred at the same scope, presumably file scope. | |
437 | .PP | |
438 | .Vb 2 | |
439 | \& my $x = 10; | |
440 | \& sub bumpx { $x++ } | |
441 | .Ve | |
442 | .PP | |
443 | An \f(CW\*(C`eval()\*(C'\fR, however, can see lexical variables of the scope it is | |
444 | being evaluated in, so long as the names aren't hidden by declarations within | |
445 | the \f(CW\*(C`eval()\*(C'\fR itself. See perlref. | |
446 | .IX Xref "eval, scope of" | |
447 | .PP | |
448 | The parameter list to \fImy()\fR may be assigned to if desired, which allows you | |
449 | to initialize your variables. (If no initializer is given for a | |
450 | particular variable, it is created with the undefined value.) Commonly | |
451 | this is used to name input parameters to a subroutine. Examples: | |
452 | .PP | |
453 | .Vb 4 | |
454 | \& $arg = "fred"; # "global" variable | |
455 | \& $n = cube_root(27); | |
456 | \& print "$arg thinks the root is $n\en"; | |
457 | \& fred thinks the root is 3 | |
458 | .Ve | |
459 | .PP | |
460 | .Vb 5 | |
461 | \& sub cube_root { | |
462 | \& my $arg = shift; # name doesn't matter | |
463 | \& $arg **= 1/3; | |
464 | \& return $arg; | |
465 | \& } | |
466 | .Ve | |
467 | .PP | |
468 | The \f(CW\*(C`my\*(C'\fR is simply a modifier on something you might assign to. So when | |
469 | you do assign to variables in its argument list, \f(CW\*(C`my\*(C'\fR doesn't | |
470 | change whether those variables are viewed as a scalar or an array. So | |
471 | .PP | |
472 | .Vb 2 | |
473 | \& my ($foo) = <STDIN>; # WRONG? | |
474 | \& my @FOO = <STDIN>; | |
475 | .Ve | |
476 | .PP | |
477 | both supply a list context to the right-hand side, while | |
478 | .PP | |
479 | .Vb 1 | |
480 | \& my $foo = <STDIN>; | |
481 | .Ve | |
482 | .PP | |
483 | supplies a scalar context. But the following declares only one variable: | |
484 | .PP | |
485 | .Vb 1 | |
486 | \& my $foo, $bar = 1; # WRONG | |
487 | .Ve | |
488 | .PP | |
489 | That has the same effect as | |
490 | .PP | |
491 | .Vb 2 | |
492 | \& my $foo; | |
493 | \& $bar = 1; | |
494 | .Ve | |
495 | .PP | |
496 | The declared variable is not introduced (is not visible) until after | |
497 | the current statement. Thus, | |
498 | .PP | |
499 | .Vb 1 | |
500 | \& my $x = $x; | |
501 | .Ve | |
502 | .PP | |
503 | can be used to initialize a new \f(CW$x\fR with the value of the old \f(CW$x\fR, and | |
504 | the expression | |
505 | .PP | |
506 | .Vb 1 | |
507 | \& my $x = 123 and $x == 123 | |
508 | .Ve | |
509 | .PP | |
510 | is false unless the old \f(CW$x\fR happened to have the value \f(CW123\fR. | |
511 | .PP | |
512 | Lexical scopes of control structures are not bounded precisely by the | |
513 | braces that delimit their controlled blocks; control expressions are | |
514 | part of that scope, too. Thus in the loop | |
515 | .PP | |
516 | .Vb 5 | |
517 | \& while (my $line = <>) { | |
518 | \& $line = lc $line; | |
519 | \& } continue { | |
520 | \& print $line; | |
521 | \& } | |
522 | .Ve | |
523 | .PP | |
524 | the scope of \f(CW$line\fR extends from its declaration throughout the rest of | |
525 | the loop construct (including the \f(CW\*(C`continue\*(C'\fR clause), but not beyond | |
526 | it. Similarly, in the conditional | |
527 | .PP | |
528 | .Vb 8 | |
529 | \& if ((my $answer = <STDIN>) =~ /^yes$/i) { | |
530 | \& user_agrees(); | |
531 | \& } elsif ($answer =~ /^no$/i) { | |
532 | \& user_disagrees(); | |
533 | \& } else { | |
534 | \& chomp $answer; | |
535 | \& die "'$answer' is neither 'yes' nor 'no'"; | |
536 | \& } | |
537 | .Ve | |
538 | .PP | |
539 | the scope of \f(CW$answer\fR extends from its declaration through the rest | |
540 | of that conditional, including any \f(CW\*(C`elsif\*(C'\fR and \f(CW\*(C`else\*(C'\fR clauses, | |
541 | but not beyond it. See \*(L"Simple statements\*(R" in perlsyn for information | |
542 | on the scope of variables in statements with modifiers. | |
543 | .PP | |
544 | The \f(CW\*(C`foreach\*(C'\fR loop defaults to scoping its index variable dynamically | |
545 | in the manner of \f(CW\*(C`local\*(C'\fR. However, if the index variable is | |
546 | prefixed with the keyword \f(CW\*(C`my\*(C'\fR, or if there is already a lexical | |
547 | by that name in scope, then a new lexical is created instead. Thus | |
548 | in the loop | |
549 | .IX Xref "foreach for" | |
550 | .PP | |
551 | .Vb 3 | |
552 | \& for my $i (1, 2, 3) { | |
553 | \& some_function(); | |
554 | \& } | |
555 | .Ve | |
556 | .PP | |
557 | the scope of \f(CW$i\fR extends to the end of the loop, but not beyond it, | |
558 | rendering the value of \f(CW$i\fR inaccessible within \f(CW\*(C`some_function()\*(C'\fR. | |
559 | .IX Xref "foreach for" | |
560 | .PP | |
561 | Some users may wish to encourage the use of lexically scoped variables. | |
562 | As an aid to catching implicit uses to package variables, | |
563 | which are always global, if you say | |
564 | .PP | |
565 | .Vb 1 | |
566 | \& use strict 'vars'; | |
567 | .Ve | |
568 | .PP | |
569 | then any variable mentioned from there to the end of the enclosing | |
570 | block must either refer to a lexical variable, be predeclared via | |
571 | \&\f(CW\*(C`our\*(C'\fR or \f(CW\*(C`use vars\*(C'\fR, or else must be fully qualified with the package name. | |
572 | A compilation error results otherwise. An inner block may countermand | |
573 | this with \f(CW\*(C`no strict 'vars'\*(C'\fR. | |
574 | .PP | |
575 | A \f(CW\*(C`my\*(C'\fR has both a compile-time and a run-time effect. At compile | |
576 | time, the compiler takes notice of it. The principal usefulness | |
577 | of this is to quiet \f(CW\*(C`use strict 'vars'\*(C'\fR, but it is also essential | |
578 | for generation of closures as detailed in perlref. Actual | |
579 | initialization is delayed until run time, though, so it gets executed | |
580 | at the appropriate time, such as each time through a loop, for | |
581 | example. | |
582 | .PP | |
583 | Variables declared with \f(CW\*(C`my\*(C'\fR are not part of any package and are therefore | |
584 | never fully qualified with the package name. In particular, you're not | |
585 | allowed to try to make a package variable (or other global) lexical: | |
586 | .PP | |
587 | .Vb 2 | |
588 | \& my $pack::var; # ERROR! Illegal syntax | |
589 | \& my $_; # also illegal (currently) | |
590 | .Ve | |
591 | .PP | |
592 | In fact, a dynamic variable (also known as package or global variables) | |
593 | are still accessible using the fully qualified \f(CW\*(C`::\*(C'\fR notation even while a | |
594 | lexical of the same name is also visible: | |
595 | .PP | |
596 | .Vb 4 | |
597 | \& package main; | |
598 | \& local $x = 10; | |
599 | \& my $x = 20; | |
600 | \& print "$x and $::x\en"; | |
601 | .Ve | |
602 | .PP | |
603 | That will print out \f(CW20\fR and \f(CW10\fR. | |
604 | .PP | |
605 | You may declare \f(CW\*(C`my\*(C'\fR variables at the outermost scope of a file | |
606 | to hide any such identifiers from the world outside that file. This | |
607 | is similar in spirit to C's static variables when they are used at | |
608 | the file level. To do this with a subroutine requires the use of | |
609 | a closure (an anonymous function that accesses enclosing lexicals). | |
610 | If you want to create a private subroutine that cannot be called | |
611 | from outside that block, it can declare a lexical variable containing | |
612 | an anonymous sub reference: | |
613 | .PP | |
614 | .Vb 3 | |
615 | \& my $secret_version = '1.001-beta'; | |
616 | \& my $secret_sub = sub { print $secret_version }; | |
617 | \& &$secret_sub(); | |
618 | .Ve | |
619 | .PP | |
620 | As long as the reference is never returned by any function within the | |
621 | module, no outside module can see the subroutine, because its name is not in | |
622 | any package's symbol table. Remember that it's not \fI\s-1REALLY\s0\fR called | |
623 | \&\f(CW$some_pack::secret_version\fR or anything; it's just \f(CW$secret_version\fR, | |
624 | unqualified and unqualifiable. | |
625 | .PP | |
626 | This does not work with object methods, however; all object methods | |
627 | have to be in the symbol table of some package to be found. See | |
628 | \&\*(L"Function Templates\*(R" in perlref for something of a work-around to | |
629 | this. | |
630 | .Sh "Persistent Private Variables" | |
631 | .IX Xref "static variable, persistent variable, static closure" | |
632 | .IX Subsection "Persistent Private Variables" | |
633 | Just because a lexical variable is lexically (also called statically) | |
634 | scoped to its enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do\*(C'\fR \s-1FILE\s0, this doesn't mean that | |
635 | within a function it works like a C static. It normally works more | |
636 | like a C auto, but with implicit garbage collection. | |
637 | .PP | |
638 | Unlike local variables in C or \*(C+, Perl's lexical variables don't | |
639 | necessarily get recycled just because their scope has exited. | |
640 | If something more permanent is still aware of the lexical, it will | |
641 | stick around. So long as something else references a lexical, that | |
642 | lexical won't be freed\*(--which is as it should be. You wouldn't want | |
643 | memory being free until you were done using it, or kept around once you | |
644 | were done. Automatic garbage collection takes care of this for you. | |
645 | .PP | |
646 | This means that you can pass back or save away references to lexical | |
647 | variables, whereas to return a pointer to a C auto is a grave error. | |
648 | It also gives us a way to simulate C's function statics. Here's a | |
649 | mechanism for giving a function private variables with both lexical | |
650 | scoping and a static lifetime. If you do want to create something like | |
651 | C's static variables, just enclose the whole function in an extra block, | |
652 | and put the static variable outside the function but in the block. | |
653 | .PP | |
654 | .Vb 8 | |
655 | \& { | |
656 | \& my $secret_val = 0; | |
657 | \& sub gimme_another { | |
658 | \& return ++$secret_val; | |
659 | \& } | |
660 | \& } | |
661 | \& # $secret_val now becomes unreachable by the outside | |
662 | \& # world, but retains its value between calls to gimme_another | |
663 | .Ve | |
664 | .PP | |
665 | If this function is being sourced in from a separate file | |
666 | via \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR, then this is probably just fine. If it's | |
667 | all in the main program, you'll need to arrange for the \f(CW\*(C`my\*(C'\fR | |
668 | to be executed early, either by putting the whole block above | |
669 | your main program, or more likely, placing merely a \f(CW\*(C`BEGIN\*(C'\fR | |
670 | code block around it to make sure it gets executed before your program | |
671 | starts to run: | |
672 | .PP | |
673 | .Vb 6 | |
674 | \& BEGIN { | |
675 | \& my $secret_val = 0; | |
676 | \& sub gimme_another { | |
677 | \& return ++$secret_val; | |
678 | \& } | |
679 | \& } | |
680 | .Ve | |
681 | .PP | |
682 | See \*(L"\s-1BEGIN\s0, \s-1CHECK\s0, \s-1INIT\s0 and \s-1END\s0\*(R" in perlmod about the | |
683 | special triggered code blocks, \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. | |
684 | .PP | |
685 | If declared at the outermost scope (the file scope), then lexicals | |
686 | work somewhat like C's file statics. They are available to all | |
687 | functions in that same file declared below them, but are inaccessible | |
688 | from outside that file. This strategy is sometimes used in modules | |
689 | to create private variables that the whole module can see. | |
690 | .Sh "Temporary Values via \fIlocal()\fP" | |
691 | .IX Xref "local scope, dynamic dynamic scope variable, local variable, temporary" | |
692 | .IX Subsection "Temporary Values via local()" | |
693 | \&\fB\s-1WARNING\s0\fR: In general, you should be using \f(CW\*(C`my\*(C'\fR instead of \f(CW\*(C`local\*(C'\fR, because | |
694 | it's faster and safer. Exceptions to this include the global punctuation | |
695 | variables, global filehandles and formats, and direct manipulation of the | |
696 | Perl symbol table itself. \f(CW\*(C`local\*(C'\fR is mostly used when the current value | |
697 | of a variable must be visible to called subroutines. | |
698 | .PP | |
699 | Synopsis: | |
700 | .PP | |
701 | .Vb 1 | |
702 | \& # localization of values | |
703 | .Ve | |
704 | .PP | |
705 | .Vb 4 | |
706 | \& local $foo; # make $foo dynamically local | |
707 | \& local (@wid, %get); # make list of variables local | |
708 | \& local $foo = "flurp"; # make $foo dynamic, and init it | |
709 | \& local @oof = @bar; # make @oof dynamic, and init it | |
710 | .Ve | |
711 | .PP | |
712 | .Vb 3 | |
713 | \& local $hash{key} = "val"; # sets a local value for this hash entry | |
714 | \& local ($cond ? $v1 : $v2); # several types of lvalues support | |
715 | \& # localization | |
716 | .Ve | |
717 | .PP | |
718 | .Vb 1 | |
719 | \& # localization of symbols | |
720 | .Ve | |
721 | .PP | |
722 | .Vb 5 | |
723 | \& local *FH; # localize $FH, @FH, %FH, &FH ... | |
724 | \& local *merlyn = *randal; # now $merlyn is really $randal, plus | |
725 | \& # @merlyn is really @randal, etc | |
726 | \& local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal | |
727 | \& local *merlyn = \e$randal; # just alias $merlyn, not @merlyn etc | |
728 | .Ve | |
729 | .PP | |
730 | A \f(CW\*(C`local\*(C'\fR modifies its listed variables to be \*(L"local\*(R" to the | |
731 | enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do FILE\*(C'\fR\-\-and to \fIany subroutine | |
732 | called from within that block\fR. A \f(CW\*(C`local\*(C'\fR just gives temporary | |
733 | values to global (meaning package) variables. It does \fInot\fR create | |
734 | a local variable. This is known as dynamic scoping. Lexical scoping | |
735 | is done with \f(CW\*(C`my\*(C'\fR, which works more like C's auto declarations. | |
736 | .PP | |
737 | Some types of lvalues can be localized as well : hash and array elements | |
738 | and slices, conditionals (provided that their result is always | |
739 | localizable), and symbolic references. As for simple variables, this | |
740 | creates new, dynamically scoped values. | |
741 | .PP | |
742 | If more than one variable or expression is given to \f(CW\*(C`local\*(C'\fR, they must be | |
743 | placed in parentheses. This operator works | |
744 | by saving the current values of those variables in its argument list on a | |
745 | hidden stack and restoring them upon exiting the block, subroutine, or | |
746 | eval. This means that called subroutines can also reference the local | |
747 | variable, but not the global one. The argument list may be assigned to if | |
748 | desired, which allows you to initialize your local variables. (If no | |
749 | initializer is given for a particular variable, it is created with an | |
750 | undefined value.) | |
751 | .PP | |
752 | Because \f(CW\*(C`local\*(C'\fR is a run-time operator, it gets executed each time | |
753 | through a loop. Consequently, it's more efficient to localize your | |
754 | variables outside the loop. | |
755 | .PP | |
756 | \fIGrammatical note on \fIlocal()\fI\fR | |
757 | .IX Xref "local, context" | |
758 | .IX Subsection "Grammatical note on local()" | |
759 | .PP | |
760 | A \f(CW\*(C`local\*(C'\fR is simply a modifier on an lvalue expression. When you assign to | |
761 | a \f(CW\*(C`local\*(C'\fRized variable, the \f(CW\*(C`local\*(C'\fR doesn't change whether its list is viewed | |
762 | as a scalar or an array. So | |
763 | .PP | |
764 | .Vb 2 | |
765 | \& local($foo) = <STDIN>; | |
766 | \& local @FOO = <STDIN>; | |
767 | .Ve | |
768 | .PP | |
769 | both supply a list context to the right-hand side, while | |
770 | .PP | |
771 | .Vb 1 | |
772 | \& local $foo = <STDIN>; | |
773 | .Ve | |
774 | .PP | |
775 | supplies a scalar context. | |
776 | .PP | |
777 | \fILocalization of special variables\fR | |
778 | .IX Xref "local, special variable" | |
779 | .IX Subsection "Localization of special variables" | |
780 | .PP | |
781 | If you localize a special variable, you'll be giving a new value to it, | |
782 | but its magic won't go away. That means that all side-effects related | |
783 | to this magic still work with the localized value. | |
784 | .PP | |
785 | This feature allows code like this to work : | |
786 | .PP | |
787 | .Vb 2 | |
788 | \& # Read the whole contents of FILE in $slurp | |
789 | \& { local $/ = undef; $slurp = <FILE>; } | |
790 | .Ve | |
791 | .PP | |
792 | Note, however, that this restricts localization of some values ; for | |
793 | example, the following statement dies, as of perl 5.9.0, with an error | |
794 | \&\fIModification of a read-only value attempted\fR, because the \f(CW$1\fR variable is | |
795 | magical and read-only : | |
796 | .PP | |
797 | .Vb 1 | |
798 | \& local $1 = 2; | |
799 | .Ve | |
800 | .PP | |
801 | Similarly, but in a way more difficult to spot, the following snippet will | |
802 | die in perl 5.9.0 : | |
803 | .PP | |
804 | .Vb 5 | |
805 | \& sub f { local $_ = "foo"; print } | |
806 | \& for ($1) { | |
807 | \& # now $_ is aliased to $1, thus is magic and readonly | |
808 | \& f(); | |
809 | \& } | |
810 | .Ve | |
811 | .PP | |
812 | See next section for an alternative to this situation. | |
813 | .PP | |
814 | \&\fB\s-1WARNING\s0\fR: Localization of tied arrays and hashes does not currently | |
815 | work as described. | |
816 | This will be fixed in a future release of Perl; in the meantime, avoid | |
817 | code that relies on any particular behaviour of localising tied arrays | |
818 | or hashes (localising individual elements is still okay). | |
819 | See \*(L"Localising Tied Arrays and Hashes Is Broken\*(R" in perl58delta for more | |
820 | details. | |
821 | .IX Xref "local, tie" | |
822 | .PP | |
823 | \fILocalization of globs\fR | |
824 | .IX Xref "local, glob glob" | |
825 | .IX Subsection "Localization of globs" | |
826 | .PP | |
827 | The construct | |
828 | .PP | |
829 | .Vb 1 | |
830 | \& local *name; | |
831 | .Ve | |
832 | .PP | |
833 | creates a whole new symbol table entry for the glob \f(CW\*(C`name\*(C'\fR in the | |
834 | current package. That means that all variables in its glob slot ($name, | |
835 | \&\f(CW@name\fR, \f(CW%name\fR, &name, and the \f(CW\*(C`name\*(C'\fR filehandle) are dynamically reset. | |
836 | .PP | |
837 | This implies, among other things, that any magic eventually carried by | |
838 | those variables is locally lost. In other words, saying \f(CW\*(C`local */\*(C'\fR | |
839 | will not have any effect on the internal value of the input record | |
840 | separator. | |
841 | .PP | |
842 | Notably, if you want to work with a brand new value of the default scalar | |
843 | \&\f(CW$_\fR, and avoid the potential problem listed above about \f(CW$_\fR previously | |
844 | carrying a magic value, you should use \f(CW\*(C`local *_\*(C'\fR instead of \f(CW\*(C`local $_\*(C'\fR. | |
845 | .PP | |
846 | \fILocalization of elements of composite types\fR | |
847 | .IX Xref "local, composite type element local, array element local, hash element" | |
848 | .IX Subsection "Localization of elements of composite types" | |
849 | .PP | |
850 | It's also worth taking a moment to explain what happens when you | |
851 | \&\f(CW\*(C`local\*(C'\fRize a member of a composite type (i.e. an array or hash element). | |
852 | In this case, the element is \f(CW\*(C`local\*(C'\fRized \fIby name\fR. This means that | |
853 | when the scope of the \f(CW\*(C`local()\*(C'\fR ends, the saved value will be | |
854 | restored to the hash element whose key was named in the \f(CW\*(C`local()\*(C'\fR, or | |
855 | the array element whose index was named in the \f(CW\*(C`local()\*(C'\fR. If that | |
856 | element was deleted while the \f(CW\*(C`local()\*(C'\fR was in effect (e.g. by a | |
857 | \&\f(CW\*(C`delete()\*(C'\fR from a hash or a \f(CW\*(C`shift()\*(C'\fR of an array), it will spring | |
858 | back into existence, possibly extending an array and filling in the | |
859 | skipped elements with \f(CW\*(C`undef\*(C'\fR. For instance, if you say | |
860 | .PP | |
861 | .Vb 17 | |
862 | \& %hash = ( 'This' => 'is', 'a' => 'test' ); | |
863 | \& @ary = ( 0..5 ); | |
864 | \& { | |
865 | \& local($ary[5]) = 6; | |
866 | \& local($hash{'a'}) = 'drill'; | |
867 | \& while (my $e = pop(@ary)) { | |
868 | \& print "$e . . .\en"; | |
869 | \& last unless $e > 3; | |
870 | \& } | |
871 | \& if (@ary) { | |
872 | \& $hash{'only a'} = 'test'; | |
873 | \& delete $hash{'a'}; | |
874 | \& } | |
875 | \& } | |
876 | \& print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\en"; | |
877 | \& print "The array has ",scalar(@ary)," elements: ", | |
878 | \& join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\en"; | |
879 | .Ve | |
880 | .PP | |
881 | Perl will print | |
882 | .PP | |
883 | .Vb 5 | |
884 | \& 6 . . . | |
885 | \& 4 . . . | |
886 | \& 3 . . . | |
887 | \& This is a test only a test. | |
888 | \& The array has 6 elements: 0, 1, 2, undef, undef, 5 | |
889 | .Ve | |
890 | .PP | |
891 | The behavior of \fIlocal()\fR on non-existent members of composite | |
892 | types is subject to change in future. | |
893 | .Sh "Lvalue subroutines" | |
894 | .IX Xref "lvalue subroutine, lvalue" | |
895 | .IX Subsection "Lvalue subroutines" | |
896 | \&\fB\s-1WARNING\s0\fR: Lvalue subroutines are still experimental and the | |
897 | implementation may change in future versions of Perl. | |
898 | .PP | |
899 | It is possible to return a modifiable value from a subroutine. | |
900 | To do this, you have to declare the subroutine to return an lvalue. | |
901 | .PP | |
902 | .Vb 8 | |
903 | \& my $val; | |
904 | \& sub canmod : lvalue { | |
905 | \& # return $val; this doesn't work, don't say "return" | |
906 | \& $val; | |
907 | \& } | |
908 | \& sub nomod { | |
909 | \& $val; | |
910 | \& } | |
911 | .Ve | |
912 | .PP | |
913 | .Vb 2 | |
914 | \& canmod() = 5; # assigns to $val | |
915 | \& nomod() = 5; # ERROR | |
916 | .Ve | |
917 | .PP | |
918 | The scalar/list context for the subroutine and for the right-hand | |
919 | side of assignment is determined as if the subroutine call is replaced | |
920 | by a scalar. For example, consider: | |
921 | .PP | |
922 | .Vb 1 | |
923 | \& data(2,3) = get_data(3,4); | |
924 | .Ve | |
925 | .PP | |
926 | Both subroutines here are called in a scalar context, while in: | |
927 | .PP | |
928 | .Vb 1 | |
929 | \& (data(2,3)) = get_data(3,4); | |
930 | .Ve | |
931 | .PP | |
932 | and in: | |
933 | .PP | |
934 | .Vb 1 | |
935 | \& (data(2),data(3)) = get_data(3,4); | |
936 | .Ve | |
937 | .PP | |
938 | all the subroutines are called in a list context. | |
939 | .IP "Lvalue subroutines are \s-1EXPERIMENTAL\s0" 4 | |
940 | .IX Item "Lvalue subroutines are EXPERIMENTAL" | |
941 | They appear to be convenient, but there are several reasons to be | |
942 | circumspect. | |
943 | .Sp | |
944 | You can't use the return keyword, you must pass out the value before | |
945 | falling out of subroutine scope. (see comment in example above). This | |
946 | is usually not a problem, but it disallows an explicit return out of a | |
947 | deeply nested loop, which is sometimes a nice way out. | |
948 | .Sp | |
949 | They violate encapsulation. A normal mutator can check the supplied | |
950 | argument before setting the attribute it is protecting, an lvalue | |
951 | subroutine never gets that chance. Consider; | |
952 | .Sp | |
953 | .Vb 1 | |
954 | \& my $some_array_ref = []; # protected by mutators ?? | |
955 | .Ve | |
956 | .Sp | |
957 | .Vb 9 | |
958 | \& sub set_arr { # normal mutator | |
959 | \& my $val = shift; | |
960 | \& die("expected array, you supplied ", ref $val) | |
961 | \& unless ref $val eq 'ARRAY'; | |
962 | \& $some_array_ref = $val; | |
963 | \& } | |
964 | \& sub set_arr_lv : lvalue { # lvalue mutator | |
965 | \& $some_array_ref; | |
966 | \& } | |
967 | .Ve | |
968 | .Sp | |
969 | .Vb 2 | |
970 | \& # set_arr_lv cannot stop this ! | |
971 | \& set_arr_lv() = { a => 1 }; | |
972 | .Ve | |
973 | .Sh "Passing Symbol Table Entries (typeglobs)" | |
974 | .IX Xref "typeglob *" | |
975 | .IX Subsection "Passing Symbol Table Entries (typeglobs)" | |
976 | \&\fB\s-1WARNING\s0\fR: The mechanism described in this section was originally | |
977 | the only way to simulate pass-by-reference in older versions of | |
978 | Perl. While it still works fine in modern versions, the new reference | |
979 | mechanism is generally easier to work with. See below. | |
980 | .PP | |
981 | Sometimes you don't want to pass the value of an array to a subroutine | |
982 | but rather the name of it, so that the subroutine can modify the global | |
983 | copy of it rather than working with a local copy. In perl you can | |
984 | refer to all objects of a particular name by prefixing the name | |
985 | with a star: \f(CW*foo\fR. This is often known as a \*(L"typeglob\*(R", because the | |
986 | star on the front can be thought of as a wildcard match for all the | |
987 | funny prefix characters on variables and subroutines and such. | |
988 | .PP | |
989 | When evaluated, the typeglob produces a scalar value that represents | |
990 | all the objects of that name, including any filehandle, format, or | |
991 | subroutine. When assigned to, it causes the name mentioned to refer to | |
992 | whatever \f(CW\*(C`*\*(C'\fR value was assigned to it. Example: | |
993 | .PP | |
994 | .Vb 8 | |
995 | \& sub doubleary { | |
996 | \& local(*someary) = @_; | |
997 | \& foreach $elem (@someary) { | |
998 | \& $elem *= 2; | |
999 | \& } | |
1000 | \& } | |
1001 | \& doubleary(*foo); | |
1002 | \& doubleary(*bar); | |
1003 | .Ve | |
1004 | .PP | |
1005 | Scalars are already passed by reference, so you can modify | |
1006 | scalar arguments without using this mechanism by referring explicitly | |
1007 | to \f(CW$_[0]\fR etc. You can modify all the elements of an array by passing | |
1008 | all the elements as scalars, but you have to use the \f(CW\*(C`*\*(C'\fR mechanism (or | |
1009 | the equivalent reference mechanism) to \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, or change the size of | |
1010 | an array. It will certainly be faster to pass the typeglob (or reference). | |
1011 | .PP | |
1012 | Even if you don't want to modify an array, this mechanism is useful for | |
1013 | passing multiple arrays in a single \s-1LIST\s0, because normally the \s-1LIST\s0 | |
1014 | mechanism will merge all the array values so that you can't extract out | |
1015 | the individual arrays. For more on typeglobs, see | |
1016 | \&\*(L"Typeglobs and Filehandles\*(R" in perldata. | |
1017 | .Sh "When to Still Use \fIlocal()\fP" | |
1018 | .IX Xref "local variable, local" | |
1019 | .IX Subsection "When to Still Use local()" | |
1020 | Despite the existence of \f(CW\*(C`my\*(C'\fR, there are still three places where the | |
1021 | \&\f(CW\*(C`local\*(C'\fR operator still shines. In fact, in these three places, you | |
1022 | \&\fImust\fR use \f(CW\*(C`local\*(C'\fR instead of \f(CW\*(C`my\*(C'\fR. | |
1023 | .IP "1." 4 | |
1024 | You need to give a global variable a temporary value, especially \f(CW$_\fR. | |
1025 | .Sp | |
1026 | The global variables, like \f(CW@ARGV\fR or the punctuation variables, must be | |
1027 | \&\f(CW\*(C`local\*(C'\fRized with \f(CW\*(C`local()\*(C'\fR. This block reads in \fI/etc/motd\fR, and splits | |
1028 | it up into chunks separated by lines of equal signs, which are placed | |
1029 | in \f(CW@Fields\fR. | |
1030 | .Sp | |
1031 | .Vb 6 | |
1032 | \& { | |
1033 | \& local @ARGV = ("/etc/motd"); | |
1034 | \& local $/ = undef; | |
1035 | \& local $_ = <>; | |
1036 | \& @Fields = split /^\es*=+\es*$/; | |
1037 | \& } | |
1038 | .Ve | |
1039 | .Sp | |
1040 | It particular, it's important to \f(CW\*(C`local\*(C'\fRize \f(CW$_\fR in any routine that assigns | |
1041 | to it. Look out for implicit assignments in \f(CW\*(C`while\*(C'\fR conditionals. | |
1042 | .IP "2." 4 | |
1043 | You need to create a local file or directory handle or a local function. | |
1044 | .Sp | |
1045 | A function that needs a filehandle of its own must use | |
1046 | \&\f(CW\*(C`local()\*(C'\fR on a complete typeglob. This can be used to create new symbol | |
1047 | table entries: | |
1048 | .Sp | |
1049 | .Vb 6 | |
1050 | \& sub ioqueue { | |
1051 | \& local (*READER, *WRITER); # not my! | |
1052 | \& pipe (READER, WRITER) or die "pipe: $!"; | |
1053 | \& return (*READER, *WRITER); | |
1054 | \& } | |
1055 | \& ($head, $tail) = ioqueue(); | |
1056 | .Ve | |
1057 | .Sp | |
1058 | See the Symbol module for a way to create anonymous symbol table | |
1059 | entries. | |
1060 | .Sp | |
1061 | Because assignment of a reference to a typeglob creates an alias, this | |
1062 | can be used to create what is effectively a local function, or at least, | |
1063 | a local alias. | |
1064 | .Sp | |
1065 | .Vb 6 | |
1066 | \& { | |
1067 | \& local *grow = \e&shrink; # only until this block exists | |
1068 | \& grow(); # really calls shrink() | |
1069 | \& move(); # if move() grow()s, it shrink()s too | |
1070 | \& } | |
1071 | \& grow(); # get the real grow() again | |
1072 | .Ve | |
1073 | .Sp | |
1074 | See \*(L"Function Templates\*(R" in perlref for more about manipulating | |
1075 | functions by name in this way. | |
1076 | .IP "3." 4 | |
1077 | You want to temporarily change just one element of an array or hash. | |
1078 | .Sp | |
1079 | You can \f(CW\*(C`local\*(C'\fRize just one element of an aggregate. Usually this | |
1080 | is done on dynamics: | |
1081 | .Sp | |
1082 | .Vb 5 | |
1083 | \& { | |
1084 | \& local $SIG{INT} = 'IGNORE'; | |
1085 | \& funct(); # uninterruptible | |
1086 | \& } | |
1087 | \& # interruptibility automatically restored here | |
1088 | .Ve | |
1089 | .Sp | |
1090 | But it also works on lexically declared aggregates. Prior to 5.005, | |
1091 | this operation could on occasion misbehave. | |
1092 | .Sh "Pass by Reference" | |
1093 | .IX Xref "pass by reference pass-by-reference reference" | |
1094 | .IX Subsection "Pass by Reference" | |
1095 | If you want to pass more than one array or hash into a function\*(--or | |
1096 | return them from it\*(--and have them maintain their integrity, then | |
1097 | you're going to have to use an explicit pass\-by\-reference. Before you | |
1098 | do that, you need to understand references as detailed in perlref. | |
1099 | This section may not make much sense to you otherwise. | |
1100 | .PP | |
1101 | Here are a few simple examples. First, let's pass in several arrays | |
1102 | to a function and have it \f(CW\*(C`pop\*(C'\fR all of then, returning a new list | |
1103 | of all their former last elements: | |
1104 | .PP | |
1105 | .Vb 1 | |
1106 | \& @tailings = popmany ( \e@a, \e@b, \e@c, \e@d ); | |
1107 | .Ve | |
1108 | .PP | |
1109 | .Vb 8 | |
1110 | \& sub popmany { | |
1111 | \& my $aref; | |
1112 | \& my @retlist = (); | |
1113 | \& foreach $aref ( @_ ) { | |
1114 | \& push @retlist, pop @$aref; | |
1115 | \& } | |
1116 | \& return @retlist; | |
1117 | \& } | |
1118 | .Ve | |
1119 | .PP | |
1120 | Here's how you might write a function that returns a | |
1121 | list of keys occurring in all the hashes passed to it: | |
1122 | .PP | |
1123 | .Vb 10 | |
1124 | \& @common = inter( \e%foo, \e%bar, \e%joe ); | |
1125 | \& sub inter { | |
1126 | \& my ($k, $href, %seen); # locals | |
1127 | \& foreach $href (@_) { | |
1128 | \& while ( $k = each %$href ) { | |
1129 | \& $seen{$k}++; | |
1130 | \& } | |
1131 | \& } | |
1132 | \& return grep { $seen{$_} == @_ } keys %seen; | |
1133 | \& } | |
1134 | .Ve | |
1135 | .PP | |
1136 | So far, we're using just the normal list return mechanism. | |
1137 | What happens if you want to pass or return a hash? Well, | |
1138 | if you're using only one of them, or you don't mind them | |
1139 | concatenating, then the normal calling convention is ok, although | |
1140 | a little expensive. | |
1141 | .PP | |
1142 | Where people get into trouble is here: | |
1143 | .PP | |
1144 | .Vb 3 | |
1145 | \& (@a, @b) = func(@c, @d); | |
1146 | \&or | |
1147 | \& (%a, %b) = func(%c, %d); | |
1148 | .Ve | |
1149 | .PP | |
1150 | That syntax simply won't work. It sets just \f(CW@a\fR or \f(CW%a\fR and | |
1151 | clears the \f(CW@b\fR or \f(CW%b\fR. Plus the function didn't get passed | |
1152 | into two separate arrays or hashes: it got one long list in \f(CW@_\fR, | |
1153 | as always. | |
1154 | .PP | |
1155 | If you can arrange for everyone to deal with this through references, it's | |
1156 | cleaner code, although not so nice to look at. Here's a function that | |
1157 | takes two array references as arguments, returning the two array elements | |
1158 | in order of how many elements they have in them: | |
1159 | .PP | |
1160 | .Vb 10 | |
1161 | \& ($aref, $bref) = func(\e@c, \e@d); | |
1162 | \& print "@$aref has more than @$bref\en"; | |
1163 | \& sub func { | |
1164 | \& my ($cref, $dref) = @_; | |
1165 | \& if (@$cref > @$dref) { | |
1166 | \& return ($cref, $dref); | |
1167 | \& } else { | |
1168 | \& return ($dref, $cref); | |
1169 | \& } | |
1170 | \& } | |
1171 | .Ve | |
1172 | .PP | |
1173 | It turns out that you can actually do this also: | |
1174 | .PP | |
1175 | .Vb 10 | |
1176 | \& (*a, *b) = func(\e@c, \e@d); | |
1177 | \& print "@a has more than @b\en"; | |
1178 | \& sub func { | |
1179 | \& local (*c, *d) = @_; | |
1180 | \& if (@c > @d) { | |
1181 | \& return (\e@c, \e@d); | |
1182 | \& } else { | |
1183 | \& return (\e@d, \e@c); | |
1184 | \& } | |
1185 | \& } | |
1186 | .Ve | |
1187 | .PP | |
1188 | Here we're using the typeglobs to do symbol table aliasing. It's | |
1189 | a tad subtle, though, and also won't work if you're using \f(CW\*(C`my\*(C'\fR | |
1190 | variables, because only globals (even in disguise as \f(CW\*(C`local\*(C'\fRs) | |
1191 | are in the symbol table. | |
1192 | .PP | |
1193 | If you're passing around filehandles, you could usually just use the bare | |
1194 | typeglob, like \f(CW*STDOUT\fR, but typeglobs references work, too. | |
1195 | For example: | |
1196 | .PP | |
1197 | .Vb 5 | |
1198 | \& splutter(\e*STDOUT); | |
1199 | \& sub splutter { | |
1200 | \& my $fh = shift; | |
1201 | \& print $fh "her um well a hmmm\en"; | |
1202 | \& } | |
1203 | .Ve | |
1204 | .PP | |
1205 | .Vb 5 | |
1206 | \& $rec = get_rec(\e*STDIN); | |
1207 | \& sub get_rec { | |
1208 | \& my $fh = shift; | |
1209 | \& return scalar <$fh>; | |
1210 | \& } | |
1211 | .Ve | |
1212 | .PP | |
1213 | If you're planning on generating new filehandles, you could do this. | |
1214 | Notice to pass back just the bare *FH, not its reference. | |
1215 | .PP | |
1216 | .Vb 5 | |
1217 | \& sub openit { | |
1218 | \& my $path = shift; | |
1219 | \& local *FH; | |
1220 | \& return open (FH, $path) ? *FH : undef; | |
1221 | \& } | |
1222 | .Ve | |
1223 | .Sh "Prototypes" | |
1224 | .IX Xref "prototype subroutine, prototype" | |
1225 | .IX Subsection "Prototypes" | |
1226 | Perl supports a very limited kind of compile-time argument checking | |
1227 | using function prototyping. If you declare | |
1228 | .PP | |
1229 | .Vb 1 | |
1230 | \& sub mypush (\e@@) | |
1231 | .Ve | |
1232 | .PP | |
1233 | then \f(CW\*(C`mypush()\*(C'\fR takes arguments exactly like \f(CW\*(C`push()\*(C'\fR does. The | |
1234 | function declaration must be visible at compile time. The prototype | |
1235 | affects only interpretation of new-style calls to the function, | |
1236 | where new-style is defined as not using the \f(CW\*(C`&\*(C'\fR character. In | |
1237 | other words, if you call it like a built-in function, then it behaves | |
1238 | like a built-in function. If you call it like an old-fashioned | |
1239 | subroutine, then it behaves like an old-fashioned subroutine. It | |
1240 | naturally falls out from this rule that prototypes have no influence | |
1241 | on subroutine references like \f(CW\*(C`\e&foo\*(C'\fR or on indirect subroutine | |
1242 | calls like \f(CW\*(C`&{$subref}\*(C'\fR or \f(CW\*(C`$subref\->()\*(C'\fR. | |
1243 | .PP | |
1244 | Method calls are not influenced by prototypes either, because the | |
1245 | function to be called is indeterminate at compile time, since | |
1246 | the exact code called depends on inheritance. | |
1247 | .PP | |
1248 | Because the intent of this feature is primarily to let you define | |
1249 | subroutines that work like built-in functions, here are prototypes | |
1250 | for some other functions that parse almost exactly like the | |
1251 | corresponding built\-in. | |
1252 | .PP | |
1253 | .Vb 1 | |
1254 | \& Declared as Called as | |
1255 | .Ve | |
1256 | .PP | |
1257 | .Vb 14 | |
1258 | \& sub mylink ($$) mylink $old, $new | |
1259 | \& sub myvec ($$$) myvec $var, $offset, 1 | |
1260 | \& sub myindex ($$;$) myindex &getstring, "substr" | |
1261 | \& sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off | |
1262 | \& sub myreverse (@) myreverse $a, $b, $c | |
1263 | \& sub myjoin ($@) myjoin ":", $a, $b, $c | |
1264 | \& sub mypop (\e@) mypop @array | |
1265 | \& sub mysplice (\e@$$@) mysplice @array, @array, 0, @pushme | |
1266 | \& sub mykeys (\e%) mykeys %{$hashref} | |
1267 | \& sub myopen (*;$) myopen HANDLE, $name | |
1268 | \& sub mypipe (**) mypipe READHANDLE, WRITEHANDLE | |
1269 | \& sub mygrep (&@) mygrep { /foo/ } $a, $b, $c | |
1270 | \& sub myrand ($) myrand 42 | |
1271 | \& sub mytime () mytime | |
1272 | .Ve | |
1273 | .PP | |
1274 | Any backslashed prototype character represents an actual argument | |
1275 | that absolutely must start with that character. The value passed | |
1276 | as part of \f(CW@_\fR will be a reference to the actual argument given | |
1277 | in the subroutine call, obtained by applying \f(CW\*(C`\e\*(C'\fR to that argument. | |
1278 | .PP | |
1279 | You can also backslash several argument types simultaneously by using | |
1280 | the \f(CW\*(C`\e[]\*(C'\fR notation: | |
1281 | .PP | |
1282 | .Vb 1 | |
1283 | \& sub myref (\e[$@%&*]) | |
1284 | .Ve | |
1285 | .PP | |
1286 | will allow calling \fImyref()\fR as | |
1287 | .PP | |
1288 | .Vb 5 | |
1289 | \& myref $var | |
1290 | \& myref @array | |
1291 | \& myref %hash | |
1292 | \& myref &sub | |
1293 | \& myref *glob | |
1294 | .Ve | |
1295 | .PP | |
1296 | and the first argument of \fImyref()\fR will be a reference to | |
1297 | a scalar, an array, a hash, a code, or a glob. | |
1298 | .PP | |
1299 | Unbackslashed prototype characters have special meanings. Any | |
1300 | unbackslashed \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR eats all remaining arguments, and forces | |
1301 | list context. An argument represented by \f(CW\*(C`$\*(C'\fR forces scalar context. An | |
1302 | \&\f(CW\*(C`&\*(C'\fR requires an anonymous subroutine, which, if passed as the first | |
1303 | argument, does not require the \f(CW\*(C`sub\*(C'\fR keyword or a subsequent comma. | |
1304 | .PP | |
1305 | A \f(CW\*(C`*\*(C'\fR allows the subroutine to accept a bareword, constant, scalar expression, | |
1306 | typeglob, or a reference to a typeglob in that slot. The value will be | |
1307 | available to the subroutine either as a simple scalar, or (in the latter | |
1308 | two cases) as a reference to the typeglob. If you wish to always convert | |
1309 | such arguments to a typeglob reference, use \fISymbol::qualify_to_ref()\fR as | |
1310 | follows: | |
1311 | .PP | |
1312 | .Vb 1 | |
1313 | \& use Symbol 'qualify_to_ref'; | |
1314 | .Ve | |
1315 | .PP | |
1316 | .Vb 4 | |
1317 | \& sub foo (*) { | |
1318 | \& my $fh = qualify_to_ref(shift, caller); | |
1319 | \& ... | |
1320 | \& } | |
1321 | .Ve | |
1322 | .PP | |
1323 | A semicolon separates mandatory arguments from optional arguments. | |
1324 | It is redundant before \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, which gobble up everything else. | |
1325 | .PP | |
1326 | Note how the last three examples in the table above are treated | |
1327 | specially by the parser. \f(CW\*(C`mygrep()\*(C'\fR is parsed as a true list | |
1328 | operator, \f(CW\*(C`myrand()\*(C'\fR is parsed as a true unary operator with unary | |
1329 | precedence the same as \f(CW\*(C`rand()\*(C'\fR, and \f(CW\*(C`mytime()\*(C'\fR is truly without | |
1330 | arguments, just like \f(CW\*(C`time()\*(C'\fR. That is, if you say | |
1331 | .PP | |
1332 | .Vb 1 | |
1333 | \& mytime +2; | |
1334 | .Ve | |
1335 | .PP | |
1336 | you'll get \f(CW\*(C`mytime() + 2\*(C'\fR, not \f(CWmytime(2)\fR, which is how it would be parsed | |
1337 | without a prototype. | |
1338 | .PP | |
1339 | The interesting thing about \f(CW\*(C`&\*(C'\fR is that you can generate new syntax with it, | |
1340 | provided it's in the initial position: | |
1341 | .IX Xref "&" | |
1342 | .PP | |
1343 | .Vb 9 | |
1344 | \& sub try (&@) { | |
1345 | \& my($try,$catch) = @_; | |
1346 | \& eval { &$try }; | |
1347 | \& if ($@) { | |
1348 | \& local $_ = $@; | |
1349 | \& &$catch; | |
1350 | \& } | |
1351 | \& } | |
1352 | \& sub catch (&) { $_[0] } | |
1353 | .Ve | |
1354 | .PP | |
1355 | .Vb 5 | |
1356 | \& try { | |
1357 | \& die "phooey"; | |
1358 | \& } catch { | |
1359 | \& /phooey/ and print "unphooey\en"; | |
1360 | \& }; | |
1361 | .Ve | |
1362 | .PP | |
1363 | That prints \f(CW"unphooey"\fR. (Yes, there are still unresolved | |
1364 | issues having to do with visibility of \f(CW@_\fR. I'm ignoring that | |
1365 | question for the moment. (But note that if we make \f(CW@_\fR lexically | |
1366 | scoped, those anonymous subroutines can act like closures... (Gee, | |
1367 | is this sounding a little Lispish? (Never mind.)))) | |
1368 | .PP | |
1369 | And here's a reimplementation of the Perl \f(CW\*(C`grep\*(C'\fR operator: | |
1370 | .IX Xref "grep" | |
1371 | .PP | |
1372 | .Vb 8 | |
1373 | \& sub mygrep (&@) { | |
1374 | \& my $code = shift; | |
1375 | \& my @result; | |
1376 | \& foreach $_ (@_) { | |
1377 | \& push(@result, $_) if &$code; | |
1378 | \& } | |
1379 | \& @result; | |
1380 | \& } | |
1381 | .Ve | |
1382 | .PP | |
1383 | Some folks would prefer full alphanumeric prototypes. Alphanumerics have | |
1384 | been intentionally left out of prototypes for the express purpose of | |
1385 | someday in the future adding named, formal parameters. The current | |
1386 | mechanism's main goal is to let module writers provide better diagnostics | |
1387 | for module users. Larry feels the notation quite understandable to Perl | |
1388 | programmers, and that it will not intrude greatly upon the meat of the | |
1389 | module, nor make it harder to read. The line noise is visually | |
1390 | encapsulated into a small pill that's easy to swallow. | |
1391 | .PP | |
1392 | If you try to use an alphanumeric sequence in a prototype you will | |
1393 | generate an optional warning \- \*(L"Illegal character in prototype...\*(R". | |
1394 | Unfortunately earlier versions of Perl allowed the prototype to be | |
1395 | used as long as its prefix was a valid prototype. The warning may be | |
1396 | upgraded to a fatal error in a future version of Perl once the | |
1397 | majority of offending code is fixed. | |
1398 | .PP | |
1399 | It's probably best to prototype new functions, not retrofit prototyping | |
1400 | into older ones. That's because you must be especially careful about | |
1401 | silent impositions of differing list versus scalar contexts. For example, | |
1402 | if you decide that a function should take just one parameter, like this: | |
1403 | .PP | |
1404 | .Vb 4 | |
1405 | \& sub func ($) { | |
1406 | \& my $n = shift; | |
1407 | \& print "you gave me $n\en"; | |
1408 | \& } | |
1409 | .Ve | |
1410 | .PP | |
1411 | and someone has been calling it with an array or expression | |
1412 | returning a list: | |
1413 | .PP | |
1414 | .Vb 2 | |
1415 | \& func(@foo); | |
1416 | \& func( split /:/ ); | |
1417 | .Ve | |
1418 | .PP | |
1419 | Then you've just supplied an automatic \f(CW\*(C`scalar\*(C'\fR in front of their | |
1420 | argument, which can be more than a bit surprising. The old \f(CW@foo\fR | |
1421 | which used to hold one thing doesn't get passed in. Instead, | |
1422 | \&\f(CW\*(C`func()\*(C'\fR now gets passed in a \f(CW1\fR; that is, the number of elements | |
1423 | in \f(CW@foo\fR. And the \f(CW\*(C`split\*(C'\fR gets called in scalar context so it | |
1424 | starts scribbling on your \f(CW@_\fR parameter list. Ouch! | |
1425 | .PP | |
1426 | This is all very powerful, of course, and should be used only in moderation | |
1427 | to make the world a better place. | |
1428 | .Sh "Constant Functions" | |
1429 | .IX Xref "constant" | |
1430 | .IX Subsection "Constant Functions" | |
1431 | Functions with a prototype of \f(CW\*(C`()\*(C'\fR are potential candidates for | |
1432 | inlining. If the result after optimization and constant folding | |
1433 | is either a constant or a lexically-scoped scalar which has no other | |
1434 | references, then it will be used in place of function calls made | |
1435 | without \f(CW\*(C`&\*(C'\fR. Calls made using \f(CW\*(C`&\*(C'\fR are never inlined. (See | |
1436 | \&\fIconstant.pm\fR for an easy way to declare most constants.) | |
1437 | .PP | |
1438 | The following functions would all be inlined: | |
1439 | .PP | |
1440 | .Vb 5 | |
1441 | \& sub pi () { 3.14159 } # Not exact, but close. | |
1442 | \& sub PI () { 4 * atan2 1, 1 } # As good as it gets, | |
1443 | \& # and it's inlined, too! | |
1444 | \& sub ST_DEV () { 0 } | |
1445 | \& sub ST_INO () { 1 } | |
1446 | .Ve | |
1447 | .PP | |
1448 | .Vb 3 | |
1449 | \& sub FLAG_FOO () { 1 << 8 } | |
1450 | \& sub FLAG_BAR () { 1 << 9 } | |
1451 | \& sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } | |
1452 | .Ve | |
1453 | .PP | |
1454 | .Vb 1 | |
1455 | \& sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } | |
1456 | .Ve | |
1457 | .PP | |
1458 | .Vb 1 | |
1459 | \& sub N () { int(OPT_BAZ) / 3 } | |
1460 | .Ve | |
1461 | .PP | |
1462 | .Vb 1 | |
1463 | \& sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO } | |
1464 | .Ve | |
1465 | .PP | |
1466 | Be aware that these will not be inlined; as they contain inner scopes, | |
1467 | the constant folding doesn't reduce them to a single constant: | |
1468 | .PP | |
1469 | .Vb 1 | |
1470 | \& sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } } | |
1471 | .Ve | |
1472 | .PP | |
1473 | .Vb 8 | |
1474 | \& sub baz_val () { | |
1475 | \& if (OPT_BAZ) { | |
1476 | \& return 23; | |
1477 | \& } | |
1478 | \& else { | |
1479 | \& return 42; | |
1480 | \& } | |
1481 | \& } | |
1482 | .Ve | |
1483 | .PP | |
1484 | If you redefine a subroutine that was eligible for inlining, you'll get | |
1485 | a mandatory warning. (You can use this warning to tell whether or not a | |
1486 | particular subroutine is considered constant.) The warning is | |
1487 | considered severe enough not to be optional because previously compiled | |
1488 | invocations of the function will still be using the old value of the | |
1489 | function. If you need to be able to redefine the subroutine, you need to | |
1490 | ensure that it isn't inlined, either by dropping the \f(CW\*(C`()\*(C'\fR prototype | |
1491 | (which changes calling semantics, so beware) or by thwarting the | |
1492 | inlining mechanism in some other way, such as | |
1493 | .PP | |
1494 | .Vb 3 | |
1495 | \& sub not_inlined () { | |
1496 | \& 23 if $]; | |
1497 | \& } | |
1498 | .Ve | |
1499 | .Sh "Overriding Built-in Functions" | |
1500 | .IX Xref "built-in override CORE CORE::GLOBAL" | |
1501 | .IX Subsection "Overriding Built-in Functions" | |
1502 | Many built-in functions may be overridden, though this should be tried | |
1503 | only occasionally and for good reason. Typically this might be | |
1504 | done by a package attempting to emulate missing built-in functionality | |
1505 | on a non-Unix system. | |
1506 | .PP | |
1507 | Overriding may be done only by importing the name from a module at | |
1508 | compile time\*(--ordinary predeclaration isn't good enough. However, the | |
1509 | \&\f(CW\*(C`use subs\*(C'\fR pragma lets you, in effect, predeclare subs | |
1510 | via the import syntax, and these names may then override built-in ones: | |
1511 | .PP | |
1512 | .Vb 3 | |
1513 | \& use subs 'chdir', 'chroot', 'chmod', 'chown'; | |
1514 | \& chdir $somewhere; | |
1515 | \& sub chdir { ... } | |
1516 | .Ve | |
1517 | .PP | |
1518 | To unambiguously refer to the built-in form, precede the | |
1519 | built-in name with the special package qualifier \f(CW\*(C`CORE::\*(C'\fR. For example, | |
1520 | saying \f(CW\*(C`CORE::open()\*(C'\fR always refers to the built-in \f(CW\*(C`open()\*(C'\fR, even | |
1521 | if the current package has imported some other subroutine called | |
1522 | \&\f(CW\*(C`&open()\*(C'\fR from elsewhere. Even though it looks like a regular | |
1523 | function call, it isn't: you can't take a reference to it, such as | |
1524 | the incorrect \f(CW\*(C`\e&CORE::open\*(C'\fR might appear to produce. | |
1525 | .PP | |
1526 | Library modules should not in general export built-in names like \f(CW\*(C`open\*(C'\fR | |
1527 | or \f(CW\*(C`chdir\*(C'\fR as part of their default \f(CW@EXPORT\fR list, because these may | |
1528 | sneak into someone else's namespace and change the semantics unexpectedly. | |
1529 | Instead, if the module adds that name to \f(CW@EXPORT_OK\fR, then it's | |
1530 | possible for a user to import the name explicitly, but not implicitly. | |
1531 | That is, they could say | |
1532 | .PP | |
1533 | .Vb 1 | |
1534 | \& use Module 'open'; | |
1535 | .Ve | |
1536 | .PP | |
1537 | and it would import the \f(CW\*(C`open\*(C'\fR override. But if they said | |
1538 | .PP | |
1539 | .Vb 1 | |
1540 | \& use Module; | |
1541 | .Ve | |
1542 | .PP | |
1543 | they would get the default imports without overrides. | |
1544 | .PP | |
1545 | The foregoing mechanism for overriding built-in is restricted, quite | |
1546 | deliberately, to the package that requests the import. There is a second | |
1547 | method that is sometimes applicable when you wish to override a built-in | |
1548 | everywhere, without regard to namespace boundaries. This is achieved by | |
1549 | importing a sub into the special namespace \f(CW\*(C`CORE::GLOBAL::\*(C'\fR. Here is an | |
1550 | example that quite brazenly replaces the \f(CW\*(C`glob\*(C'\fR operator with something | |
1551 | that understands regular expressions. | |
1552 | .PP | |
1553 | .Vb 4 | |
1554 | \& package REGlob; | |
1555 | \& require Exporter; | |
1556 | \& @ISA = 'Exporter'; | |
1557 | \& @EXPORT_OK = 'glob'; | |
1558 | .Ve | |
1559 | .PP | |
1560 | .Vb 7 | |
1561 | \& sub import { | |
1562 | \& my $pkg = shift; | |
1563 | \& return unless @_; | |
1564 | \& my $sym = shift; | |
1565 | \& my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0)); | |
1566 | \& $pkg->export($where, $sym, @_); | |
1567 | \& } | |
1568 | .Ve | |
1569 | .PP | |
1570 | .Vb 11 | |
1571 | \& sub glob { | |
1572 | \& my $pat = shift; | |
1573 | \& my @got; | |
1574 | \& local *D; | |
1575 | \& if (opendir D, '.') { | |
1576 | \& @got = grep /$pat/, readdir D; | |
1577 | \& closedir D; | |
1578 | \& } | |
1579 | \& return @got; | |
1580 | \& } | |
1581 | \& 1; | |
1582 | .Ve | |
1583 | .PP | |
1584 | And here's how it could be (ab)used: | |
1585 | .PP | |
1586 | .Vb 4 | |
1587 | \& #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces | |
1588 | \& package Foo; | |
1589 | \& use REGlob 'glob'; # override glob() in Foo:: only | |
1590 | \& print for <^[a-z_]+\e.pm\e$>; # show all pragmatic modules | |
1591 | .Ve | |
1592 | .PP | |
1593 | The initial comment shows a contrived, even dangerous example. | |
1594 | By overriding \f(CW\*(C`glob\*(C'\fR globally, you would be forcing the new (and | |
1595 | subversive) behavior for the \f(CW\*(C`glob\*(C'\fR operator for \fIevery\fR namespace, | |
1596 | without the complete cognizance or cooperation of the modules that own | |
1597 | those namespaces. Naturally, this should be done with extreme caution\*(--if | |
1598 | it must be done at all. | |
1599 | .PP | |
1600 | The \f(CW\*(C`REGlob\*(C'\fR example above does not implement all the support needed to | |
1601 | cleanly override perl's \f(CW\*(C`glob\*(C'\fR operator. The built-in \f(CW\*(C`glob\*(C'\fR has | |
1602 | different behaviors depending on whether it appears in a scalar or list | |
1603 | context, but our \f(CW\*(C`REGlob\*(C'\fR doesn't. Indeed, many perl built-in have such | |
1604 | context sensitive behaviors, and these must be adequately supported by | |
1605 | a properly written override. For a fully functional example of overriding | |
1606 | \&\f(CW\*(C`glob\*(C'\fR, study the implementation of \f(CW\*(C`File::DosGlob\*(C'\fR in the standard | |
1607 | library. | |
1608 | .PP | |
1609 | When you override a built\-in, your replacement should be consistent (if | |
1610 | possible) with the built-in native syntax. You can achieve this by using | |
1611 | a suitable prototype. To get the prototype of an overridable built\-in, | |
1612 | use the \f(CW\*(C`prototype\*(C'\fR function with an argument of \f(CW"CORE::builtin_name"\fR | |
1613 | (see \*(L"prototype\*(R" in perlfunc). | |
1614 | .PP | |
1615 | Note however that some built-ins can't have their syntax expressed by a | |
1616 | prototype (such as \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`chomp\*(C'\fR). If you override them you won't | |
1617 | be able to fully mimic their original syntax. | |
1618 | .PP | |
1619 | The built-ins \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`glob\*(C'\fR can also be overridden, but due | |
1620 | to special magic, their original syntax is preserved, and you don't have | |
1621 | to define a prototype for their replacements. (You can't override the | |
1622 | \&\f(CW\*(C`do BLOCK\*(C'\fR syntax, though). | |
1623 | .PP | |
1624 | \&\f(CW\*(C`require\*(C'\fR has special additional dark magic: if you invoke your | |
1625 | \&\f(CW\*(C`require\*(C'\fR replacement as \f(CW\*(C`require Foo::Bar\*(C'\fR, it will actually receive | |
1626 | the argument \f(CW"Foo/Bar.pm"\fR in \f(CW@_\fR. See \*(L"require\*(R" in perlfunc. | |
1627 | .PP | |
1628 | And, as you'll have noticed from the previous example, if you override | |
1629 | \&\f(CW\*(C`glob\*(C'\fR, the \f(CW\*(C`<*>\*(C'\fR glob operator is overridden as well. | |
1630 | .PP | |
1631 | In a similar fashion, overriding the \f(CW\*(C`readline\*(C'\fR function also overrides | |
1632 | the equivalent I/O operator \f(CW\*(C`<FILEHANDLE>\*(C'\fR. | |
1633 | .PP | |
1634 | Finally, some built-ins (e.g. \f(CW\*(C`exists\*(C'\fR or \f(CW\*(C`grep\*(C'\fR) can't be overridden. | |
1635 | .Sh "Autoloading" | |
1636 | .IX Xref "autoloading AUTOLOAD" | |
1637 | .IX Subsection "Autoloading" | |
1638 | If you call a subroutine that is undefined, you would ordinarily | |
1639 | get an immediate, fatal error complaining that the subroutine doesn't | |
1640 | exist. (Likewise for subroutines being used as methods, when the | |
1641 | method doesn't exist in any base class of the class's package.) | |
1642 | However, if an \f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is defined in the package or | |
1643 | packages used to locate the original subroutine, then that | |
1644 | \&\f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is called with the arguments that would have | |
1645 | been passed to the original subroutine. The fully qualified name | |
1646 | of the original subroutine magically appears in the global \f(CW$AUTOLOAD\fR | |
1647 | variable of the same package as the \f(CW\*(C`AUTOLOAD\*(C'\fR routine. The name | |
1648 | is not passed as an ordinary argument because, er, well, just | |
1649 | because, that's why... | |
1650 | .PP | |
1651 | Many \f(CW\*(C`AUTOLOAD\*(C'\fR routines load in a definition for the requested | |
1652 | subroutine using \fIeval()\fR, then execute that subroutine using a special | |
1653 | form of \fIgoto()\fR that erases the stack frame of the \f(CW\*(C`AUTOLOAD\*(C'\fR routine | |
1654 | without a trace. (See the source to the standard module documented | |
1655 | in AutoLoader, for example.) But an \f(CW\*(C`AUTOLOAD\*(C'\fR routine can | |
1656 | also just emulate the routine and never define it. For example, | |
1657 | let's pretend that a function that wasn't defined should just invoke | |
1658 | \&\f(CW\*(C`system\*(C'\fR with those arguments. All you'd do is: | |
1659 | .PP | |
1660 | .Vb 8 | |
1661 | \& sub AUTOLOAD { | |
1662 | \& my $program = $AUTOLOAD; | |
1663 | \& $program =~ s/.*:://; | |
1664 | \& system($program, @_); | |
1665 | \& } | |
1666 | \& date(); | |
1667 | \& who('am', 'i'); | |
1668 | \& ls('-l'); | |
1669 | .Ve | |
1670 | .PP | |
1671 | In fact, if you predeclare functions you want to call that way, you don't | |
1672 | even need parentheses: | |
1673 | .PP | |
1674 | .Vb 4 | |
1675 | \& use subs qw(date who ls); | |
1676 | \& date; | |
1677 | \& who "am", "i"; | |
1678 | \& ls -l; | |
1679 | .Ve | |
1680 | .PP | |
1681 | A more complete example of this is the standard Shell module, which | |
1682 | can treat undefined subroutine calls as calls to external programs. | |
1683 | .PP | |
1684 | Mechanisms are available to help modules writers split their modules | |
1685 | into autoloadable files. See the standard AutoLoader module | |
1686 | described in AutoLoader and in AutoSplit, the standard | |
1687 | SelfLoader modules in SelfLoader, and the document on adding C | |
1688 | functions to Perl code in perlxs. | |
1689 | .Sh "Subroutine Attributes" | |
1690 | .IX Xref "attribute subroutine, attribute attrs" | |
1691 | .IX Subsection "Subroutine Attributes" | |
1692 | A subroutine declaration or definition may have a list of attributes | |
1693 | associated with it. If such an attribute list is present, it is | |
1694 | broken up at space or colon boundaries and treated as though a | |
1695 | \&\f(CW\*(C`use attributes\*(C'\fR had been seen. See attributes for details | |
1696 | about what attributes are currently supported. | |
1697 | Unlike the limitation with the obsolescent \f(CW\*(C`use attrs\*(C'\fR, the | |
1698 | \&\f(CW\*(C`sub : ATTRLIST\*(C'\fR syntax works to associate the attributes with | |
1699 | a pre\-declaration, and not just with a subroutine definition. | |
1700 | .PP | |
1701 | The attributes must be valid as simple identifier names (without any | |
1702 | punctuation other than the '_' character). They may have a parameter | |
1703 | list appended, which is only checked for whether its parentheses ('(',')') | |
1704 | nest properly. | |
1705 | .PP | |
1706 | Examples of valid syntax (even though the attributes are unknown): | |
1707 | .PP | |
1708 | .Vb 3 | |
1709 | \& sub fnord (&\e%) : switch(10,foo(7,3)) : expensive; | |
1710 | \& sub plugh () : Ugly('\e(") :Bad; | |
1711 | \& sub xyzzy : _5x5 { ... } | |
1712 | .Ve | |
1713 | .PP | |
1714 | Examples of invalid syntax: | |
1715 | .PP | |
1716 | .Vb 5 | |
1717 | \& sub fnord : switch(10,foo(); # ()-string not balanced | |
1718 | \& sub snoid : Ugly('('); # ()-string not balanced | |
1719 | \& sub xyzzy : 5x5; # "5x5" not a valid identifier | |
1720 | \& sub plugh : Y2::north; # "Y2::north" not a simple identifier | |
1721 | \& sub snurt : foo + bar; # "+" not a colon or space | |
1722 | .Ve | |
1723 | .PP | |
1724 | The attribute list is passed as a list of constant strings to the code | |
1725 | which associates them with the subroutine. In particular, the second example | |
1726 | of valid syntax above currently looks like this in terms of how it's | |
1727 | parsed and invoked: | |
1728 | .PP | |
1729 | .Vb 1 | |
1730 | \& use attributes __PACKAGE__, \e&plugh, q[Ugly('\e(")], 'Bad'; | |
1731 | .Ve | |
1732 | .PP | |
1733 | For further details on attribute lists and their manipulation, | |
1734 | see attributes and Attribute::Handlers. | |
1735 | .SH "SEE ALSO" | |
1736 | .IX Header "SEE ALSO" | |
1737 | See \*(L"Function Templates\*(R" in perlref for more about references and closures. | |
1738 | See perlxs if you'd like to learn about calling C subroutines from Perl. | |
1739 | See perlembed if you'd like to learn about calling Perl subroutines from C. | |
1740 | See perlmod to learn about bundling up your functions in separate files. | |
1741 | See perlmodlib to learn what library modules come standard on your system. | |
1742 | See perltoot to learn how to make object method calls. |