This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix a2p translation of '{print "a" "b" "c"}'
[perl5.git] / pod / perlref.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlref - Perl references and nested data structures
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7Before release 5 of Perl it was difficult to represent complex data
8structures, because all references had to be symbolic, and even that was
9difficult to do when you wanted to refer to a variable rather than a
10symbol table entry. Perl 5 not only makes it easier to use symbolic
11references to variables, but lets you have "hard" references to any piece
12of data. Any scalar may hold a hard reference. Since arrays and hashes
13contain scalars, you can now easily build arrays of arrays, arrays of
14hashes, hashes of arrays, arrays of hashes of functions, and so on.
a0d0e21e
LW
15
16Hard references are smart--they keep track of reference counts for you,
17automatically freeing the thing referred to when its reference count
6309d9d9
PP
18goes to zero. (Note: The reference counts for values in self-referential
19or cyclic data structures may not go to zero without a little help; see
20L<perlobj/"Two-Phased Garbage Collection"> for a detailed explanation.
21If that thing happens to be an object, the object is
a0d0e21e
LW
22destructed. See L<perlobj> for more about objects. (In a sense,
23everything in Perl is an object, but we usually reserve the word for
24references to objects that have been officially "blessed" into a class package.)
25
6309d9d9 26
a0d0e21e
LW
27A symbolic reference contains the name of a variable, just as a
28symbolic link in the filesystem merely contains the name of a file.
29The C<*glob> notation is a kind of symbolic reference. Hard references
30are more like hard links in the file system: merely another way
31at getting at the same underlying object, irrespective of its name.
32
33"Hard" references are easy to use in Perl. There is just one
34overriding principle: Perl does no implicit referencing or
35dereferencing. When a scalar is holding a reference, it always behaves
36as a scalar. It doesn't magically start being an array or a hash
37unless you tell it so explicitly by dereferencing it.
38
39References can be constructed several ways.
40
41=over 4
42
43=item 1.
44
45By using the backslash operator on a variable, subroutine, or value.
46(This works much like the & (address-of) operator works in C.) Note
47that this typically creates I<ANOTHER> reference to a variable, since
48there's already a reference to the variable in the symbol table. But
49the symbol table reference might go away, and you'll still have the
50reference that the backslash returned. Here are some examples:
51
52 $scalarref = \$foo;
53 $arrayref = \@ARGV;
54 $hashref = \%ENV;
55 $coderef = \&handler;
cb1a09d0
AD
56 $globref = \*STDOUT;
57
a0d0e21e
LW
58
59=item 2.
60
61A reference to an anonymous array can be constructed using square
62brackets:
63
64 $arrayref = [1, 2, ['a', 'b', 'c']];
65
66Here we've constructed a reference to an anonymous array of three elements
67whose final element is itself reference to another anonymous array of three
68elements. (The multidimensional syntax described later can be used to
184e9718 69access this. For example, after the above, C<$arrayref-E<gt>[2][1]> would have
a0d0e21e
LW
70the value "b".)
71
cb1a09d0
AD
72Note that taking a reference to an enumerated list is not the same
73as using square brackets--instead it's the same as creating
74a list of references!
75
58e0a6ae
GS
76 @list = (\$a, \@b, \%c);
77 @list = \($a, @b, %c); # same thing!
78
79As a special case, C<\(@foo)> returns a list of references to the contents
80of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>.
cb1a09d0 81
a0d0e21e
LW
82=item 3.
83
84A reference to an anonymous hash can be constructed using curly
85brackets:
86
87 $hashref = {
88 'Adam' => 'Eve',
89 'Clyde' => 'Bonnie',
90 };
91
92Anonymous hash and array constructors can be intermixed freely to
93produce as complicated a structure as you want. The multidimensional
94syntax described below works for these too. The values above are
95literals, but variables and expressions would work just as well, because
96assignment operators in Perl (even within local() or my()) are executable
97statements, not compile-time declarations.
98
99Because curly brackets (braces) are used for several other things
100including BLOCKs, you may occasionally have to disambiguate braces at the
101beginning of a statement by putting a C<+> or a C<return> in front so
102that Perl realizes the opening brace isn't starting a BLOCK. The economy and
103mnemonic value of using curlies is deemed worth this occasional extra
104hassle.
105
106For example, if you wanted a function to make a new hash and return a
107reference to it, you have these options:
108
109 sub hashem { { @_ } } # silently wrong
110 sub hashem { +{ @_ } } # ok
111 sub hashem { return { @_ } } # ok
112
113=item 4.
114
115A reference to an anonymous subroutine can be constructed by using
116C<sub> without a subname:
117
118 $coderef = sub { print "Boink!\n" };
119
120Note the presence of the semicolon. Except for the fact that the code
121inside isn't executed immediately, a C<sub {}> is not so much a
122declaration as it is an operator, like C<do{}> or C<eval{}>. (However, no
123matter how many times you execute that line (unless you're in an
124C<eval("...")>), C<$coderef> will still have a reference to the I<SAME>
125anonymous subroutine.)
126
748a9306
LW
127Anonymous subroutines act as closures with respect to my() variables,
128that is, variables visible lexically within the current scope. Closure
129is a notion out of the Lisp world that says if you define an anonymous
130function in a particular lexical context, it pretends to run in that
131context even when it's called outside of the context.
132
133In human terms, it's a funny way of passing arguments to a subroutine when
134you define it as well as when you call it. It's useful for setting up
135little bits of code to run later, such as callbacks. You can even
136do object-oriented stuff with it, though Perl provides a different
137mechanism to do that already--see L<perlobj>.
138
139You can also think of closure as a way to write a subroutine template without
140using eval. (In fact, in version 5.000, eval was the I<only> way to get
141closures. You may wish to use "require 5.001" if you use closures.)
142
143Here's a small example of how closures works:
144
145 sub newprint {
146 my $x = shift;
147 return sub { my $y = shift; print "$x, $y!\n"; };
a0d0e21e 148 }
748a9306
LW
149 $h = newprint("Howdy");
150 $g = newprint("Greetings");
151
152 # Time passes...
153
154 &$h("world");
155 &$g("earthlings");
a0d0e21e 156
748a9306
LW
157This prints
158
159 Howdy, world!
160 Greetings, earthlings!
161
162Note particularly that $x continues to refer to the value passed into
cb1a09d0 163newprint() I<despite> the fact that the "my $x" has seemingly gone out of
748a9306
LW
164scope by the time the anonymous subroutine runs. That's what closure
165is all about.
166
167This only applies to lexical variables, by the way. Dynamic variables
168continue to work as they have always worked. Closure is not something
169that most Perl programmers need trouble themselves about to begin with.
a0d0e21e
LW
170
171=item 5.
172
173References are often returned by special subroutines called constructors.
748a9306 174Perl objects are just references to a special kind of object that happens to know
a0d0e21e
LW
175which package it's associated with. Constructors are just special
176subroutines that know how to create that association. They do so by
177starting with an ordinary reference, and it remains an ordinary reference
178even while it's also being an object. Constructors are customarily
179named new(), but don't have to be:
180
181 $objref = new Doggie (Tail => 'short', Ears => 'long');
182
183=item 6.
184
185References of the appropriate type can spring into existence if you
186dereference them in a context that assumes they exist. Since we haven't
187talked about dereferencing yet, we can't show you any examples yet.
188
cb1a09d0
AD
189=item 7.
190
191References to filehandles can be created by taking a reference to
192a typeglob. This is currently the best way to pass filehandles into or
193out of subroutines, or to store them in larger data structures.
194
195 splutter(\*STDOUT);
196 sub splutter {
197 my $fh = shift;
198 print $fh "her um well a hmmm\n";
199 }
200
201 $rec = get_rec(\*STDIN);
202 sub get_rec {
203 my $fh = shift;
204 return scalar <$fh>;
205 }
206
a0d0e21e
LW
207=back
208
209That's it for creating references. By now you're probably dying to
210know how to use references to get back to your long-lost data. There
211are several basic methods.
212
213=over 4
214
215=item 1.
216
6309d9d9
PP
217Anywhere you'd put an identifier (or chain of identifiers) as part
218of a variable or subroutine name, you can replace the identifier with
219a simple scalar variable containing a reference of the correct type:
a0d0e21e
LW
220
221 $bar = $$scalarref;
222 push(@$arrayref, $filename);
223 $$arrayref[0] = "January";
224 $$hashref{"KEY"} = "VALUE";
225 &$coderef(1,2,3);
cb1a09d0 226 print $globref "output\n";
a0d0e21e
LW
227
228It's important to understand that we are specifically I<NOT> dereferencing
229C<$arrayref[0]> or C<$hashref{"KEY"}> there. The dereference of the
230scalar variable happens I<BEFORE> it does any key lookups. Anything more
231complicated than a simple scalar variable must use methods 2 or 3 below.
232However, a "simple scalar" includes an identifier that itself uses method
2331 recursively. Therefore, the following prints "howdy".
234
235 $refrefref = \\\"howdy";
236 print $$$$refrefref;
237
238=item 2.
239
6309d9d9
PP
240Anywhere you'd put an identifier (or chain of identifiers) as part of a
241variable or subroutine name, you can replace the identifier with a
242BLOCK returning a reference of the correct type. In other words, the
243previous examples could be written like this:
a0d0e21e
LW
244
245 $bar = ${$scalarref};
246 push(@{$arrayref}, $filename);
247 ${$arrayref}[0] = "January";
248 ${$hashref}{"KEY"} = "VALUE";
249 &{$coderef}(1,2,3);
cb1a09d0 250 $globref->print("output\n"); # iff you use FileHandle
a0d0e21e
LW
251
252Admittedly, it's a little silly to use the curlies in this case, but
253the BLOCK can contain any arbitrary expression, in particular,
254subscripted expressions:
255
256 &{ $dispatch{$index} }(1,2,3); # call correct routine
257
258Because of being able to omit the curlies for the simple case of C<$$x>,
259people often make the mistake of viewing the dereferencing symbols as
260proper operators, and wonder about their precedence. If they were,
261though, you could use parens instead of braces. That's not the case.
262Consider the difference below; case 0 is a short-hand version of case 1,
263I<NOT> case 2:
264
265 $$hashref{"KEY"} = "VALUE"; # CASE 0
266 ${$hashref}{"KEY"} = "VALUE"; # CASE 1
267 ${$hashref{"KEY"}} = "VALUE"; # CASE 2
268 ${$hashref->{"KEY"}} = "VALUE"; # CASE 3
269
270Case 2 is also deceptive in that you're accessing a variable
271called %hashref, not dereferencing through $hashref to the hash
272it's presumably referencing. That would be case 3.
273
274=item 3.
275
276The case of individual array elements arises often enough that it gets
277cumbersome to use method 2. As a form of syntactic sugar, the two
278lines like that above can be written:
279
280 $arrayref->[0] = "January";
748a9306 281 $hashref->{"KEY"} = "VALUE";
a0d0e21e
LW
282
283The left side of the array can be any expression returning a reference,
284including a previous dereference. Note that C<$array[$x]> is I<NOT> the
285same thing as C<$array-E<gt>[$x]> here:
286
287 $array[$x]->{"foo"}->[0] = "January";
288
289This is one of the cases we mentioned earlier in which references could
290spring into existence when in an lvalue context. Before this
291statement, C<$array[$x]> may have been undefined. If so, it's
292automatically defined with a hash reference so that we can look up
293C<{"foo"}> in it. Likewise C<$array[$x]-E<gt>{"foo"}> will automatically get
294defined with an array reference so that we can look up C<[0]> in it.
295
296One more thing here. The arrow is optional I<BETWEEN> brackets
297subscripts, so you can shrink the above down to
298
299 $array[$x]{"foo"}[0] = "January";
300
301Which, in the degenerate case of using only ordinary arrays, gives you
302multidimensional arrays just like C's:
303
304 $score[$x][$y][$z] += 42;
305
306Well, okay, not entirely like C's arrays, actually. C doesn't know how
307to grow its arrays on demand. Perl does.
308
309=item 4.
310
311If a reference happens to be a reference to an object, then there are
312probably methods to access the things referred to, and you should probably
313stick to those methods unless you're in the class package that defines the
314object's methods. In other words, be nice, and don't violate the object's
315encapsulation without a very good reason. Perl does not enforce
316encapsulation. We are not totalitarians here. We do expect some basic
317civility though.
318
319=back
320
321The ref() operator may be used to determine what type of thing the
322reference is pointing to. See L<perlfunc>.
323
324The bless() operator may be used to associate a reference with a package
325functioning as an object class. See L<perlobj>.
326
cb1a09d0 327A typeglob may be dereferenced the same way a reference can, since
a0d0e21e
LW
328the dereference syntax always indicates the kind of reference desired.
329So C<${*foo}> and C<${\$foo}> both indicate the same scalar variable.
330
331Here's a trick for interpolating a subroutine call into a string:
332
cb1a09d0
AD
333 print "My sub returned @{[mysub(1,2,3)]} that time.\n";
334
335The way it works is that when the C<@{...}> is seen in the double-quoted
336string, it's evaluated as a block. The block creates a reference to an
337anonymous array containing the results of the call to C<mysub(1,2,3)>. So
338the whole block returns a reference to an array, which is then
339dereferenced by C<@{...}> and stuck into the double-quoted string. This
340chicanery is also useful for arbitrary expressions:
a0d0e21e 341
184e9718 342 print "That yields @{[$n + 5]} widgets\n";
a0d0e21e
LW
343
344=head2 Symbolic references
345
346We said that references spring into existence as necessary if they are
347undefined, but we didn't say what happens if a value used as a
348reference is already defined, but I<ISN'T> a hard reference. If you
349use it as a reference in this case, it'll be treated as a symbolic
350reference. That is, the value of the scalar is taken to be the I<NAME>
351of a variable, rather than a direct link to a (possibly) anonymous
352value.
353
354People frequently expect it to work like this. So it does.
355
356 $name = "foo";
357 $$name = 1; # Sets $foo
358 ${$name} = 2; # Sets $foo
359 ${$name x 2} = 3; # Sets $foofoo
360 $name->[0] = 4; # Sets $foo[0]
361 @$name = (); # Clears @foo
362 &$name(); # Calls &foo() (as in Perl 4)
363 $pack = "THAT";
364 ${"${pack}::$name"} = 5; # Sets $THAT::foo without eval
365
366This is very powerful, and slightly dangerous, in that it's possible
367to intend (with the utmost sincerity) to use a hard reference, and
368accidentally use a symbolic reference instead. To protect against
369that, you can say
370
371 use strict 'refs';
372
373and then only hard references will be allowed for the rest of the enclosing
374block. An inner block may countermand that with
375
376 no strict 'refs';
377
378Only package variables are visible to symbolic references. Lexical
379variables (declared with my()) aren't in a symbol table, and thus are
380invisible to this mechanism. For example:
381
382 local($value) = 10;
383 $ref = \$value;
384 {
385 my $value = 20;
386 print $$ref;
387 }
388
389This will still print 10, not 20. Remember that local() affects package
390variables, which are all "global" to the package.
391
748a9306
LW
392=head2 Not-so-symbolic references
393
394A new feature contributing to readability in 5.001 is that the brackets
395around a symbolic reference behave more like quotes, just as they
396always have within a string. That is,
397
398 $push = "pop on ";
399 print "${push}over";
400
401has always meant to print "pop on over", despite the fact that push is
402a reserved word. This has been generalized to work the same outside
403of quotes, so that
404
405 print ${push} . "over";
406
407and even
408
409 print ${ push } . "over";
410
411will have the same effect. (This would have been a syntax error in
4125.000, though Perl 4 allowed it in the spaceless form.) Note that this
413construct is I<not> considered to be a symbolic reference when you're
414using strict refs:
415
416 use strict 'refs';
417 ${ bareword }; # Okay, means $bareword.
418 ${ "bareword" }; # Error, symbolic reference.
419
420Similarly, because of all the subscripting that is done using single
421words, we've applied the same rule to any bareword that is used for
422subscripting a hash. So now, instead of writing
423
424 $array{ "aaa" }{ "bbb" }{ "ccc" }
425
426you can just write
427
428 $array{ aaa }{ bbb }{ ccc }
429
430and not worry about whether the subscripts are reserved words. In the
431rare event that you do wish to do something like
432
433 $array{ shift }
434
435you can force interpretation as a reserved word by adding anything that
436makes it more than a bareword:
437
438 $array{ shift() }
439 $array{ +shift }
440 $array{ shift @_ }
441
442The B<-w> switch will warn you if it interprets a reserved word as a string.
443But it will no longer warn you about using lowercase words, since the
444string is effectively quoted.
445
cb1a09d0 446=head1 WARNING
748a9306
LW
447
448You may not (usefully) use a reference as the key to a hash. It will be
449converted into a string:
450
451 $x{ \$a } = $a;
452
453If you try to dereference the key, it won't do a hard dereference, and
184e9718 454you won't accomplish what you're attempting. You might want to do something
cb1a09d0 455more like
748a9306 456
cb1a09d0
AD
457 $r = \@a;
458 $x{ $r } = $r;
459
460And then at least you can use the values(), which will be
461real refs, instead of the keys(), which won't.
462
463=head1 SEE ALSO
a0d0e21e
LW
464
465Besides the obvious documents, source code can be instructive.
466Some rather pathological examples of the use of references can be found
467in the F<t/op/ref.t> regression test in the Perl source directory.
cb1a09d0
AD
468
469See also L<perldsc> and L<perllol> for how to use references to create
470complex data structures, and L<perlobj> for how to use them to create
471objects.