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 "PERLREF 1" | |
132 | .TH PERLREF 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | .IX Xref "reference pointer data structure structure struct" | |
135 | perlref \- Perl references and nested data structures | |
136 | .SH "NOTE" | |
137 | .IX Header "NOTE" | |
138 | This is complete documentation about all aspects of references. | |
139 | For a shorter, tutorial introduction to just the essential features, | |
140 | see perlreftut. | |
141 | .SH "DESCRIPTION" | |
142 | .IX Header "DESCRIPTION" | |
143 | Before release 5 of Perl it was difficult to represent complex data | |
144 | structures, because all references had to be symbolic\*(--and even then | |
145 | it was difficult to refer to a variable instead of a symbol table entry. | |
146 | Perl now not only makes it easier to use symbolic references to variables, | |
147 | but also lets you have \*(L"hard\*(R" references to any piece of data or code. | |
148 | Any scalar may hold a hard reference. Because arrays and hashes contain | |
149 | scalars, you can now easily build arrays of arrays, arrays of hashes, | |
150 | hashes of arrays, arrays of hashes of functions, and so on. | |
151 | .PP | |
152 | Hard references are smart\*(--they keep track of reference counts for you, | |
153 | automatically freeing the thing referred to when its reference count goes | |
154 | to zero. (Reference counts for values in self-referential or | |
155 | cyclic data structures may not go to zero without a little help; see | |
156 | \&\*(L"Two\-Phased Garbage Collection\*(R" in perlobj for a detailed explanation.) | |
157 | If that thing happens to be an object, the object is destructed. See | |
158 | perlobj for more about objects. (In a sense, everything in Perl is an | |
159 | object, but we usually reserve the word for references to objects that | |
160 | have been officially \*(L"blessed\*(R" into a class package.) | |
161 | .PP | |
162 | Symbolic references are names of variables or other objects, just as a | |
163 | symbolic link in a Unix filesystem contains merely the name of a file. | |
164 | The \f(CW*glob\fR notation is something of a symbolic reference. (Symbolic | |
165 | references are sometimes called \*(L"soft references\*(R", but please don't call | |
166 | them that; references are confusing enough without useless synonyms.) | |
167 | .IX Xref "reference, symbolic reference, soft symbolic reference soft reference" | |
168 | .PP | |
169 | In contrast, hard references are more like hard links in a Unix file | |
170 | system: They are used to access an underlying object without concern for | |
171 | what its (other) name is. When the word \*(L"reference\*(R" is used without an | |
172 | adjective, as in the following paragraph, it is usually talking about a | |
173 | hard reference. | |
174 | .IX Xref "reference, hard hard reference" | |
175 | .PP | |
176 | References are easy to use in Perl. There is just one overriding | |
177 | principle: Perl does no implicit referencing or dereferencing. When a | |
178 | scalar is holding a reference, it always behaves as a simple scalar. It | |
179 | doesn't magically start being an array or hash or subroutine; you have to | |
180 | tell it explicitly to do so, by dereferencing it. | |
181 | .Sh "Making References" | |
182 | .IX Xref "reference, creation referencing" | |
183 | .IX Subsection "Making References" | |
184 | References can be created in several ways. | |
185 | .IP "1." 4 | |
186 | .IX Xref "\ backslash" | |
187 | By using the backslash operator on a variable, subroutine, or value. | |
188 | (This works much like the & (address\-of) operator in C.) | |
189 | This typically creates \fIanother\fR reference to a variable, because | |
190 | there's already a reference to the variable in the symbol table. But | |
191 | the symbol table reference might go away, and you'll still have the | |
192 | reference that the backslash returned. Here are some examples: | |
193 | .Sp | |
194 | .Vb 5 | |
195 | \& $scalarref = \e$foo; | |
196 | \& $arrayref = \e@ARGV; | |
197 | \& $hashref = \e%ENV; | |
198 | \& $coderef = \e&handler; | |
199 | \& $globref = \e*foo; | |
200 | .Ve | |
201 | .Sp | |
202 | It isn't possible to create a true reference to an \s-1IO\s0 handle (filehandle | |
203 | or dirhandle) using the backslash operator. The most you can get is a | |
204 | reference to a typeglob, which is actually a complete symbol table entry. | |
205 | But see the explanation of the \f(CW*foo{THING}\fR syntax below. However, | |
206 | you can still use type globs and globrefs as though they were \s-1IO\s0 handles. | |
207 | .IP "2." 4 | |
208 | .IX Xref "array, anonymous [ [] square bracket bracket, square arrayref array reference reference, array" | |
209 | A reference to an anonymous array can be created using square | |
210 | brackets: | |
211 | .Sp | |
212 | .Vb 1 | |
213 | \& $arrayref = [1, 2, ['a', 'b', 'c']]; | |
214 | .Ve | |
215 | .Sp | |
216 | Here we've created a reference to an anonymous array of three elements | |
217 | whose final element is itself a reference to another anonymous array of three | |
218 | elements. (The multidimensional syntax described later can be used to | |
219 | access this. For example, after the above, \f(CW\*(C`$arrayref\->[2][1]\*(C'\fR would have | |
220 | the value \*(L"b\*(R".) | |
221 | .Sp | |
222 | Taking a reference to an enumerated list is not the same | |
223 | as using square brackets\*(--instead it's the same as creating | |
224 | a list of references! | |
225 | .Sp | |
226 | .Vb 2 | |
227 | \& @list = (\e$a, \e@b, \e%c); | |
228 | \& @list = \e($a, @b, %c); # same thing! | |
229 | .Ve | |
230 | .Sp | |
231 | As a special case, \f(CW\*(C`\e(@foo)\*(C'\fR returns a list of references to the contents | |
232 | of \f(CW@foo\fR, not a reference to \f(CW@foo\fR itself. Likewise for \f(CW%foo\fR, | |
233 | except that the key references are to copies (since the keys are just | |
234 | strings rather than full-fledged scalars). | |
235 | .IP "3." 4 | |
236 | .IX Xref "hash, anonymous { {} curly bracket bracket, curly brace hashref hash reference reference, hash" | |
237 | A reference to an anonymous hash can be created using curly | |
238 | brackets: | |
239 | .Sp | |
240 | .Vb 4 | |
241 | \& $hashref = { | |
242 | \& 'Adam' => 'Eve', | |
243 | \& 'Clyde' => 'Bonnie', | |
244 | \& }; | |
245 | .Ve | |
246 | .Sp | |
247 | Anonymous hash and array composers like these can be intermixed freely to | |
248 | produce as complicated a structure as you want. The multidimensional | |
249 | syntax described below works for these too. The values above are | |
250 | literals, but variables and expressions would work just as well, because | |
251 | assignment operators in Perl (even within \fIlocal()\fR or \fImy()\fR) are executable | |
252 | statements, not compile-time declarations. | |
253 | .Sp | |
254 | Because curly brackets (braces) are used for several other things | |
255 | including BLOCKs, you may occasionally have to disambiguate braces at the | |
256 | beginning of a statement by putting a \f(CW\*(C`+\*(C'\fR or a \f(CW\*(C`return\*(C'\fR in front so | |
257 | that Perl realizes the opening brace isn't starting a \s-1BLOCK\s0. The economy and | |
258 | mnemonic value of using curlies is deemed worth this occasional extra | |
259 | hassle. | |
260 | .Sp | |
261 | For example, if you wanted a function to make a new hash and return a | |
262 | reference to it, you have these options: | |
263 | .Sp | |
264 | .Vb 3 | |
265 | \& sub hashem { { @_ } } # silently wrong | |
266 | \& sub hashem { +{ @_ } } # ok | |
267 | \& sub hashem { return { @_ } } # ok | |
268 | .Ve | |
269 | .Sp | |
270 | On the other hand, if you want the other meaning, you can do this: | |
271 | .Sp | |
272 | .Vb 3 | |
273 | \& sub showem { { @_ } } # ambiguous (currently ok, but may change) | |
274 | \& sub showem { {; @_ } } # ok | |
275 | \& sub showem { { return @_ } } # ok | |
276 | .Ve | |
277 | .Sp | |
278 | The leading \f(CW\*(C`+{\*(C'\fR and \f(CW\*(C`{;\*(C'\fR always serve to disambiguate | |
279 | the expression to mean either the \s-1HASH\s0 reference, or the \s-1BLOCK\s0. | |
280 | .IP "4." 4 | |
281 | .IX Xref "subroutine, anonymous subroutine, reference reference, subroutine scope, lexical closure lexical lexical scope" | |
282 | A reference to an anonymous subroutine can be created by using | |
283 | \&\f(CW\*(C`sub\*(C'\fR without a subname: | |
284 | .Sp | |
285 | .Vb 1 | |
286 | \& $coderef = sub { print "Boink!\en" }; | |
287 | .Ve | |
288 | .Sp | |
289 | Note the semicolon. Except for the code | |
290 | inside not being immediately executed, a \f(CW\*(C`sub {}\*(C'\fR is not so much a | |
291 | declaration as it is an operator, like \f(CW\*(C`do{}\*(C'\fR or \f(CW\*(C`eval{}\*(C'\fR. (However, no | |
292 | matter how many times you execute that particular line (unless you're in an | |
293 | \&\f(CW\*(C`eval("...")\*(C'\fR), \f(CW$coderef\fR will still have a reference to the \fIsame\fR | |
294 | anonymous subroutine.) | |
295 | .Sp | |
296 | Anonymous subroutines act as closures with respect to \fImy()\fR variables, | |
297 | that is, variables lexically visible within the current scope. Closure | |
298 | is a notion out of the Lisp world that says if you define an anonymous | |
299 | function in a particular lexical context, it pretends to run in that | |
300 | context even when it's called outside the context. | |
301 | .Sp | |
302 | In human terms, it's a funny way of passing arguments to a subroutine when | |
303 | you define it as well as when you call it. It's useful for setting up | |
304 | little bits of code to run later, such as callbacks. You can even | |
305 | do object-oriented stuff with it, though Perl already provides a different | |
306 | mechanism to do that\*(--see perlobj. | |
307 | .Sp | |
308 | You might also think of closure as a way to write a subroutine | |
309 | template without using \fIeval()\fR. Here's a small example of how | |
310 | closures work: | |
311 | .Sp | |
312 | .Vb 6 | |
313 | \& sub newprint { | |
314 | \& my $x = shift; | |
315 | \& return sub { my $y = shift; print "$x, $y!\en"; }; | |
316 | \& } | |
317 | \& $h = newprint("Howdy"); | |
318 | \& $g = newprint("Greetings"); | |
319 | .Ve | |
320 | .Sp | |
321 | .Vb 1 | |
322 | \& # Time passes... | |
323 | .Ve | |
324 | .Sp | |
325 | .Vb 2 | |
326 | \& &$h("world"); | |
327 | \& &$g("earthlings"); | |
328 | .Ve | |
329 | .Sp | |
330 | This prints | |
331 | .Sp | |
332 | .Vb 2 | |
333 | \& Howdy, world! | |
334 | \& Greetings, earthlings! | |
335 | .Ve | |
336 | .Sp | |
337 | Note particularly that \f(CW$x\fR continues to refer to the value passed | |
338 | into \fInewprint()\fR \fIdespite\fR \*(L"my \f(CW$x\fR\*(R" having gone out of scope by the | |
339 | time the anonymous subroutine runs. That's what a closure is all | |
340 | about. | |
341 | .Sp | |
342 | This applies only to lexical variables, by the way. Dynamic variables | |
343 | continue to work as they have always worked. Closure is not something | |
344 | that most Perl programmers need trouble themselves about to begin with. | |
345 | .IP "5." 4 | |
346 | .IX Xref "constructor new" | |
347 | References are often returned by special subroutines called constructors. | |
348 | Perl objects are just references to a special type of object that happens to know | |
349 | which package it's associated with. Constructors are just special | |
350 | subroutines that know how to create that association. They do so by | |
351 | starting with an ordinary reference, and it remains an ordinary reference | |
352 | even while it's also being an object. Constructors are often | |
353 | named \fInew()\fR and called indirectly: | |
354 | .Sp | |
355 | .Vb 1 | |
356 | \& $objref = new Doggie (Tail => 'short', Ears => 'long'); | |
357 | .Ve | |
358 | .Sp | |
359 | But don't have to be: | |
360 | .Sp | |
361 | .Vb 1 | |
362 | \& $objref = Doggie->new(Tail => 'short', Ears => 'long'); | |
363 | .Ve | |
364 | .Sp | |
365 | .Vb 2 | |
366 | \& use Term::Cap; | |
367 | \& $terminal = Term::Cap->Tgetent( { OSPEED => 9600 }); | |
368 | .Ve | |
369 | .Sp | |
370 | .Vb 4 | |
371 | \& use Tk; | |
372 | \& $main = MainWindow->new(); | |
373 | \& $menubar = $main->Frame(-relief => "raised", | |
374 | \& -borderwidth => 2) | |
375 | .Ve | |
376 | .IP "6." 4 | |
377 | .IX Xref "autovivification" | |
378 | References of the appropriate type can spring into existence if you | |
379 | dereference them in a context that assumes they exist. Because we haven't | |
380 | talked about dereferencing yet, we can't show you any examples yet. | |
381 | .IP "7." 4 | |
382 | .IX Xref "*foo{THING} *" | |
383 | A reference can be created by using a special syntax, lovingly known as | |
384 | the *foo{\s-1THING\s0} syntax. *foo{\s-1THING\s0} returns a reference to the \s-1THING\s0 | |
385 | slot in *foo (which is the symbol table entry which holds everything | |
386 | known as foo). | |
387 | .Sp | |
388 | .Vb 7 | |
389 | \& $scalarref = *foo{SCALAR}; | |
390 | \& $arrayref = *ARGV{ARRAY}; | |
391 | \& $hashref = *ENV{HASH}; | |
392 | \& $coderef = *handler{CODE}; | |
393 | \& $ioref = *STDIN{IO}; | |
394 | \& $globref = *foo{GLOB}; | |
395 | \& $formatref = *foo{FORMAT}; | |
396 | .Ve | |
397 | .Sp | |
398 | All of these are self-explanatory except for \f(CW*foo{IO}\fR. It returns | |
399 | the \s-1IO\s0 handle, used for file handles (\*(L"open\*(R" in perlfunc), sockets | |
400 | (\*(L"socket\*(R" in perlfunc and \*(L"socketpair\*(R" in perlfunc), and directory | |
401 | handles (\*(L"opendir\*(R" in perlfunc). For compatibility with previous | |
402 | versions of Perl, \f(CW*foo{FILEHANDLE}\fR is a synonym for \f(CW*foo{IO}\fR, though it | |
403 | is deprecated as of 5.8.0. If deprecation warnings are in effect, it will warn | |
404 | of its use. | |
405 | .Sp | |
406 | \&\f(CW*foo{THING}\fR returns undef if that particular \s-1THING\s0 hasn't been used yet, | |
407 | except in the case of scalars. \f(CW*foo{SCALAR}\fR returns a reference to an | |
408 | anonymous scalar if \f(CW$foo\fR hasn't been used yet. This might change in a | |
409 | future release. | |
410 | .Sp | |
411 | \&\f(CW*foo{IO}\fR is an alternative to the \f(CW*HANDLE\fR mechanism given in | |
412 | \&\*(L"Typeglobs and Filehandles\*(R" in perldata for passing filehandles | |
413 | into or out of subroutines, or storing into larger data structures. | |
414 | Its disadvantage is that it won't create a new filehandle for you. | |
415 | Its advantage is that you have less risk of clobbering more than | |
416 | you want to with a typeglob assignment. (It still conflates file | |
417 | and directory handles, though.) However, if you assign the incoming | |
418 | value to a scalar instead of a typeglob as we do in the examples | |
419 | below, there's no risk of that happening. | |
420 | .Sp | |
421 | .Vb 2 | |
422 | \& splutter(*STDOUT); # pass the whole glob | |
423 | \& splutter(*STDOUT{IO}); # pass both file and dir handles | |
424 | .Ve | |
425 | .Sp | |
426 | .Vb 4 | |
427 | \& sub splutter { | |
428 | \& my $fh = shift; | |
429 | \& print $fh "her um well a hmmm\en"; | |
430 | \& } | |
431 | .Ve | |
432 | .Sp | |
433 | .Vb 2 | |
434 | \& $rec = get_rec(*STDIN); # pass the whole glob | |
435 | \& $rec = get_rec(*STDIN{IO}); # pass both file and dir handles | |
436 | .Ve | |
437 | .Sp | |
438 | .Vb 4 | |
439 | \& sub get_rec { | |
440 | \& my $fh = shift; | |
441 | \& return scalar <$fh>; | |
442 | \& } | |
443 | .Ve | |
444 | .Sh "Using References" | |
445 | .IX Xref "reference, use dereferencing dereference" | |
446 | .IX Subsection "Using References" | |
447 | That's it for creating references. By now you're probably dying to | |
448 | know how to use references to get back to your long-lost data. There | |
449 | are several basic methods. | |
450 | .IP "1." 4 | |
451 | Anywhere you'd put an identifier (or chain of identifiers) as part | |
452 | of a variable or subroutine name, you can replace the identifier with | |
453 | a simple scalar variable containing a reference of the correct type: | |
454 | .Sp | |
455 | .Vb 6 | |
456 | \& $bar = $$scalarref; | |
457 | \& push(@$arrayref, $filename); | |
458 | \& $$arrayref[0] = "January"; | |
459 | \& $$hashref{"KEY"} = "VALUE"; | |
460 | \& &$coderef(1,2,3); | |
461 | \& print $globref "output\en"; | |
462 | .Ve | |
463 | .Sp | |
464 | It's important to understand that we are specifically \fInot\fR dereferencing | |
465 | \&\f(CW$arrayref[0]\fR or \f(CW$hashref{"KEY"}\fR there. The dereference of the | |
466 | scalar variable happens \fIbefore\fR it does any key lookups. Anything more | |
467 | complicated than a simple scalar variable must use methods 2 or 3 below. | |
468 | However, a \*(L"simple scalar\*(R" includes an identifier that itself uses method | |
469 | 1 recursively. Therefore, the following prints \*(L"howdy\*(R". | |
470 | .Sp | |
471 | .Vb 2 | |
472 | \& $refrefref = \e\e\e"howdy"; | |
473 | \& print $$$$refrefref; | |
474 | .Ve | |
475 | .IP "2." 4 | |
476 | .IX Xref "${} @{} %{}" | |
477 | Anywhere you'd put an identifier (or chain of identifiers) as part of a | |
478 | variable or subroutine name, you can replace the identifier with a | |
479 | \&\s-1BLOCK\s0 returning a reference of the correct type. In other words, the | |
480 | previous examples could be written like this: | |
481 | .Sp | |
482 | .Vb 6 | |
483 | \& $bar = ${$scalarref}; | |
484 | \& push(@{$arrayref}, $filename); | |
485 | \& ${$arrayref}[0] = "January"; | |
486 | \& ${$hashref}{"KEY"} = "VALUE"; | |
487 | \& &{$coderef}(1,2,3); | |
488 | \& $globref->print("output\en"); # iff IO::Handle is loaded | |
489 | .Ve | |
490 | .Sp | |
491 | Admittedly, it's a little silly to use the curlies in this case, but | |
492 | the \s-1BLOCK\s0 can contain any arbitrary expression, in particular, | |
493 | subscripted expressions: | |
494 | .Sp | |
495 | .Vb 1 | |
496 | \& &{ $dispatch{$index} }(1,2,3); # call correct routine | |
497 | .Ve | |
498 | .Sp | |
499 | Because of being able to omit the curlies for the simple case of \f(CW$$x\fR, | |
500 | people often make the mistake of viewing the dereferencing symbols as | |
501 | proper operators, and wonder about their precedence. If they were, | |
502 | though, you could use parentheses instead of braces. That's not the case. | |
503 | Consider the difference below; case 0 is a short-hand version of case 1, | |
504 | \&\fInot\fR case 2: | |
505 | .Sp | |
506 | .Vb 4 | |
507 | \& $$hashref{"KEY"} = "VALUE"; # CASE 0 | |
508 | \& ${$hashref}{"KEY"} = "VALUE"; # CASE 1 | |
509 | \& ${$hashref{"KEY"}} = "VALUE"; # CASE 2 | |
510 | \& ${$hashref->{"KEY"}} = "VALUE"; # CASE 3 | |
511 | .Ve | |
512 | .Sp | |
513 | Case 2 is also deceptive in that you're accessing a variable | |
514 | called \f(CW%hashref\fR, not dereferencing through \f(CW$hashref\fR to the hash | |
515 | it's presumably referencing. That would be case 3. | |
516 | .IP "3." 4 | |
517 | .IX Xref "autovivification -> arrow" | |
518 | Subroutine calls and lookups of individual array elements arise often | |
519 | enough that it gets cumbersome to use method 2. As a form of | |
520 | syntactic sugar, the examples for method 2 may be written: | |
521 | .Sp | |
522 | .Vb 3 | |
523 | \& $arrayref->[0] = "January"; # Array element | |
524 | \& $hashref->{"KEY"} = "VALUE"; # Hash element | |
525 | \& $coderef->(1,2,3); # Subroutine call | |
526 | .Ve | |
527 | .Sp | |
528 | The left side of the arrow can be any expression returning a reference, | |
529 | including a previous dereference. Note that \f(CW$array[$x]\fR is \fInot\fR the | |
530 | same thing as \f(CW\*(C`$array\->[$x]\*(C'\fR here: | |
531 | .Sp | |
532 | .Vb 1 | |
533 | \& $array[$x]->{"foo"}->[0] = "January"; | |
534 | .Ve | |
535 | .Sp | |
536 | This is one of the cases we mentioned earlier in which references could | |
537 | spring into existence when in an lvalue context. Before this | |
538 | statement, \f(CW$array[$x]\fR may have been undefined. If so, it's | |
539 | automatically defined with a hash reference so that we can look up | |
540 | \&\f(CW\*(C`{"foo"}\*(C'\fR in it. Likewise \f(CW\*(C`$array[$x]\->{"foo"}\*(C'\fR will automatically get | |
541 | defined with an array reference so that we can look up \f(CW\*(C`[0]\*(C'\fR in it. | |
542 | This process is called \fIautovivification\fR. | |
543 | .Sp | |
544 | One more thing here. The arrow is optional \fIbetween\fR brackets | |
545 | subscripts, so you can shrink the above down to | |
546 | .Sp | |
547 | .Vb 1 | |
548 | \& $array[$x]{"foo"}[0] = "January"; | |
549 | .Ve | |
550 | .Sp | |
551 | Which, in the degenerate case of using only ordinary arrays, gives you | |
552 | multidimensional arrays just like C's: | |
553 | .Sp | |
554 | .Vb 1 | |
555 | \& $score[$x][$y][$z] += 42; | |
556 | .Ve | |
557 | .Sp | |
558 | Well, okay, not entirely like C's arrays, actually. C doesn't know how | |
559 | to grow its arrays on demand. Perl does. | |
560 | .IP "4." 4 | |
561 | .IX Xref "encapsulation" | |
562 | If a reference happens to be a reference to an object, then there are | |
563 | probably methods to access the things referred to, and you should probably | |
564 | stick to those methods unless you're in the class package that defines the | |
565 | object's methods. In other words, be nice, and don't violate the object's | |
566 | encapsulation without a very good reason. Perl does not enforce | |
567 | encapsulation. We are not totalitarians here. We do expect some basic | |
568 | civility though. | |
569 | .PP | |
570 | Using a string or number as a reference produces a symbolic reference, | |
571 | as explained above. Using a reference as a number produces an | |
572 | integer representing its storage location in memory. The only | |
573 | useful thing to be done with this is to compare two references | |
574 | numerically to see whether they refer to the same location. | |
575 | .IX Xref "reference, numeric context" | |
576 | .PP | |
577 | .Vb 3 | |
578 | \& if ($ref1 == $ref2) { # cheap numeric compare of references | |
579 | \& print "refs 1 and 2 refer to the same thing\en"; | |
580 | \& } | |
581 | .Ve | |
582 | .PP | |
583 | Using a reference as a string produces both its referent's type, | |
584 | including any package blessing as described in perlobj, as well | |
585 | as the numeric address expressed in hex. The \fIref()\fR operator returns | |
586 | just the type of thing the reference is pointing to, without the | |
587 | address. See \*(L"ref\*(R" in perlfunc for details and examples of its use. | |
588 | .IX Xref "reference, string context" | |
589 | .PP | |
590 | The \fIbless()\fR operator may be used to associate the object a reference | |
591 | points to with a package functioning as an object class. See perlobj. | |
592 | .PP | |
593 | A typeglob may be dereferenced the same way a reference can, because | |
594 | the dereference syntax always indicates the type of reference desired. | |
595 | So \f(CW\*(C`${*foo}\*(C'\fR and \f(CW\*(C`${\e$foo}\*(C'\fR both indicate the same scalar variable. | |
596 | .PP | |
597 | Here's a trick for interpolating a subroutine call into a string: | |
598 | .PP | |
599 | .Vb 1 | |
600 | \& print "My sub returned @{[mysub(1,2,3)]} that time.\en"; | |
601 | .Ve | |
602 | .PP | |
603 | The way it works is that when the \f(CW\*(C`@{...}\*(C'\fR is seen in the double-quoted | |
604 | string, it's evaluated as a block. The block creates a reference to an | |
605 | anonymous array containing the results of the call to \f(CW\*(C`mysub(1,2,3)\*(C'\fR. So | |
606 | the whole block returns a reference to an array, which is then | |
607 | dereferenced by \f(CW\*(C`@{...}\*(C'\fR and stuck into the double-quoted string. This | |
608 | chicanery is also useful for arbitrary expressions: | |
609 | .PP | |
610 | .Vb 1 | |
611 | \& print "That yields @{[$n + 5]} widgets\en"; | |
612 | .Ve | |
613 | .Sh "Symbolic references" | |
614 | .IX Xref "reference, symbolic reference, soft symbolic reference soft reference" | |
615 | .IX Subsection "Symbolic references" | |
616 | We said that references spring into existence as necessary if they are | |
617 | undefined, but we didn't say what happens if a value used as a | |
618 | reference is already defined, but \fIisn't\fR a hard reference. If you | |
619 | use it as a reference, it'll be treated as a symbolic | |
620 | reference. That is, the value of the scalar is taken to be the \fIname\fR | |
621 | of a variable, rather than a direct link to a (possibly) anonymous | |
622 | value. | |
623 | .PP | |
624 | People frequently expect it to work like this. So it does. | |
625 | .PP | |
626 | .Vb 9 | |
627 | \& $name = "foo"; | |
628 | \& $$name = 1; # Sets $foo | |
629 | \& ${$name} = 2; # Sets $foo | |
630 | \& ${$name x 2} = 3; # Sets $foofoo | |
631 | \& $name->[0] = 4; # Sets $foo[0] | |
632 | \& @$name = (); # Clears @foo | |
633 | \& &$name(); # Calls &foo() (as in Perl 4) | |
634 | \& $pack = "THAT"; | |
635 | \& ${"${pack}::$name"} = 5; # Sets $THAT::foo without eval | |
636 | .Ve | |
637 | .PP | |
638 | This is powerful, and slightly dangerous, in that it's possible | |
639 | to intend (with the utmost sincerity) to use a hard reference, and | |
640 | accidentally use a symbolic reference instead. To protect against | |
641 | that, you can say | |
642 | .PP | |
643 | .Vb 1 | |
644 | \& use strict 'refs'; | |
645 | .Ve | |
646 | .PP | |
647 | and then only hard references will be allowed for the rest of the enclosing | |
648 | block. An inner block may countermand that with | |
649 | .PP | |
650 | .Vb 1 | |
651 | \& no strict 'refs'; | |
652 | .Ve | |
653 | .PP | |
654 | Only package variables (globals, even if localized) are visible to | |
655 | symbolic references. Lexical variables (declared with \fImy()\fR) aren't in | |
656 | a symbol table, and thus are invisible to this mechanism. For example: | |
657 | .PP | |
658 | .Vb 6 | |
659 | \& local $value = 10; | |
660 | \& $ref = "value"; | |
661 | \& { | |
662 | \& my $value = 20; | |
663 | \& print $$ref; | |
664 | \& } | |
665 | .Ve | |
666 | .PP | |
667 | This will still print 10, not 20. Remember that \fIlocal()\fR affects package | |
668 | variables, which are all \*(L"global\*(R" to the package. | |
669 | .Sh "Not-so-symbolic references" | |
670 | .IX Subsection "Not-so-symbolic references" | |
671 | A new feature contributing to readability in perl version 5.001 is that the | |
672 | brackets around a symbolic reference behave more like quotes, just as they | |
673 | always have within a string. That is, | |
674 | .PP | |
675 | .Vb 2 | |
676 | \& $push = "pop on "; | |
677 | \& print "${push}over"; | |
678 | .Ve | |
679 | .PP | |
680 | has always meant to print \*(L"pop on over\*(R", even though push is | |
681 | a reserved word. This has been generalized to work the same outside | |
682 | of quotes, so that | |
683 | .PP | |
684 | .Vb 1 | |
685 | \& print ${push} . "over"; | |
686 | .Ve | |
687 | .PP | |
688 | and even | |
689 | .PP | |
690 | .Vb 1 | |
691 | \& print ${ push } . "over"; | |
692 | .Ve | |
693 | .PP | |
694 | will have the same effect. (This would have been a syntax error in | |
695 | Perl 5.000, though Perl 4 allowed it in the spaceless form.) This | |
696 | construct is \fInot\fR considered to be a symbolic reference when you're | |
697 | using strict refs: | |
698 | .PP | |
699 | .Vb 3 | |
700 | \& use strict 'refs'; | |
701 | \& ${ bareword }; # Okay, means $bareword. | |
702 | \& ${ "bareword" }; # Error, symbolic reference. | |
703 | .Ve | |
704 | .PP | |
705 | Similarly, because of all the subscripting that is done using single | |
706 | words, we've applied the same rule to any bareword that is used for | |
707 | subscripting a hash. So now, instead of writing | |
708 | .PP | |
709 | .Vb 1 | |
710 | \& $array{ "aaa" }{ "bbb" }{ "ccc" } | |
711 | .Ve | |
712 | .PP | |
713 | you can write just | |
714 | .PP | |
715 | .Vb 1 | |
716 | \& $array{ aaa }{ bbb }{ ccc } | |
717 | .Ve | |
718 | .PP | |
719 | and not worry about whether the subscripts are reserved words. In the | |
720 | rare event that you do wish to do something like | |
721 | .PP | |
722 | .Vb 1 | |
723 | \& $array{ shift } | |
724 | .Ve | |
725 | .PP | |
726 | you can force interpretation as a reserved word by adding anything that | |
727 | makes it more than a bareword: | |
728 | .PP | |
729 | .Vb 3 | |
730 | \& $array{ shift() } | |
731 | \& $array{ +shift } | |
732 | \& $array{ shift @_ } | |
733 | .Ve | |
734 | .PP | |
735 | The \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR switch will warn you if it | |
736 | interprets a reserved word as a string. | |
737 | But it will no longer warn you about using lowercase words, because the | |
738 | string is effectively quoted. | |
739 | .Sh "Pseudo\-hashes: Using an array as a hash" | |
740 | .IX Xref "pseudo-hash pseudo hash pseudohash" | |
741 | .IX Subsection "Pseudo-hashes: Using an array as a hash" | |
742 | \&\fB\s-1WARNING\s0\fR: This section describes an experimental feature. Details may | |
743 | change without notice in future versions. | |
744 | .PP | |
745 | \&\fB\s-1NOTE\s0\fR: The current user-visible implementation of pseudo-hashes | |
746 | (the weird use of the first array element) is deprecated starting from | |
747 | Perl 5.8.0 and will be removed in Perl 5.10.0, and the feature will be | |
748 | implemented differently. Not only is the current interface rather ugly, | |
749 | but the current implementation slows down normal array and hash use quite | |
750 | noticeably. The 'fields' pragma interface will remain available. | |
751 | .PP | |
752 | Beginning with release 5.005 of Perl, you may use an array reference | |
753 | in some contexts that would normally require a hash reference. This | |
754 | allows you to access array elements using symbolic names, as if they | |
755 | were fields in a structure. | |
756 | .PP | |
757 | For this to work, the array must contain extra information. The first | |
758 | element of the array has to be a hash reference that maps field names | |
759 | to array indices. Here is an example: | |
760 | .PP | |
761 | .Vb 1 | |
762 | \& $struct = [{foo => 1, bar => 2}, "FOO", "BAR"]; | |
763 | .Ve | |
764 | .PP | |
765 | .Vb 2 | |
766 | \& $struct->{foo}; # same as $struct->[1], i.e. "FOO" | |
767 | \& $struct->{bar}; # same as $struct->[2], i.e. "BAR" | |
768 | .Ve | |
769 | .PP | |
770 | .Vb 2 | |
771 | \& keys %$struct; # will return ("foo", "bar") in some order | |
772 | \& values %$struct; # will return ("FOO", "BAR") in same some order | |
773 | .Ve | |
774 | .PP | |
775 | .Vb 3 | |
776 | \& while (my($k,$v) = each %$struct) { | |
777 | \& print "$k => $v\en"; | |
778 | \& } | |
779 | .Ve | |
780 | .PP | |
781 | Perl will raise an exception if you try to access nonexistent fields. | |
782 | To avoid inconsistencies, always use the \fIfields::phash()\fR function | |
783 | provided by the \f(CW\*(C`fields\*(C'\fR pragma. | |
784 | .PP | |
785 | .Vb 2 | |
786 | \& use fields; | |
787 | \& $pseudohash = fields::phash(foo => "FOO", bar => "BAR"); | |
788 | .Ve | |
789 | .PP | |
790 | For better performance, Perl can also do the translation from field | |
791 | names to array indices at compile time for typed object references. | |
792 | See fields. | |
793 | .PP | |
794 | There are two ways to check for the existence of a key in a | |
795 | pseudo\-hash. The first is to use \fIexists()\fR. This checks to see if the | |
796 | given field has ever been set. It acts this way to match the behavior | |
797 | of a regular hash. For instance: | |
798 | .PP | |
799 | .Vb 3 | |
800 | \& use fields; | |
801 | \& $phash = fields::phash([qw(foo bar pants)], ['FOO']); | |
802 | \& $phash->{pants} = undef; | |
803 | .Ve | |
804 | .PP | |
805 | .Vb 3 | |
806 | \& print exists $phash->{foo}; # true, 'foo' was set in the declaration | |
807 | \& print exists $phash->{bar}; # false, 'bar' has not been used. | |
808 | \& print exists $phash->{pants}; # true, your 'pants' have been touched | |
809 | .Ve | |
810 | .PP | |
811 | The second is to use \fIexists()\fR on the hash reference sitting in the | |
812 | first array element. This checks to see if the given key is a valid | |
813 | field in the pseudo\-hash. | |
814 | .PP | |
815 | .Vb 2 | |
816 | \& print exists $phash->[0]{bar}; # true, 'bar' is a valid field | |
817 | \& print exists $phash->[0]{shoes};# false, 'shoes' can't be used | |
818 | .Ve | |
819 | .PP | |
820 | \&\fIdelete()\fR on a pseudo-hash element only deletes the value corresponding | |
821 | to the key, not the key itself. To delete the key, you'll have to | |
822 | explicitly delete it from the first hash element. | |
823 | .PP | |
824 | .Vb 5 | |
825 | \& print delete $phash->{foo}; # prints $phash->[1], "FOO" | |
826 | \& print exists $phash->{foo}; # false | |
827 | \& print exists $phash->[0]{foo}; # true, key still exists | |
828 | \& print delete $phash->[0]{foo}; # now key is gone | |
829 | \& print $phash->{foo}; # runtime exception | |
830 | .Ve | |
831 | .Sh "Function Templates" | |
832 | .IX Xref "scope, lexical closure lexical lexical scope subroutine, nested sub, nested subroutine, local sub, local" | |
833 | .IX Subsection "Function Templates" | |
834 | As explained above, an anonymous function with access to the lexical | |
835 | variables visible when that function was compiled, creates a closure. It | |
836 | retains access to those variables even though it doesn't get run until | |
837 | later, such as in a signal handler or a Tk callback. | |
838 | .PP | |
839 | Using a closure as a function template allows us to generate many functions | |
840 | that act similarly. Suppose you wanted functions named after the colors | |
841 | that generated \s-1HTML\s0 font changes for the various colors: | |
842 | .PP | |
843 | .Vb 1 | |
844 | \& print "Be ", red("careful"), "with that ", green("light"); | |
845 | .Ve | |
846 | .PP | |
847 | The \fIred()\fR and \fIgreen()\fR functions would be similar. To create these, | |
848 | we'll assign a closure to a typeglob of the name of the function we're | |
849 | trying to build. | |
850 | .PP | |
851 | .Vb 5 | |
852 | \& @colors = qw(red blue green yellow orange purple violet); | |
853 | \& for my $name (@colors) { | |
854 | \& no strict 'refs'; # allow symbol table manipulation | |
855 | \& *$name = *{uc $name} = sub { "<FONT COLOR='$name'>@_</FONT>" }; | |
856 | \& } | |
857 | .Ve | |
858 | .PP | |
859 | Now all those different functions appear to exist independently. You can | |
860 | call \fIred()\fR, \s-1\fIRED\s0()\fR, \fIblue()\fR, \s-1\fIBLUE\s0()\fR, \fIgreen()\fR, etc. This technique saves on | |
861 | both compile time and memory use, and is less error-prone as well, since | |
862 | syntax checks happen at compile time. It's critical that any variables in | |
863 | the anonymous subroutine be lexicals in order to create a proper closure. | |
864 | That's the reasons for the \f(CW\*(C`my\*(C'\fR on the loop iteration variable. | |
865 | .PP | |
866 | This is one of the only places where giving a prototype to a closure makes | |
867 | much sense. If you wanted to impose scalar context on the arguments of | |
868 | these functions (probably not a wise idea for this particular example), | |
869 | you could have written it this way instead: | |
870 | .PP | |
871 | .Vb 1 | |
872 | \& *$name = sub ($) { "<FONT COLOR='$name'>$_[0]</FONT>" }; | |
873 | .Ve | |
874 | .PP | |
875 | However, since prototype checking happens at compile time, the assignment | |
876 | above happens too late to be of much use. You could address this by | |
877 | putting the whole loop of assignments within a \s-1BEGIN\s0 block, forcing it | |
878 | to occur during compilation. | |
879 | .PP | |
880 | Access to lexicals that change over type\*(--like those in the \f(CW\*(C`for\*(C'\fR loop | |
881 | above\*(--only works with closures, not general subroutines. In the general | |
882 | case, then, named subroutines do not nest properly, although anonymous | |
883 | ones do. Thus is because named subroutines are created (and capture any | |
884 | outer lexicals) only once at compile time, whereas anonymous subroutines | |
885 | get to capture each time you execute the 'sub' operator. If you are | |
886 | accustomed to using nested subroutines in other programming languages with | |
887 | their own private variables, you'll have to work at it a bit in Perl. The | |
888 | intuitive coding of this type of thing incurs mysterious warnings about | |
889 | \&\*(L"will not stay shared\*(R". For example, this won't work: | |
890 | .PP | |
891 | .Vb 5 | |
892 | \& sub outer { | |
893 | \& my $x = $_[0] + 35; | |
894 | \& sub inner { return $x * 19 } # WRONG | |
895 | \& return $x + inner(); | |
896 | \& } | |
897 | .Ve | |
898 | .PP | |
899 | A work-around is the following: | |
900 | .PP | |
901 | .Vb 5 | |
902 | \& sub outer { | |
903 | \& my $x = $_[0] + 35; | |
904 | \& local *inner = sub { return $x * 19 }; | |
905 | \& return $x + inner(); | |
906 | \& } | |
907 | .Ve | |
908 | .PP | |
909 | Now \fIinner()\fR can only be called from within \fIouter()\fR, because of the | |
910 | temporary assignments of the closure (anonymous subroutine). But when | |
911 | it does, it has normal access to the lexical variable \f(CW$x\fR from the scope | |
912 | of \fIouter()\fR. | |
913 | .PP | |
914 | This has the interesting effect of creating a function local to another | |
915 | function, something not normally supported in Perl. | |
916 | .SH "WARNING" | |
917 | .IX Xref "reference, string context reference, use as hash key" | |
918 | .IX Header "WARNING" | |
919 | You may not (usefully) use a reference as the key to a hash. It will be | |
920 | converted into a string: | |
921 | .PP | |
922 | .Vb 1 | |
923 | \& $x{ \e$a } = $a; | |
924 | .Ve | |
925 | .PP | |
926 | If you try to dereference the key, it won't do a hard dereference, and | |
927 | you won't accomplish what you're attempting. You might want to do something | |
928 | more like | |
929 | .PP | |
930 | .Vb 2 | |
931 | \& $r = \e@a; | |
932 | \& $x{ $r } = $r; | |
933 | .Ve | |
934 | .PP | |
935 | And then at least you can use the \fIvalues()\fR, which will be | |
936 | real refs, instead of the \fIkeys()\fR, which won't. | |
937 | .PP | |
938 | The standard Tie::RefHash module provides a convenient workaround to this. | |
939 | .SH "SEE ALSO" | |
940 | .IX Header "SEE ALSO" | |
941 | Besides the obvious documents, source code can be instructive. | |
942 | Some pathological examples of the use of references can be found | |
943 | in the \fIt/op/ref.t\fR regression test in the Perl source directory. | |
944 | .PP | |
945 | See also perldsc and perllol for how to use references to create | |
946 | complex data structures, and perltoot, perlobj, and perlbot | |
947 | for how to use them to create objects. |