Debian Codegraph @

upstream/mageia-cauldron/man1/perlreftut.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLREFTUT 1"
61 .TH PERLREFTUT 1 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlreftut \- Mark\*(Aqs very short tutorial about references
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 One of the most important new features in Perl 5 was the capability to
71 manage complicated data structures like multidimensional arrays and
72 nested hashes. To enable these, Perl 5 introduced a feature called
73 \&\fIreferences\fR, and using references is the key to managing complicated,
74 structured data in Perl. Unfortunately, there\*(Aqs a lot of funny syntax
75 to learn, and the main manual page can be hard to follow. The manual
76 is quite complete, and sometimes people find that a problem, because
77 it can be hard to tell what is important and what isn\*(Aqt.
78 .PP
79 Fortunately, you only need to know 10% of what\*(Aqs in the main page to get
80 90% of the benefit. This page will show you that 10%.
81 .SH "Who Needs Complicated Data Structures?"
82 .IX Header "Who Needs Complicated Data Structures?"
83 One problem that comes up all the time is needing a hash whose values are
84 lists. Perl has hashes, of course, but the values have to be scalars;
85 they can\*(Aqt be lists.
86 .PP
87 Why would you want a hash of lists? Let\*(Aqs take a simple example: You
88 have a file of city and country names, like this:
89 .PP
90 .Vb 6
91 \& Chicago, USA
92 \& Frankfurt, Germany
93 \& Berlin, Germany
94 \& Washington, USA
95 \& Helsinki, Finland
96 \& New York, USA
97 .Ve
98 .PP
99 and you want to produce an output like this, with each country mentioned
100 once, and then an alphabetical list of the cities in that country:
101 .PP
102 .Vb 3
103 \& Finland: Helsinki.
104 \& Germany: Berlin, Frankfurt.
105 \& USA: Chicago, New York, Washington.
106 .Ve
107 .PP
108 The natural way to do this is to have a hash whose keys are country
109 names. Associated with each country name key is a list of the cities in
110 that country. Each time you read a line of input, split it into a country
111 and a city, look up the list of cities already known to be in that
112 country, and append the new city to the list. When you\*(Aqre done reading
113 the input, iterate over the hash as usual, sorting each list of cities
114 before you print it out.
115 .PP
116 If hash values couldn\*(Aqt be lists, you lose. You\*(Aqd probably have to
117 combine all the cities into a single string somehow, and then when
118 time came to write the output, you\*(Aqd have to break the string into a
119 list, sort the list, and turn it back into a string. This is messy
120 and error\-prone. And it\*(Aqs frustrating, because Perl already has
121 perfectly good lists that would solve the problem if only you could
122 use them.
123 .SH "The Solution"
124 .IX Header "The Solution"
125 By the time Perl 5 rolled around, we were already stuck with this
126 design: Hash values must be scalars. The solution to this is
127 references.
128 .PP
129 A reference is a scalar value that \fIrefers to\fR an entire array or an
130 entire hash (or to just about anything else). Names are one kind of
131 reference that you\*(Aqre already familiar with. Each human being is a
132 messy, inconvenient collection of cells. But to refer to a particular
133 human, for instance the first computer programmer, it isn\*(Aqt necessary to
134 describe each of their cells; all you need is the easy, convenient
135 scalar string "Ada Lovelace".
136 .PP
137 References in Perl are like names for arrays and hashes. They\*(Aqre
138 Perl\*(Aqs private, internal names, so you can be sure they\*(Aqre
139 unambiguous. Unlike a human name, a reference only refers to one
140 thing, and you always know what it refers to. If you have a reference
141 to an array, you can recover the entire array from it. If you have a
142 reference to a hash, you can recover the entire hash. But the
143 reference is still an easy, compact scalar value.
144 .PP
145 You can\*(Aqt have a hash whose values are arrays; hash values can only be
146 scalars. We\*(Aqre stuck with that. But a single reference can refer to
147 an entire array, and references are scalars, so you can have a hash of
148 references to arrays, and it\*(Aqll act a lot like a hash of arrays, and
149 it\*(Aqll be just as useful as a hash of arrays.
150 .PP
151 We\*(Aqll come back to this city\-country problem later, after we\*(Aqve seen
152 some syntax for managing references.
153 .SH Syntax
154 .IX Header "Syntax"
155 There are just two ways to make a reference, and just two ways to use
156 it once you have it.
157 .SS "Making References"
158 .IX Subsection "Making References"
159 \fR\f(BIMake Rule 1\fR\fI\fR
160 .IX Subsection "Make Rule 1"
161 .PP
162 If you put a \f(CW\*(C`\e\*(C'\fR in front of a variable, you get a
163 reference to that variable.
164 .PP
165 .Vb 2
166 \& $aref = \e@array; # $aref now holds a reference to @array
167 \& $href = \e%hash; # $href now holds a reference to %hash
168 .Ve
169 .PP
170 Once the reference is stored in a variable like \f(CW$aref\fR or \f(CW$href\fR, you
171 can copy it or store it just the same as any other scalar value:
172 .PP
173 .Vb 3
174 \& $xy = $aref; # $xy now holds a reference to @array
175 \& $p[3] = $href; # $p[3] now holds a reference to %hash
176 \& $z = $p[3]; # $z now holds a reference to %hash
177 .Ve
178 .PP
179 These examples show how to make references to variables with names.
180 Sometimes you want to make an array or a hash that doesn\*(Aqt have a
181 name. This is analogous to the way you like to be able to use the
182 string \f(CW"\en"\fR or the number 80 without having to store it in a named
183 variable first.
184 .PP
185 \fR\f(BIMake Rule 2\fR\fI\fR
186 .IX Subsection "Make Rule 2"
187 .PP
188 \&\f(CW\*(C`[ ITEMS ]\*(C'\fR makes a new, anonymous array, and returns a reference to
189 that array. \f(CW\*(C`{ ITEMS }\*(C'\fR makes a new, anonymous hash, and returns a
190 reference to that hash.
191 .PP
192 .Vb 2
193 \& $aref = [ 1, "foo", undef, 13 ];
194 \& # $aref now holds a reference to an array
195 \&
196 \& $href = { APR => 4, AUG => 8 };
197 \& # $href now holds a reference to a hash
198 .Ve
199 .PP
200 The references you get from rule 2 are the same kind of
201 references that you get from rule 1:
202 .PP
203 .Vb 2
204 \& # This:
205 \& $aref = [ 1, 2, 3 ];
206 \&
207 \& # Does the same as this:
208 \& @array = (1, 2, 3);
209 \& $aref = \e@array;
210 .Ve
211 .PP
212 The first line is an abbreviation for the following two lines, except
213 that it doesn\*(Aqt create the superfluous array variable \f(CW@array\fR.
214 .PP
215 If you write just \f(CW\*(C`[]\*(C'\fR, you get a new, empty anonymous array.
216 If you write just \f(CW\*(C`{}\*(C'\fR, you get a new, empty anonymous hash.
217 .SS "Using References"
218 .IX Subsection "Using References"
219 What can you do with a reference once you have it? It\*(Aqs a scalar
220 value, and we\*(Aqve seen that you can store it as a scalar and get it back
221 again just like any scalar. There are just two more ways to use it:
222 .PP
223 \fR\f(BIUse Rule 1\fR\fI\fR
224 .IX Subsection "Use Rule 1"
225 .PP
226 You can always use an array reference, in curly braces, in place of
227 the name of an array. For example, \f(CW\*(C`@{$aref}\*(C'\fR instead of \f(CW@array\fR.
228 .PP
229 Here are some examples of that:
230 .PP
231 Arrays:
232 .PP
233 .Vb 4
234 \& @a @{$aref} An array
235 \& reverse @a reverse @{$aref} Reverse the array
236 \& $a[3] ${$aref}[3] An element of the array
237 \& $a[3] = 17; ${$aref}[3] = 17 Assigning an element
238 .Ve
239 .PP
240 On each line are two expressions that do the same thing. The
241 left\-hand versions operate on the array \f(CW@a\fR. The right\-hand
242 versions operate on the array that is referred to by \f(CW$aref\fR. Once
243 they find the array they\*(Aqre operating on, both versions do the same
244 things to the arrays.
245 .PP
246 Using a hash reference is \fIexactly\fR the same:
247 .PP
248 .Vb 4
249 \& %h %{$href} A hash
250 \& keys %h keys %{$href} Get the keys from the hash
251 \& $h{\*(Aqred\*(Aq} ${$href}{\*(Aqred\*(Aq} An element of the hash
252 \& $h{\*(Aqred\*(Aq} = 17 ${$href}{\*(Aqred\*(Aq} = 17 Assigning an element
253 .Ve
254 .PP
255 Whatever you want to do with a reference, \fBUse Rule 1\fR tells you how
256 to do it. You just write the Perl code that you would have written
257 for doing the same thing to a regular array or hash, and then replace
258 the array or hash name with \f(CW\*(C`{$reference}\*(C'\fR. "How do I loop over an
259 array when all I have is a reference?" Well, to loop over an array, you
260 would write
261 .PP
262 .Vb 3
263 \& for my $element (@array) {
264 \& ...
265 \& }
266 .Ve
267 .PP
268 so replace the array name, \f(CW@array\fR, with the reference:
269 .PP
270 .Vb 3
271 \& for my $element (@{$aref}) {
272 \& ...
273 \& }
274 .Ve
275 .PP
276 "How do I print out the contents of a hash when all I have is a
277 reference?" First write the code for printing out a hash:
278 .PP
279 .Vb 3
280 \& for my $key (keys %hash) {
281 \& print "$key => $hash{$key}\en";
282 \& }
283 .Ve
284 .PP
285 And then replace the hash name with the reference:
286 .PP
287 .Vb 3
288 \& for my $key (keys %{$href}) {
289 \& print "$key => ${$href}{$key}\en";
290 \& }
291 .Ve
292 .PP
293 \fR\f(BIUse Rule 2\fR\fI\fR
294 .IX Subsection "Use Rule 2"
295 .PP
296 \&\fBUse Rule 1\fR is all you really need, because it tells
297 you how to do absolutely everything you ever need to do with references.
298 But the most common thing to do with an array or a hash is to extract a
299 single element, and the \fBUse Rule 1\fR notation is
300 cumbersome. So there is an abbreviation.
301 .PP
302 \&\f(CW\*(C`${$aref}[3]\*(C'\fR is too hard to read, so you can write \f(CW\*(C`$aref\->[3]\*(C'\fR
303 instead.
304 .PP
305 \&\f(CW\*(C`${$href}{red}\*(C'\fR is too hard to read, so you can write
306 \&\f(CW\*(C`$href\->{red}\*(C'\fR instead.
307 .PP
308 If \f(CW$aref\fR holds a reference to an array, then \f(CW\*(C`$aref\->[3]\*(C'\fR is
309 the fourth element of the array. Don\*(Aqt confuse this with \f(CW$aref[3]\fR,
310 which is the fourth element of a totally different array, one
311 deceptively named \f(CW@aref\fR. \f(CW$aref\fR and \f(CW@aref\fR are unrelated the
312 same way that \f(CW$item\fR and \f(CW@item\fR are.
313 .PP
314 Similarly, \f(CW\*(C`$href\->{\*(Aqred\*(Aq}\*(C'\fR is part of the hash referred to by
315 the scalar variable \f(CW$href\fR, perhaps even one with no name.
316 \&\f(CW$href{\*(Aqred\*(Aq}\fR is part of the deceptively named \f(CW%href\fR hash. It\*(Aqs
317 easy to forget to leave out the \f(CW\*(C`\->\*(C'\fR, and if you do, you\*(Aqll get
318 bizarre results when your program gets array and hash elements out of
319 totally unexpected hashes and arrays that weren\*(Aqt the ones you wanted
320 to use.
321 .SS "An Example"
322 .IX Subsection "An Example"
323 Let\*(Aqs see a quick example of how all this is useful.
324 .PP
325 First, remember that \f(CW\*(C`[1, 2, 3]\*(C'\fR makes an anonymous array containing
326 \&\f(CW\*(C`(1, 2, 3)\*(C'\fR, and gives you a reference to that array.
327 .PP
328 Now think about
329 .PP
330 .Vb 4
331 \& @a = ( [1, 2, 3],
332 \& [4, 5, 6],
333 \& [7, 8, 9]
334 \& );
335 .Ve
336 .PP
337 \&\f(CW@a\fR is an array with three elements, and each one is a reference to
338 another array.
339 .PP
340 \&\f(CW$a[1]\fR is one of these references. It refers to an array, the array
341 containing \f(CW\*(C`(4, 5, 6)\*(C'\fR, and because it is a reference to an array,
342 \&\fBUse Rule 2\fR says that we can write \f(CW\*(C`$a[1]\->[2]\*(C'\fR
343 to get the third element from that array. \f(CW\*(C`$a[1]\->[2]\*(C'\fR is the 6.
344 Similarly, \f(CW\*(C`$a[0]\->[1]\*(C'\fR is the 2. What we have here is like a
345 two\-dimensional array; you can write \f(CW\*(C`$a[ROW]\->[COLUMN]\*(C'\fR to get or
346 set the element in any row and any column of the array.
347 .PP
348 The notation still looks a little cumbersome, so there\*(Aqs one more
349 abbreviation:
350 .SS "Arrow Rule"
351 .IX Subsection "Arrow Rule"
352 In between two \fBsubscripts\fR, the arrow is optional.
353 .PP
354 Instead of \f(CW\*(C`$a[1]\->[2]\*(C'\fR, we can write \f(CW\*(C`$a[1][2]\*(C'\fR; it means the
355 same thing. Instead of \f(CW\*(C`$a[0]\->[1] = 23\*(C'\fR, we can write
356 \&\f(CW\*(C`$a[0][1] = 23\*(C'\fR; it means the same thing.
357 .PP
358 Now it really looks like two\-dimensional arrays!
359 .PP
360 You can see why the arrows are important. Without them, we would have
361 had to write \f(CW\*(C`${$a[1]}[2]\*(C'\fR instead of \f(CW\*(C`$a[1][2]\*(C'\fR. For
362 three\-dimensional arrays, they let us write \f(CW\*(C`$x[2][3][5]\*(C'\fR instead of
363 the unreadable \f(CW\*(C`${${$x[2]}[3]}[5]\*(C'\fR.
364 .SH Solution
365 .IX Header "Solution"
366 Here\*(Aqs the answer to the problem I posed earlier, of reformatting a
367 file of city and country names.
368 .PP
369 .Vb 1
370 \& 1 my %table;
371 \&
372 \& 2 while (<>) {
373 \& 3 chomp;
374 \& 4 my ($city, $country) = split /, /;
375 \& 5 $table{$country} = [] unless exists $table{$country};
376 \& 6 push @{$table{$country}}, $city;
377 \& 7 }
378 \&
379 \& 8 for my $country (sort keys %table) {
380 \& 9 print "$country: ";
381 \& 10 my @cities = @{$table{$country}};
382 \& 11 print join \*(Aq, \*(Aq, sort @cities;
383 \& 12 print ".\en";
384 \& 13 }
385 .Ve
386 .PP
387 The program has two pieces: Lines 2\-7 read the input and build a data
388 structure, and lines 8\-13 analyze the data and print out the report.
389 We\*(Aqre going to have a hash, \f(CW%table\fR, whose keys are country names,
390 and whose values are references to arrays of city names. The data
391 structure will look like this:
392 .PP
393 .Vb 10
394 \& %table
395 \& +\-\-\-\-\-\-\-+\-\-\-+
396 \& | | | +\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+
397 \& |Germany| *\-\-\-\->| Frankfurt | Berlin |
398 \& | | | +\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+
399 \& +\-\-\-\-\-\-\-+\-\-\-+
400 \& | | | +\-\-\-\-\-\-\-\-\-\-+
401 \& |Finland| *\-\-\-\->| Helsinki |
402 \& | | | +\-\-\-\-\-\-\-\-\-\-+
403 \& +\-\-\-\-\-\-\-+\-\-\-+
404 \& | | | +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
405 \& | USA | *\-\-\-\->| Chicago | Washington | New York |
406 \& | | | +\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
407 \& +\-\-\-\-\-\-\-+\-\-\-+
408 .Ve
409 .PP
410 We\*(Aqll look at output first. Supposing we already have this structure,
411 how do we print it out?
412 .PP
413 .Vb 6
414 \& 8 for my $country (sort keys %table) {
415 \& 9 print "$country: ";
416 \& 10 my @cities = @{$table{$country}};
417 \& 11 print join \*(Aq, \*(Aq, sort @cities;
418 \& 12 print ".\en";
419 \& 13 }
420 .Ve
421 .PP
422 \&\f(CW%table\fR is an ordinary hash, and we get a list of keys from it, sort
423 the keys, and loop over the keys as usual. The only use of references
424 is in line 10. \f(CW$table{$country}\fR looks up the key \f(CW$country\fR in the
425 hash and gets the value, which is a reference to an array of cities in
426 that country. \fBUse Rule 1\fR says that we can recover
427 the array by saying \f(CW\*(C`@{$table{$country}}\*(C'\fR. Line 10 is just like
428 .PP
429 .Vb 1
430 \& @cities = @array;
431 .Ve
432 .PP
433 except that the name \f(CW\*(C`array\*(C'\fR has been replaced by the reference
434 \&\f(CW\*(C`{$table{$country}}\*(C'\fR. The \f(CW\*(C`@\*(C'\fR tells Perl to get the entire array.
435 Having gotten the list of cities, we sort it, join it, and print it
436 out as usual.
437 .PP
438 Lines 2\-7 are responsible for building the structure in the first
439 place. Here they are again:
440 .PP
441 .Vb 6
442 \& 2 while (<>) {
443 \& 3 chomp;
444 \& 4 my ($city, $country) = split /, /;
445 \& 5 $table{$country} = [] unless exists $table{$country};
446 \& 6 push @{$table{$country}}, $city;
447 \& 7 }
448 .Ve
449 .PP
450 Lines 2\-4 acquire a city and country name. Line 5 looks to see if the
451 country is already present as a key in the hash. If it\*(Aqs not, the
452 program uses the \f(CW\*(C`[]\*(C'\fR notation (\fBMake Rule 2\fR) to
453 manufacture a new, empty anonymous array of cities, and installs a
454 reference to it into the hash under the appropriate key.
455 .PP
456 Line 6 installs the city name into the appropriate array.
457 \&\f(CW$table{$country}\fR now holds a reference to the array of cities seen
458 in that country so far. Line 6 is exactly like
459 .PP
460 .Vb 1
461 \& push @array, $city;
462 .Ve
463 .PP
464 except that the name \f(CW\*(C`array\*(C'\fR has been replaced by the reference
465 \&\f(CW\*(C`{$table{$country}}\*(C'\fR. The \f(CW\*(C`push\*(C'\fR adds a
466 city name to the end of the referred\-to array.
467 .PP
468 There\*(Aqs one fine point I skipped. Line 5 is unnecessary, and we can
469 get rid of it.
470 .PP
471 .Vb 6
472 \& 2 while (<>) {
473 \& 3 chomp;
474 \& 4 my ($city, $country) = split /, /;
475 \& 5 #### $table{$country} = [] unless exists $table{$country};
476 \& 6 push @{$table{$country}}, $city;
477 \& 7 }
478 .Ve
479 .PP
480 If there\*(Aqs already an entry in \f(CW%table\fR for the current \f(CW$country\fR,
481 then nothing is different. Line 6 will locate the value in
482 \&\f(CW$table{$country}\fR, which is a reference to an array, and push \f(CW$city\fR
483 into the array. But what does it do when \f(CW$country\fR holds a key, say
484 \&\f(CW\*(C`Greece\*(C'\fR, that is not yet in \f(CW%table\fR?
485 .PP
486 This is Perl, so it does the exact right thing. It sees that you want
487 to push \f(CW\*(C`Athens\*(C'\fR onto an array that doesn\*(Aqt exist, so it helpfully
488 makes a new, empty, anonymous array for you, installs it into
489 \&\f(CW%table\fR, and then pushes \f(CW\*(C`Athens\*(C'\fR onto it. This is called
490 \&\fIautovivification\fR\-\-bringing things to life automatically. Perl saw
491 that the key wasn\*(Aqt in the hash, so it created a new hash entry
492 automatically. Perl saw that you wanted to use the hash value as an
493 array, so it created a new empty array and installed a reference to it
494 in the hash automatically. And as usual, Perl made the array one
495 element longer to hold the new city name.
496 .SH "The Rest"
497 .IX Header "The Rest"
498 I promised to give you 90% of the benefit with 10% of the details, and
499 that means I left out 90% of the details. Now that you have an
500 overview of the important parts, it should be easier to read the
501 perlref manual page, which discusses 100% of the details.
502 .PP
503 Some of the highlights of perlref:
504 .IP \(bu 4
505 You can make references to anything, including scalars, functions, and
506 other references.
507 .IP \(bu 4
508 In \fBUse Rule 1\fR, you can omit the curly brackets
509 whenever the thing inside them is an atomic scalar variable like
510 \&\f(CW$aref\fR. For example, \f(CW@$aref\fR is the same as \f(CW\*(C`@{$aref}\*(C'\fR, and
511 \&\f(CW$$aref[1]\fR is the same as \f(CW\*(C`${$aref}[1]\*(C'\fR. If you\*(Aqre just starting
512 out, you may want to adopt the habit of always including the curly
513 brackets.
514 .IP \(bu 4
515 This doesn\*(Aqt copy the underlying array:
516 .Sp
517 .Vb 1
518 \& $aref2 = $aref1;
519 .Ve
520 .Sp
521 You get two references to the same array. If you modify
522 \&\f(CW\*(C`$aref1\->[23]\*(C'\fR and then look at
523 \&\f(CW\*(C`$aref2\->[23]\*(C'\fR you\*(Aqll see the change.
524 .Sp
525 To copy the array, use
526 .Sp
527 .Vb 1
528 \& $aref2 = [@{$aref1}];
529 .Ve
530 .Sp
531 This uses \f(CW\*(C`[...]\*(C'\fR notation to create a new anonymous array, and
532 \&\f(CW$aref2\fR is assigned a reference to the new array. The new array is
533 initialized with the contents of the array referred to by \f(CW$aref1\fR.
534 .Sp
535 Similarly, to copy an anonymous hash, you can use
536 .Sp
537 .Vb 1
538 \& $href2 = {%{$href1}};
539 .Ve
540 .IP \(bu 4
541 To see if a variable contains a reference, use the
542 \&\f(CW\*(C`ref\*(C'\fR function. It returns true if its argument
543 is a reference. Actually it\*(Aqs a little better than that: It returns
544 \&\f(CW\*(C`HASH\*(C'\fR for hash references and \f(CW\*(C`ARRAY\*(C'\fR for array references.
545 .IP \(bu 4
546 If you try to use a reference like a string, you get strings like
547 .Sp
548 .Vb 1
549 \& ARRAY(0x80f5dec) or HASH(0x826afc0)
550 .Ve
551 .Sp
552 If you ever see a string that looks like this, you\*(Aqll know you
553 printed out a reference by mistake.
554 .Sp
555 A side effect of this representation is that you can use
556 \&\f(CW\*(C`eq\*(C'\fR to see if two references refer to the
557 same thing. (But you should usually use
558 \&\f(CW\*(C`==\*(C'\fR instead because it\*(Aqs much faster.)
559 .IP \(bu 4
560 You can use a string as if it were a reference. If you use the string
561 \&\f(CW"foo"\fR as an array reference, it\*(Aqs taken to be a reference to the
562 array \f(CW@foo\fR. This is called a \fIsymbolic reference\fR. The declaration
563 \&\f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR disables this feature, which can cause
564 all sorts of trouble if you use it by accident.
565 .PP
566 You might prefer to go on to perllol instead of perlref; it
567 discusses lists of lists and multidimensional arrays in detail. After
568 that, you should move on to perldsc; it\*(Aqs a Data Structure Cookbook
569 that shows recipes for using and printing out arrays of hashes, hashes
570 of arrays, and other kinds of data.
571 .SH Summary
572 .IX Header "Summary"
573 Everyone needs compound data structures, and in Perl the way you get
574 them is with references. There are four important rules for managing
575 references: Two for making references and two for using them. Once
576 you know these rules you can do most of the important things you need
577 to do with references.
578 .SH Credits
579 .IX Header "Credits"
580 Author: Mark Jason Dominus, Plover Systems (\f(CW\*(C`mjd\-perl\[email protected]\*(C'\fR)
581 .PP
582 This article originally appeared in \fIThe Perl Journal\fR
583 ( <http://www.tpj.com/> ) volume 3, #2. Reprinted with permission.
584 .PP
585 The original title was \fIUnderstand References Today\fR.
586 .SS "Distribution Conditions"
587 .IX Subsection "Distribution Conditions"
588 Copyright 1998 The Perl Journal.
589 .PP
590 This documentation is free; you can redistribute it and/or modify it
591 under the same terms as Perl itself.
592 .PP
593 Irrespective of its distribution, all code examples in these files are
594 hereby placed into the public domain. You are permitted and
595 encouraged to use this code in your own programs for fun or for profit
596 as you see fit. A simple comment in the code giving credit would be
597 courteous but is not required.