summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlreftut.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlreftut.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlreftut.pod527
1 files changed, 0 insertions, 527 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlreftut.pod b/Master/tlpkg/tlperl/lib/pods/perlreftut.pod
deleted file mode 100644
index 9565562711d..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlreftut.pod
+++ /dev/null
@@ -1,527 +0,0 @@
-=head1 NAME
-
-perlreftut - Mark's very short tutorial about references
-
-=head1 DESCRIPTION
-
-One of the most important new features in Perl 5 was the capability to
-manage complicated data structures like multidimensional arrays and
-nested hashes. To enable these, Perl 5 introduced a feature called
-'references', and using references is the key to managing complicated,
-structured data in Perl. Unfortunately, there's a lot of funny syntax
-to learn, and the main manual page can be hard to follow. The manual
-is quite complete, and sometimes people find that a problem, because
-it can be hard to tell what is important and what isn't.
-
-Fortunately, you only need to know 10% of what's in the main page to get
-90% of the benefit. This page will show you that 10%.
-
-=head1 Who Needs Complicated Data Structures?
-
-One problem that came up all the time in Perl 4 was how to represent a
-hash whose values were lists. Perl 4 had hashes, of course, but the
-values had to be scalars; they couldn't be lists.
-
-Why would you want a hash of lists? Let's take a simple example: You
-have a file of city and country names, like this:
-
- Chicago, USA
- Frankfurt, Germany
- Berlin, Germany
- Washington, USA
- Helsinki, Finland
- New York, USA
-
-and you want to produce an output like this, with each country mentioned
-once, and then an alphabetical list of the cities in that country:
-
- Finland: Helsinki.
- Germany: Berlin, Frankfurt.
- USA: Chicago, New York, Washington.
-
-The natural way to do this is to have a hash whose keys are country
-names. Associated with each country name key is a list of the cities in
-that country. Each time you read a line of input, split it into a country
-and a city, look up the list of cities already known to be in that
-country, and append the new city to the list. When you're done reading
-the input, iterate over the hash as usual, sorting each list of cities
-before you print it out.
-
-If hash values can't be lists, you lose. In Perl 4, hash values can't
-be lists; they can only be strings. You lose. You'd probably have to
-combine all the cities into a single string somehow, and then when
-time came to write the output, you'd have to break the string into a
-list, sort the list, and turn it back into a string. This is messy
-and error-prone. And it's frustrating, because Perl already has
-perfectly good lists that would solve the problem if only you could
-use them.
-
-=head1 The Solution
-
-By the time Perl 5 rolled around, we were already stuck with this
-design: Hash values must be scalars. The solution to this is
-references.
-
-A reference is a scalar value that I<refers to> an entire array or an
-entire hash (or to just about anything else). Names are one kind of
-reference that you're already familiar with. Think of the President
-of the United States: a messy, inconvenient bag of blood and bones.
-But to talk about him, or to represent him in a computer program, all
-you need is the easy, convenient scalar string "Barack Obama".
-
-References in Perl are like names for arrays and hashes. They're
-Perl's private, internal names, so you can be sure they're
-unambiguous. Unlike "Barack Obama", a reference only refers to one
-thing, and you always know what it refers to. If you have a reference
-to an array, you can recover the entire array from it. If you have a
-reference to a hash, you can recover the entire hash. But the
-reference is still an easy, compact scalar value.
-
-You can't have a hash whose values are arrays; hash values can only be
-scalars. We're stuck with that. But a single reference can refer to
-an entire array, and references are scalars, so you can have a hash of
-references to arrays, and it'll act a lot like a hash of arrays, and
-it'll be just as useful as a hash of arrays.
-
-We'll come back to this city-country problem later, after we've seen
-some syntax for managing references.
-
-
-=head1 Syntax
-
-There are just two ways to make a reference, and just two ways to use
-it once you have it.
-
-=head2 Making References
-
-=head3 B<Make Rule 1>
-
-If you put a C<\> in front of a variable, you get a
-reference to that variable.
-
- $aref = \@array; # $aref now holds a reference to @array
- $href = \%hash; # $href now holds a reference to %hash
- $sref = \$scalar; # $sref now holds a reference to $scalar
-
-Once the reference is stored in a variable like $aref or $href, you
-can copy it or store it just the same as any other scalar value:
-
- $xy = $aref; # $xy now holds a reference to @array
- $p[3] = $href; # $p[3] now holds a reference to %hash
- $z = $p[3]; # $z now holds a reference to %hash
-
-
-These examples show how to make references to variables with names.
-Sometimes you want to make an array or a hash that doesn't have a
-name. This is analogous to the way you like to be able to use the
-string C<"\n"> or the number 80 without having to store it in a named
-variable first.
-
-B<Make Rule 2>
-
-C<[ ITEMS ]> makes a new, anonymous array, and returns a reference to
-that array. C<{ ITEMS }> makes a new, anonymous hash, and returns a
-reference to that hash.
-
- $aref = [ 1, "foo", undef, 13 ];
- # $aref now holds a reference to an array
-
- $href = { APR => 4, AUG => 8 };
- # $href now holds a reference to a hash
-
-
-The references you get from rule 2 are the same kind of
-references that you get from rule 1:
-
- # This:
- $aref = [ 1, 2, 3 ];
-
- # Does the same as this:
- @array = (1, 2, 3);
- $aref = \@array;
-
-
-The first line is an abbreviation for the following two lines, except
-that it doesn't create the superfluous array variable C<@array>.
-
-If you write just C<[]>, you get a new, empty anonymous array.
-If you write just C<{}>, you get a new, empty anonymous hash.
-
-
-=head2 Using References
-
-What can you do with a reference once you have it? It's a scalar
-value, and we've seen that you can store it as a scalar and get it back
-again just like any scalar. There are just two more ways to use it:
-
-=head3 B<Use Rule 1>
-
-You can always use an array reference, in curly braces, in place of
-the name of an array. For example, C<@{$aref}> instead of C<@array>.
-
-Here are some examples of that:
-
-Arrays:
-
-
- @a @{$aref} An array
- reverse @a reverse @{$aref} Reverse the array
- $a[3] ${$aref}[3] An element of the array
- $a[3] = 17; ${$aref}[3] = 17 Assigning an element
-
-
-On each line are two expressions that do the same thing. The
-left-hand versions operate on the array C<@a>. The right-hand
-versions operate on the array that is referred to by C<$aref>. Once
-they find the array they're operating on, both versions do the same
-things to the arrays.
-
-Using a hash reference is I<exactly> the same:
-
- %h %{$href} A hash
- keys %h keys %{$href} Get the keys from the hash
- $h{'red'} ${$href}{'red'} An element of the hash
- $h{'red'} = 17 ${$href}{'red'} = 17 Assigning an element
-
-Whatever you want to do with a reference, B<Use Rule 1> tells you how
-to do it. You just write the Perl code that you would have written
-for doing the same thing to a regular array or hash, and then replace
-the array or hash name with C<{$reference}>. "How do I loop over an
-array when all I have is a reference?" Well, to loop over an array, you
-would write
-
- for my $element (@array) {
- ...
- }
-
-so replace the array name, C<@array>, with the reference:
-
- for my $element (@{$aref}) {
- ...
- }
-
-"How do I print out the contents of a hash when all I have is a
-reference?" First write the code for printing out a hash:
-
- for my $key (keys %hash) {
- print "$key => $hash{$key}\n";
- }
-
-And then replace the hash name with the reference:
-
- for my $key (keys %{$href}) {
- print "$key => ${$href}{$key}\n";
- }
-
-=head3 B<Use Rule 2>
-
-B<Use Rule 1> is all you really need, because it tells you how to do
-absolutely everything you ever need to do with references. But the
-most common thing to do with an array or a hash is to extract a single
-element, and the B<Use Rule 1> notation is cumbersome. So there is an
-abbreviation.
-
-C<${$aref}[3]> is too hard to read, so you can write C<< $aref->[3] >>
-instead.
-
-C<${$href}{red}> is too hard to read, so you can write
-C<< $href->{red} >> instead.
-
-If C<$aref> holds a reference to an array, then C<< $aref->[3] >> is
-the fourth element of the array. Don't confuse this with C<$aref[3]>,
-which is the fourth element of a totally different array, one
-deceptively named C<@aref>. C<$aref> and C<@aref> are unrelated the
-same way that C<$item> and C<@item> are.
-
-Similarly, C<< $href->{'red'} >> is part of the hash referred to by
-the scalar variable C<$href>, perhaps even one with no name.
-C<$href{'red'}> is part of the deceptively named C<%href> hash. It's
-easy to forget to leave out the C<< -> >>, and if you do, you'll get
-bizarre results when your program gets array and hash elements out of
-totally unexpected hashes and arrays that weren't the ones you wanted
-to use.
-
-
-=head2 An Example
-
-Let's see a quick example of how all this is useful.
-
-First, remember that C<[1, 2, 3]> makes an anonymous array containing
-C<(1, 2, 3)>, and gives you a reference to that array.
-
-Now think about
-
- @a = ( [1, 2, 3],
- [4, 5, 6],
- [7, 8, 9]
- );
-
-@a is an array with three elements, and each one is a reference to
-another array.
-
-C<$a[1]> is one of these references. It refers to an array, the array
-containing C<(4, 5, 6)>, and because it is a reference to an array,
-B<Use Rule 2> says that we can write C<< $a[1]->[2] >> to get the
-third element from that array. C<< $a[1]->[2] >> is the 6.
-Similarly, C<< $a[0]->[1] >> is the 2. What we have here is like a
-two-dimensional array; you can write C<< $a[ROW]->[COLUMN] >> to get
-or set the element in any row and any column of the array.
-
-The notation still looks a little cumbersome, so there's one more
-abbreviation:
-
-=head2 Arrow Rule
-
-In between two B<subscripts>, the arrow is optional.
-
-Instead of C<< $a[1]->[2] >>, we can write C<$a[1][2]>; it means the
-same thing. Instead of C<< $a[0]->[1] = 23 >>, we can write
-C<$a[0][1] = 23>; it means the same thing.
-
-Now it really looks like two-dimensional arrays!
-
-You can see why the arrows are important. Without them, we would have
-had to write C<${$a[1]}[2]> instead of C<$a[1][2]>. For
-three-dimensional arrays, they let us write C<$x[2][3][5]> instead of
-the unreadable C<${${$x[2]}[3]}[5]>.
-
-=head1 Solution
-
-Here's the answer to the problem I posed earlier, of reformatting a
-file of city and country names.
-
- 1 my %table;
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
- 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-
-
-The program has two pieces: Lines 2--7 read the input and build a data
-structure, and lines 8-13 analyze the data and print out the report.
-We're going to have a hash, C<%table>, whose keys are country names,
-and whose values are references to arrays of city names. The data
-structure will look like this:
-
-
- %table
- +-------+---+
- | | | +-----------+--------+
- |Germany| *---->| Frankfurt | Berlin |
- | | | +-----------+--------+
- +-------+---+
- | | | +----------+
- |Finland| *---->| Helsinki |
- | | | +----------+
- +-------+---+
- | | | +---------+------------+----------+
- | USA | *---->| Chicago | Washington | New York |
- | | | +---------+------------+----------+
- +-------+---+
-
-We'll look at output first. Supposing we already have this structure,
-how do we print it out?
-
- 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-
-C<%table> is an
-ordinary hash, and we get a list of keys from it, sort the keys, and
-loop over the keys as usual. The only use of references is in line 10.
-C<$table{$country}> looks up the key C<$country> in the hash
-and gets the value, which is a reference to an array of cities in that country.
-B<Use Rule 1> says that
-we can recover the array by saying
-C<@{$table{$country}}>. Line 10 is just like
-
- @cities = @array;
-
-except that the name C<array> has been replaced by the reference
-C<{$table{$country}}>. The C<@> tells Perl to get the entire array.
-Having gotten the list of cities, we sort it, join it, and print it
-out as usual.
-
-Lines 2-7 are responsible for building the structure in the first
-place. Here they are again:
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
-Lines 2-4 acquire a city and country name. Line 5 looks to see if the
-country is already present as a key in the hash. If it's not, the
-program uses the C<[]> notation (B<Make Rule 2>) to manufacture a new,
-empty anonymous array of cities, and installs a reference to it into
-the hash under the appropriate key.
-
-Line 6 installs the city name into the appropriate array.
-C<$table{$country}> now holds a reference to the array of cities seen
-in that country so far. Line 6 is exactly like
-
- push @array, $city;
-
-except that the name C<array> has been replaced by the reference
-C<{$table{$country}}>. The C<push> adds a city name to the end of the
-referred-to array.
-
-There's one fine point I skipped. Line 5 is unnecessary, and we can
-get rid of it.
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 #### $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
-If there's already an entry in C<%table> for the current C<$country>,
-then nothing is different. Line 6 will locate the value in
-C<$table{$country}>, which is a reference to an array, and push
-C<$city> into the array. But
-what does it do when
-C<$country> holds a key, say C<Greece>, that is not yet in C<%table>?
-
-This is Perl, so it does the exact right thing. It sees that you want
-to push C<Athens> onto an array that doesn't exist, so it helpfully
-makes a new, empty, anonymous array for you, installs it into
-C<%table>, and then pushes C<Athens> onto it. This is called
-'autovivification'--bringing things to life automatically. Perl saw
-that they key wasn't in the hash, so it created a new hash entry
-automatically. Perl saw that you wanted to use the hash value as an
-array, so it created a new empty array and installed a reference to it
-in the hash automatically. And as usual, Perl made the array one
-element longer to hold the new city name.
-
-=head1 The Rest
-
-I promised to give you 90% of the benefit with 10% of the details, and
-that means I left out 90% of the details. Now that you have an
-overview of the important parts, it should be easier to read the
-L<perlref> manual page, which discusses 100% of the details.
-
-Some of the highlights of L<perlref>:
-
-=over 4
-
-=item *
-
-You can make references to anything, including scalars, functions, and
-other references.
-
-=item *
-
-In B<Use Rule 1>, you can omit the curly brackets whenever the thing
-inside them is an atomic scalar variable like C<$aref>. For example,
-C<@$aref> is the same as C<@{$aref}>, and C<$$aref[1]> is the same as
-C<${$aref}[1]>. If you're just starting out, you may want to adopt
-the habit of always including the curly brackets.
-
-=item *
-
-This doesn't copy the underlying array:
-
- $aref2 = $aref1;
-
-You get two references to the same array. If you modify
-C<< $aref1->[23] >> and then look at
-C<< $aref2->[23] >> you'll see the change.
-
-To copy the array, use
-
- $aref2 = [@{$aref1}];
-
-This uses C<[...]> notation to create a new anonymous array, and
-C<$aref2> is assigned a reference to the new array. The new array is
-initialized with the contents of the array referred to by C<$aref1>.
-
-Similarly, to copy an anonymous hash, you can use
-
- $href2 = {%{$href1}};
-
-=item *
-
-To see if a variable contains a reference, use the C<ref> function. It
-returns true if its argument is a reference. Actually it's a little
-better than that: It returns C<HASH> for hash references and C<ARRAY>
-for array references.
-
-=item *
-
-If you try to use a reference like a string, you get strings like
-
- ARRAY(0x80f5dec) or HASH(0x826afc0)
-
-If you ever see a string that looks like this, you'll know you
-printed out a reference by mistake.
-
-A side effect of this representation is that you can use C<eq> to see
-if two references refer to the same thing. (But you should usually use
-C<==> instead because it's much faster.)
-
-=item *
-
-You can use a string as if it were a reference. If you use the string
-C<"foo"> as an array reference, it's taken to be a reference to the
-array C<@foo>. This is called a I<soft reference> or I<symbolic
-reference>. The declaration C<use strict 'refs'> disables this
-feature, which can cause all sorts of trouble if you use it by accident.
-
-=back
-
-You might prefer to go on to L<perllol> instead of L<perlref>; it
-discusses lists of lists and multidimensional arrays in detail. After
-that, you should move on to L<perldsc>; it's a Data Structure Cookbook
-that shows recipes for using and printing out arrays of hashes, hashes
-of arrays, and other kinds of data.
-
-=head1 Summary
-
-Everyone needs compound data structures, and in Perl the way you get
-them is with references. There are four important rules for managing
-references: Two for making references and two for using them. Once
-you know these rules you can do most of the important things you need
-to do with references.
-
-=head1 Credits
-
-Author: Mark Jason Dominus, Plover Systems (C<mjd-perl-ref+@plover.com>)
-
-This article originally appeared in I<The Perl Journal>
-( http://www.tpj.com/ ) volume 3, #2. Reprinted with permission.
-
-The original title was I<Understand References Today>.
-
-=head2 Distribution Conditions
-
-Copyright 1998 The Perl Journal.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in these files are
-hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun or for profit
-as you see fit. A simple comment in the code giving credit would be
-courteous but is not required.
-
-
-
-
-=cut