perl 5.003_07: lib/ExtUtils/xsubpp
[perl.git] / pod / perldsc.pod
1 =head1 NAME
2
3 perldsc - Perl Data Structures Cookbook
4
5 =head1 DESCRIPTION
6
7 The single feature most sorely lacking in the Perl programming language
8 prior to its 5.0 release was complex data structures.  Even without direct
9 language support, some valiant programmers did manage to emulate them, but
10 it was hard work and not for the faint of heart.  You could occasionally
11 get away with the C<$m{$LoL,$b}> notation borrowed from I<awk> in which the
12 keys are actually more like a single concatenated string C<"$LoL$b">, but
13 traversal and sorting were difficult.  More desperate programmers even
14 hacked Perl's internal symbol table directly, a strategy that proved hard
15 to develop and maintain--to put it mildly.
16
17 The 5.0 release of Perl let us have complex data structures.  You
18 may now write something like this and all of a sudden, you'd have a array
19 with three dimensions!
20
21     for $x (1 .. 10) {
22         for $y (1 .. 10) {
23             for $z (1 .. 10) {
24                 $LoL[$x][$y][$z] =
25                     $x ** $y + $z;
26             }
27         }
28     }
29
30 Alas, however simple this may appear, underneath it's a much more
31 elaborate construct than meets the eye!
32
33 How do you print it out?  Why can't you just say C<print @LoL>?  How do
34 you sort it?  How can you pass it to a function or get one of these back
35 from a function?  Is is an object?  Can you save it to disk to read
36 back later?  How do you access whole rows or columns of that matrix?  Do
37 all the values have to be numeric?
38
39 As you see, it's quite easy to become confused.  While some small portion
40 of the blame for this can be attributed to the reference-based
41 implementation, it's really more due to a lack of existing documentation with
42 examples designed for the beginner.
43
44 This document is meant to be a detailed but understandable treatment of
45 the many different sorts of data structures you might want to develop.  It should
46 also serve as a cookbook of examples.  That way, when you need to create one of these
47 complex data structures, you can just pinch, pilfer, or purloin
48 a drop-in example from here.
49
50 Let's look at each of these possible constructs in detail.  There are separate
51 documents on each of the following:
52
53 =over 5
54
55 =item * arrays of arrays
56
57 =item * hashes of arrays
58
59 =item * arrays of hashes
60
61 =item * hashes of hashes
62
63 =item * more elaborate constructs
64
65 =item * recursive and self-referential data structures
66
67 =item * objects
68
69 =back
70
71 But for now, let's look at some of the general issues common to all
72 of these types of data structures.
73
74 =head1 REFERENCES
75
76 The most important thing to understand about all data structures in Perl
77 -- including multidimensional arrays--is that even though they might
78 appear otherwise, Perl C<@ARRAY>s and C<%HASH>es are all internally
79 one-dimensional.  They can only hold scalar values (meaning a string,
80 number, or a reference).  They cannot directly contain other arrays or
81 hashes, but instead contain I<references> to other arrays or hashes.
82
83 You can't use a reference to a array or hash in quite the same way that
84 you would a real array or hash.  For C or C++ programmers unused to distinguishing
85 between arrays and pointers to the same, this can be confusing.  If so,
86 just think of it as the difference between a structure and a pointer to a
87 structure.
88
89 You can (and should) read more about references in the perlref(1) man
90 page.  Briefly, references are rather like pointers that know what they
91 point to.  (Objects are also a kind of reference, but we won't be needing
92 them right away--if ever.)  This means that when you have something which
93 looks to you like an access to a two-or-more-dimensional array and/or hash,
94 what's really going on is that the base type is
95 merely a one-dimensional entity that contains references to the next
96 level.  It's just that you can I<use> it as though it were a
97 two-dimensional one.  This is actually the way almost all C
98 multidimensional arrays work as well.
99
100     $list[7][12]                        # array of arrays
101     $list[7]{string}                    # array of hashes
102     $hash{string}[7]                    # hash of arrays
103     $hash{string}{'another string'}     # hash of hashes
104
105 Now, because the top level only contains references, if you try to print
106 out your array in with a simple print() function, you'll get something
107 that doesn't look very nice, like this:
108
109     @LoL = ( [2, 3], [4, 5, 7], [0] );
110     print $LoL[1][2];
111   7
112     print @LoL;
113   ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)
114
115
116 That's because Perl doesn't (ever) implicitly dereference your variables.
117 If you want to get at the thing a reference is referring to, then you have
118 to do this yourself using either prefix typing indicators, like
119 C<${$blah}>, C<@{$blah}>, C<@{$blah[$i]}>, or else postfix pointer arrows,
120 like C<$a-E<gt>[3]>, C<$h-E<gt>{fred}>, or even C<$ob-E<gt>method()-E<gt>[3]>.
121
122 =head1 COMMON MISTAKES
123
124 The two most common mistakes made in constructing something like
125 an array of arrays is either accidentally counting the number of
126 elements or else taking a reference to the same memory location
127 repeatedly.  Here's the case where you just get the count instead
128 of a nested array:
129
130     for $i (1..10) {
131         @list = somefunc($i);
132         $LoL[$i] = @list;       # WRONG!
133     }
134
135 That's just the simple case of assigning a list to a scalar and getting
136 its element count.  If that's what you really and truly want, then you
137 might do well to consider being a tad more explicit about it, like this:
138
139     for $i (1..10) {
140         @list = somefunc($i);
141         $counts[$i] = scalar @list;     
142     }
143
144 Here's the case of taking a reference to the same memory location
145 again and again:
146
147     for $i (1..10) {
148         @list = somefunc($i);
149         $LoL[$i] = \@list;      # WRONG!
150     }
151
152 So, just what's the big problem with that?  It looks right, doesn't it?
153 After all, I just told you that you need an array of references, so by
154 golly, you've made me one!
155
156 Unfortunately, while this is true, it's still broken.  All the references
157 in @LoL refer to the I<very same place>, and they will therefore all hold
158 whatever was last in @list!  It's similar to the problem demonstrated in
159 the following C program:
160
161     #include <pwd.h>
162     main() {
163         struct passwd *getpwnam(), *rp, *dp;
164         rp = getpwnam("root");
165         dp = getpwnam("daemon");
166
167         printf("daemon name is %s\nroot name is %s\n",
168                 dp->pw_name, rp->pw_name);
169     }
170
171 Which will print
172
173     daemon name is daemon
174     root name is daemon
175
176 The problem is that both C<rp> and C<dp> are pointers to the same location
177 in memory!  In C, you'd have to remember to malloc() yourself some new
178 memory.  In Perl, you'll want to use the array constructor C<[]> or the
179 hash constructor C<{}> instead.   Here's the right way to do the preceding
180 broken code fragments:
181
182     for $i (1..10) {
183         @list = somefunc($i);
184         $LoL[$i] = [ @list ];
185     }
186
187 The square brackets make a reference to a new array with a I<copy>
188 of what's in @list at the time of the assignment.  This is what
189 you want.
190
191 Note that this will produce something similar, but it's
192 much harder to read:
193
194     for $i (1..10) {
195         @list = 0 .. $i;
196         @{$LoL[$i]} = @list;
197     }
198
199 Is it the same?  Well, maybe so--and maybe not.  The subtle difference
200 is that when you assign something in square brackets, you know for sure
201 it's always a brand new reference with a new I<copy> of the data.
202 Something else could be going on in this new case with the C<@{$LoL[$i]}}>
203 dereference on the left-hand-side of the assignment.  It all depends on
204 whether C<$LoL[$i]> had been undefined to start with, or whether it
205 already contained a reference.  If you had already populated @LoL with
206 references, as in
207
208     $LoL[3] = \@another_list;
209
210 Then the assignment with the indirection on the left-hand-side would
211 use the existing reference that was already there:
212
213     @{$LoL[3]} = @list;
214
215 Of course, this I<would> have the "interesting" effect of clobbering
216 @another_list.  (Have you ever noticed how when a programmer says
217 something is "interesting", that rather than meaning "intriguing",
218 they're disturbingly more apt to mean that it's "annoying",
219 "difficult", or both?  :-)
220
221 So just remember to always use the array or hash constructors with C<[]>
222 or C<{}>, and you'll be fine, although it's not always optimally
223 efficient.
224
225 Surprisingly, the following dangerous-looking construct will
226 actually work out fine:
227
228     for $i (1..10) {
229         my @list = somefunc($i);
230         $LoL[$i] = \@list;
231     }
232
233 That's because my() is more of a run-time statement than it is a
234 compile-time declaration I<per se>.  This means that the my() variable is
235 remade afresh each time through the loop.  So even though it I<looks> as
236 though you stored the same variable reference each time, you actually did
237 not!  This is a subtle distinction that can produce more efficient code at
238 the risk of misleading all but the most experienced of programmers.  So I
239 usually advise against teaching it to beginners.  In fact, except for
240 passing arguments to functions, I seldom like to see the gimme-a-reference
241 operator (backslash) used much at all in code.  Instead, I advise
242 beginners that they (and most of the rest of us) should try to use the
243 much more easily understood constructors C<[]> and C<{}> instead of
244 relying upon lexical (or dynamic) scoping and hidden reference-counting to
245 do the right thing behind the scenes.
246
247 In summary:
248
249     $LoL[$i] = [ @list ];       # usually best
250     $LoL[$i] = \@list;          # perilous; just how my() was that list?
251     @{ $LoL[$i] } = @list;      # way too tricky for most programmers
252
253
254 =head1 CAVEAT ON PRECEDENCE
255
256 Speaking of things like C<@{$LoL[$i]}>, the following are actually the
257 same thing:
258
259     $listref->[2][2]    # clear
260     $$listref[2][2]     # confusing
261
262 That's because Perl's precedence rules on its five prefix dereferencers
263 (which look like someone swearing: C<$ @ * % &>) make them bind more
264 tightly than the postfix subscripting brackets or braces!  This will no
265 doubt come as a great shock to the C or C++ programmer, who is quite
266 accustomed to using C<*a[i]> to mean what's pointed to by the I<i'th>
267 element of C<a>.  That is, they first take the subscript, and only then
268 dereference the thing at that subscript.  That's fine in C, but this isn't C.
269
270 The seemingly equivalent construct in Perl, C<$$listref[$i]> first does
271 the deref of C<$listref>, making it take $listref as a reference to an
272 array, and then dereference that, and finally tell you the I<i'th> value
273 of the array pointed to by $LoL. If you wanted the C notion, you'd have to
274 write C<${$LoL[$i]}> to force the C<$LoL[$i]> to get evaluated first
275 before the leading C<$> dereferencer.
276
277 =head1 WHY YOU SHOULD ALWAYS C<use strict>
278
279 If this is starting to sound scarier than it's worth, relax.  Perl has
280 some features to help you avoid its most common pitfalls.  The best
281 way to avoid getting confused is to start every program like this:
282
283     #!/usr/bin/perl -w
284     use strict;
285
286 This way, you'll be forced to declare all your variables with my() and
287 also disallow accidental "symbolic dereferencing".  Therefore if you'd done
288 this:
289
290     my $listref = [
291         [ "fred", "barney", "pebbles", "bambam", "dino", ],
292         [ "homer", "bart", "marge", "maggie", ],
293         [ "george", "jane", "alroy", "judy", ],
294     ];
295
296     print $listref[2][2];
297
298 The compiler would immediately flag that as an error I<at compile time>,
299 because you were accidentally accessing C<@listref>, an undeclared
300 variable, and it would thereby remind you to instead write:
301
302     print $listref->[2][2]
303
304 =head1 DEBUGGING
305
306 Before 5.002, the standard Perl debugger didn't do a very nice job of
307 printing out complex data structures.  With version 5.002 or above, the
308 debugger includes several new features, including command line editing as
309 well as the C<x> command to dump out complex data structures.  For
310 example, given the assignment to $LoL above, here's the debugger output:
311
312     DB<1> X $LoL
313     $LoL = ARRAY(0x13b5a0)
314        0  ARRAY(0x1f0a24)
315           0  'fred'
316           1  'barney'
317           2  'pebbles'
318           3  'bambam'
319           4  'dino'
320        1  ARRAY(0x13b558)
321           0  'homer'
322           1  'bart'
323           2  'marge'
324           3  'maggie'
325        2  ARRAY(0x13b540)
326           0  'george'
327           1  'jane'
328           2  'alroy'
329           3  'judy'
330
331 There's also a lower-case B<x> command which is nearly the same.
332
333 =head1 CODE EXAMPLES
334
335 Presented with little comment (these will get their own man pages someday)
336 here are short code examples illustrating access of various
337 types of data structures.
338
339 =head1 LISTS OF LISTS
340
341 =head2 Declaration of a LIST OF LISTS
342
343  @LoL = (
344         [ "fred", "barney" ],
345         [ "george", "jane", "elroy" ],
346         [ "homer", "marge", "bart" ],
347       );
348
349 =head2 Generation of a LIST OF LISTS
350
351  # reading from file
352  while ( <> ) {
353      push @LoL, [ split ];
354  }
355
356  # calling a function
357  for $i ( 1 .. 10 ) {
358      $LoL[$i] = [ somefunc($i) ];
359  }
360
361  # using temp vars
362  for $i ( 1 .. 10 ) {
363      @tmp = somefunc($i);
364      $LoL[$i] = [ @tmp ];
365  }
366
367  # add to an existing row
368  push @{ $LoL[0] }, "wilma", "betty";
369
370 =head2 Access and Printing of a LIST OF LISTS
371
372  # one element
373  $LoL[0][0] = "Fred";
374
375  # another element
376  $LoL[1][1] =~ s/(\w)/\u$1/;
377
378  # print the whole thing with refs
379  for $aref ( @LoL ) {
380      print "\t [ @$aref ],\n";
381  }
382
383  # print the whole thing with indices
384  for $i ( 0 .. $#LoL ) {
385      print "\t [ @{$LoL[$i]} ],\n";
386  }
387
388  # print the whole thing one at a time
389  for $i ( 0 .. $#LoL ) {
390      for $j ( 0 .. $#{$LoL[$i]} ) {
391          print "elt $i $j is $LoL[$i][$j]\n";
392      }
393  }
394
395 =head1 HASHES OF LISTS
396
397 =head2 Declaration of a HASH OF LISTS
398
399  %HoL = (
400         "flintstones"        => [ "fred", "barney" ],
401         "jetsons"            => [ "george", "jane", "elroy" ],
402         "simpsons"           => [ "homer", "marge", "bart" ],
403       );
404
405 =head2 Generation of a HASH OF LISTS
406
407  # reading from file
408  # flintstones: fred barney wilma dino
409  while ( <> ) {
410      next unless s/^(.*?):\s*//;
411      $HoL{$1} = [ split ];
412  }
413
414  # reading from file; more temps
415  # flintstones: fred barney wilma dino
416  while ( $line = <> ) {
417      ($who, $rest) = split /:\s*/, $line, 2;
418      @fields = split ' ', $rest;
419      $HoL{$who} = [ @fields ];
420  }
421
422  # calling a function that returns a list
423  for $group ( "simpsons", "jetsons", "flintstones" ) {
424      $HoL{$group} = [ get_family($group) ];
425  }
426
427  # likewise, but using temps
428  for $group ( "simpsons", "jetsons", "flintstones" ) {
429      @members = get_family($group);
430      $HoL{$group} = [ @members ];
431  }
432
433  # append new members to an existing family
434  push @{ $HoL{"flintstones"} }, "wilma", "betty";
435
436 =head2 Access and Printing of a HASH OF LISTS
437
438  # one element
439  $HoL{flintstones}[0] = "Fred";
440
441  # another element
442  $HoL{simpsons}[1] =~ s/(\w)/\u$1/;
443
444  # print the whole thing
445  foreach $family ( keys %HoL ) {
446      print "$family: @{ $HoL{$family} }\n"
447  }
448
449  # print the whole thing with indices
450  foreach $family ( keys %HoL ) {
451      print "family: ";
452      foreach $i ( 0 .. $#{ $HoL{$family} ) {
453          print " $i = $HoL{$family}[$i]";
454      }
455      print "\n";
456  }
457
458  # print the whole thing sorted by number of members
459  foreach $family ( sort { @{$HoL{$b}} <=> @{$HoL{$b}} } keys %HoL ) {
460      print "$family: @{ $HoL{$family} }\n"
461  }
462
463  # print the whole thing sorted by number of members and name
464  foreach $family ( sort { @{$HoL{$b}} <=> @{$HoL{$a}} } keys %HoL ) {
465      print "$family: ", join(", ", sort @{ $HoL{$family}), "\n";
466  }
467
468 =head1 LISTS OF HASHES
469
470 =head2 Declaration of a LIST OF HASHES
471
472  @LoH = (
473         {
474             Lead     => "fred",
475             Friend   => "barney",
476         },
477         {
478             Lead     => "george",
479             Wife     => "jane",
480             Son      => "elroy",
481         },
482         {
483             Lead     => "homer",
484             Wife     => "marge",
485             Son      => "bart",
486         }
487   );
488
489 =head2 Generation of a LIST OF HASHES
490
491  # reading from file
492  # format: LEAD=fred FRIEND=barney
493  while ( <> ) {
494      $rec = {};
495      for $field ( split ) {
496          ($key, $value) = split /=/, $field;
497          $rec->{$key} = $value;
498      }
499      push @LoH, $rec;
500  }
501
502
503  # reading from file
504  # format: LEAD=fred FRIEND=barney
505  # no temp
506  while ( <> ) {
507      push @LoH, { split /[\s+=]/ };
508  }
509
510  # calling a function  that returns a key,value list, like
511  # "lead","fred","daughter","pebbles"
512  while ( %fields = getnextpairset() ) {
513      push @LoH, { %fields };
514  }
515
516  # likewise, but using no temp vars
517  while (<>) {
518      push @LoH, { parsepairs($_) };
519  }
520
521  # add key/value to an element
522  $LoH[0]{pet} = "dino";
523  $LoH[2]{pet} = "santa's little helper";
524
525 =head2 Access and Printing of a LIST OF HASHES
526
527  # one element
528  $LoH[0]{lead} = "fred";
529
530  # another element
531  $LoH[1]{lead} =~ s/(\w)/\u$1/;
532
533  # print the whole thing with refs
534  for $href ( @LoH ) {
535      print "{ ";
536      for $role ( keys %$href ) {
537          print "$role=$href->{$role} ";
538      }
539      print "}\n";
540  }
541
542  # print the whole thing with indices
543  for $i ( 0 .. $#LoH ) {
544      print "$i is { ";
545      for $role ( keys %{ $LoH[$i] } ) {
546          print "$role=$LoH[$i]{$role} ";
547      }
548      print "}\n";
549  }
550
551  # print the whole thing one at a time
552  for $i ( 0 .. $#LoH ) {
553      for $role ( keys %{ $LoH[$i] } ) {
554          print "elt $i $role is $LoH[$i]{$role}\n";
555      }
556  }
557
558 =head1 HASHES OF HASHES
559
560 =head2 Declaration of a HASH OF HASHES
561
562  %HoH = (
563         "flintstones" => {
564             "lead"    => "fred",
565             "pal"     => "barney",
566         },
567         "jetsons"     => {
568             "lead"    => "george",
569             "wife"    => "jane",
570             "his boy" => "elroy",
571         },
572         "simpsons"    => {
573              "lead"   => "homer",
574              "wife"   => "marge",
575              "kid"    => "bart",
576         },
577  );
578
579 =head2 Generation of a HASH OF HASHES
580
581  # reading from file
582  # flintstones: lead=fred pal=barney wife=wilma pet=dino
583  while ( <> ) {
584      next unless s/^(.*?):\s*//;
585      $who = $1;
586      for $field ( split ) {
587          ($key, $value) = split /=/, $field;
588          $HoH{$who}{$key} = $value;
589      }
590
591
592  # reading from file; more temps
593  while ( <> ) {
594      next unless s/^(.*?):\s*//;
595      $who = $1;
596      $rec = {};
597      $HoH{$who} = $rec;
598      for $field ( split ) {
599          ($key, $value) = split /=/, $field;
600          $rec->{$key} = $value;
601      }
602  }
603
604  # calling a function  that returns a key,value hash
605  for $group ( "simpsons", "jetsons", "flintstones" ) {
606      $HoH{$group} = { get_family($group) };
607  }
608
609  # likewise, but using temps
610  for $group ( "simpsons", "jetsons", "flintstones" ) {
611      %members = get_family($group);
612      $HoH{$group} = { %members };
613  }
614
615  # append new members to an existing family
616  %new_folks = (
617      "wife" => "wilma",
618      "pet"  => "dino";
619  );
620
621  for $what (keys %new_folks) {
622      $HoH{flintstones}{$what} = $new_folks{$what};
623  }
624
625 =head2 Access and Printing of a HASH OF HASHES
626
627  # one element
628  $HoH{flintstones}{wife} = "wilma";
629
630  # another element
631  $HoH{simpsons}{lead} =~ s/(\w)/\u$1/;
632
633  # print the whole thing
634  foreach $family ( keys %HoH ) {
635      print "$family: { ";
636      for $role ( keys %{ $HoH{$family} } ) {
637          print "$role=$HoH{$family}{$role} ";
638      }
639      print "}\n";
640  }
641
642  # print the whole thing  somewhat sorted
643  foreach $family ( sort keys %HoH ) {
644      print "$family: { ";
645      for $role ( sort keys %{ $HoH{$family} } ) {
646          print "$role=$HoH{$family}{$role} ";
647      }
648      print "}\n";
649  }
650
651
652  # print the whole thing sorted by number of members
653  foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$b}} } keys %HoH ) {
654      print "$family: { ";
655      for $role ( sort keys %{ $HoH{$family} } ) {
656          print "$role=$HoH{$family}{$role} ";
657      }
658      print "}\n";
659  }
660
661  # establish a sort order (rank) for each role
662  $i = 0;
663  for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i }
664
665  # now print the whole thing sorted by number of members
666  foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$b}} } keys %HoH ) {
667      print "$family: { ";
668      # and print these according to rank order
669      for $role ( sort { $rank{$a} <=> $rank{$b} keys %{ $HoH{$family} } } ) {
670          print "$role=$HoH{$family}{$role} ";
671      }
672      print "}\n";
673  }
674
675
676 =head1 MORE ELABORATE RECORDS
677
678 =head2 Declaration of MORE ELABORATE RECORDS
679
680 Here's a sample showing how to create and use a record whose fields are of
681 many different sorts:
682
683      $rec = {
684          TEXT      => $string,
685          SEQUENCE  => [ @old_values ],
686          LOOKUP    => { %some_table },
687          THATCODE  => \&some_function,
688          THISCODE  => sub { $_[0] ** $_[1] },
689          HANDLE    => \*STDOUT,
690      };
691
692      print $rec->{TEXT};
693
694      print $rec->{LIST}[0];
695      $last = pop @ { $rec->{SEQUENCE} };
696
697      print $rec->{LOOKUP}{"key"};
698      ($first_k, $first_v) = each %{ $rec->{LOOKUP} };
699
700      $answer = &{ $rec->{THATCODE} }($arg);
701      $answer = &{ $rec->{THISCODE} }($arg1, $arg2);
702
703      # careful of extra block braces on fh ref
704      print { $rec->{HANDLE} } "a string\n";
705
706      use FileHandle;
707      $rec->{HANDLE}->autoflush(1);
708      $rec->{HANDLE}->print(" a string\n");
709
710 =head2 Declaration of a HASH OF COMPLEX RECORDS
711
712      %TV = (
713         "flintstones" => {
714             series   => "flintstones",
715             nights   => [ qw(monday thursday friday) ],
716             members  => [
717                 { name => "fred",    role => "lead", age  => 36, },
718                 { name => "wilma",   role => "wife", age  => 31, },
719                 { name => "pebbles", role => "kid",  age  =>  4, },
720             ],
721         },
722
723         "jetsons"     => {
724             series   => "jetsons",
725             nights   => [ qw(wednesday saturday) ],
726             members  => [
727                 { name => "george",  role => "lead", age  => 41, },
728                 { name => "jane",    role => "wife", age  => 39, },
729                 { name => "elroy",   role => "kid",  age  =>  9, },
730             ],
731          },
732
733         "simpsons"    => {
734             series   => "simpsons",
735             nights   => [ qw(monday) ],
736             members  => [
737                 { name => "homer", role => "lead", age  => 34, },
738                 { name => "marge", role => "wife", age => 37, },
739                 { name => "bart",  role => "kid",  age  =>  11, },
740             ],
741          },
742       );
743
744 =head2 Generation of a HASH OF COMPLEX RECORDS
745
746      # reading from file
747      # this is most easily done by having the file itself be
748      # in the raw data format as shown above.  perl is happy
749      # to parse complex datastructures if declared as data, so
750      # sometimes it's easiest to do that
751
752      # here's a piece by piece build up
753      $rec = {};
754      $rec->{series} = "flintstones";
755      $rec->{nights} = [ find_days() ];
756
757      @members = ();
758      # assume this file in field=value syntax
759      while (<>) {
760          %fields = split /[\s=]+/;
761          push @members, { %fields };
762      }
763      $rec->{members} = [ @members ];
764
765      # now remember the whole thing
766      $TV{ $rec->{series} } = $rec;
767
768      ###########################################################
769      # now, you might want to make interesting extra fields that
770      # include pointers back into the same data structure so if
771      # change one piece, it changes everywhere, like for examples
772      # if you wanted a {kids} field that was an array reference
773      # to a list of the kids' records without having duplicate
774      # records and thus update problems.
775      ###########################################################
776      foreach $family (keys %TV) {
777          $rec = $TV{$family}; # temp pointer
778          @kids = ();
779          for $person ( @{$rec->{members}} ) {
780              if ($person->{role} =~ /kid|son|daughter/) {
781                  push @kids, $person;
782              }
783          }
784          # REMEMBER: $rec and $TV{$family} point to same data!!
785          $rec->{kids} = [ @kids ];
786      }
787
788      # you copied the list, but the list itself contains pointers
789      # to uncopied objects. this means that if you make bart get
790      # older via
791
792      $TV{simpsons}{kids}[0]{age}++;
793
794      # then this would also change in
795      print $TV{simpsons}{members}[2]{age};
796
797      # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2]
798      # both point to the same underlying anonymous hash table
799
800      # print the whole thing
801      foreach $family ( keys %TV ) {
802          print "the $family";
803          print " is on during @{ $TV{$family}{nights} }\n";
804          print "its members are:\n";
805          for $who ( @{ $TV{$family}{members} } ) {
806              print " $who->{name} ($who->{role}), age $who->{age}\n";
807          }
808          print "it turns out that $TV{$family}{'lead'} has ";
809          print scalar ( @{ $TV{$family}{kids} } ), " kids named ";
810          print join (", ", map { $_->{name} } @{ $TV{$family}{kids} } );
811          print "\n";
812      }
813
814 =head1 Database Ties
815
816 You cannot easily tie a multilevel data structure (such as a hash of
817 hashes) to a dbm file.  The first problem is that all but GDBM and
818 Berkeley DB have size limitations, but beyond that, you also have problems
819 with how references are to be represented on disk.  One experimental
820 module that does attempt to partially address this need is the MLDBM
821 module.  Check your nearest CPAN site as described in L<perlmod> for
822 source code to MLDBM.
823
824 =head1 SEE ALSO
825
826 perlref(1), perllol(1), perldata(1), perlobj(1)
827
828 =head1 AUTHOR
829
830 Tom Christiansen E<lt>F<tchrist@perl.com>E<gt>
831
832 Last update:
833 Mon Jul  8 05:22:49 MDT 1996