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