POD index entries with X<>

Message-ID: <434D9A32.4050305@cpan.org>

p4raw-id: //depot/perl@25748

1 files changed, 49 insertions, 0 deletions

diff --git a/pod/perltie.pod b/pod/perltie.pod
index b64357665f..b4c2baf20f 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -1,4 +1,5 @@
 =head1 NAME
+X<tie>
 
 perltie - how to hide an object class in a simple variable
 
@@ -46,6 +47,7 @@ Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
 for you--you need to do that explicitly yourself.
 
 =head2 Tying Scalars
+X<scalar, tying>
 
 A class implementing a tied scalar should define the following methods:
 TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
@@ -74,6 +76,7 @@ calls.  Here's the preamble of the class.
 =over 4
 
 =item TIESCALAR classname, LIST
+X<TIESCALAR>
 
 This is the constructor for the class.  That means it is
 expected to return a blessed reference to a new scalar
@@ -102,6 +105,7 @@ other classes may well not wish to be so forgiving.  It checks the global
 variable C<$^W> to see whether to emit a bit of noise anyway.
 
 =item FETCH this
+X<FETCH>
 
 This method will be triggered every time the tied variable is accessed
 (read).  It takes no arguments beyond its self reference, which is the
@@ -126,6 +130,7 @@ fails--there's no place for us to return an error otherwise, and it's
 probably the right thing to do.
 
 =item STORE this, value
+X<STORE>
 
 This method will be triggered every time the tied variable is set
 (assigned).  Beyond its self reference, it also expects one (and only one)
@@ -159,12 +164,14 @@ assigned value is implemented with FETCH.
     }
 
 =item UNTIE this
+X<UNTIE>
 
 This method will be triggered when the C<untie> occurs. This can be useful
 if the class needs to know when no further calls will be made. (Except DESTROY
 of course.) See L<The C<untie> Gotcha> below for more details.
 
 =item DESTROY this
+X<DESTROY>
 
 This method will be triggered when the tied variable needs to be destructed.
 As with other object classes, such a method is seldom necessary, because Perl
@@ -185,6 +192,7 @@ of completeness, robustness, and general aesthetics.  Simpler
 TIESCALAR classes are certainly possible.
 
 =head2 Tying Arrays
+X<array, tying>
 
 A class implementing a tied ordinary array should define the following
 methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
@@ -220,6 +228,7 @@ The preamble code for the class is as follows:
 =over 4
 
 =item TIEARRAY classname, LIST
+X<TIEARRAY>
 
 This is the constructor for the class.  That means it is expected to
 return a blessed reference through which the new array (probably an
@@ -246,6 +255,7 @@ This just goes to show you that you should respect an object's privacy.
     }
 
 =item FETCH this, index
+X<FETCH>
 
 This method will be triggered every time an individual element the tied array
 is accessed (read).  It takes one argument beyond its self reference: the
@@ -270,6 +280,7 @@ several tied types, in practice this becomes cumbersome, and it's easiest
 to keep them at simply one tie type per class.
 
 =item STORE this, index, value
+X<STORE>
 
 This method will be triggered every time an element in the tied array is set
 (written).  It takes two arguments beyond its self reference: the index at
@@ -294,6 +305,7 @@ spaces so we have a little more work to do here:
 Negative indexes are treated the same as with FETCH.
 
 =item FETCHSIZE this
+X<FETCHSIZE>
 
 Returns the total number of items in the tied array associated with
 object I<this>. (Equivalent to C<scalar(@array)>).  For example:
@@ -304,6 +316,7 @@ object I<this>. (Equivalent to C<scalar(@array)>).  For example:
     }
 
 =item STORESIZE this, count
+X<STORESIZE>
 
 Sets the total number of items in the tied array associated with
 object I<this> to be I<count>. If this makes the array larger then
@@ -329,6 +342,7 @@ C<$self-E<gt>{ELEMSIZE}> number of spaces.  Observe:
     }
 
 =item EXTEND this, count
+X<EXTEND>
 
 Informative call that array is likely to grow to have I<count> entries.
 Can be used to optimize allocation. This method need do nothing.
@@ -344,6 +358,7 @@ as needed:
     }
 
 =item EXISTS this, key
+X<EXISTS>
 
 Verify that the element at index I<key> exists in the tied array I<this>.
 
@@ -359,6 +374,7 @@ C<$self-E<gt>{ELEMSIZE}> spaces only, it does not exist:
     }
 
 =item DELETE this, key
+X<DELETE>
 
 Delete the element at index I<key> from the tied array I<this>.
 
@@ -371,6 +387,7 @@ In our example, a deleted item is C<$self-E<gt>{ELEMSIZE}> spaces:
     }
 
 =item CLEAR this
+X<CLEAR>
 
 Clear (remove, delete, ...) all values from the tied array associated with
 object I<this>.  For example:
@@ -381,6 +398,7 @@ object I<this>.  For example:
     }
 
 =item PUSH this, LIST 
+X<PUSH>
 
 Append elements of I<LIST> to the array.  For example:
 
@@ -393,6 +411,7 @@ Append elements of I<LIST> to the array.  For example:
     }   
 
 =item POP this
+X<POP>
 
 Remove last element of the array and return it.  For example:
 
@@ -402,6 +421,7 @@ Remove last element of the array and return it.  For example:
     }
 
 =item SHIFT this
+X<SHIFT>
 
 Remove the first element of the array (shifting other elements down)
 and return it.  For example:
@@ -412,6 +432,7 @@ and return it.  For example:
     }
 
 =item UNSHIFT this, LIST 
+X<UNSHIFT>
 
 Insert LIST elements at the beginning of the array, moving existing elements
 up to make room.  For example:
@@ -427,6 +448,7 @@ up to make room.  For example:
     }
 
 =item SPLICE this, offset, length, LIST
+X<SPLICE>
 
 Perform the equivalent of C<splice> on the array. 
 
@@ -454,10 +476,12 @@ In our example, we'll use a little shortcut if there is a I<LIST>:
     }
 
 =item UNTIE this
+X<UNTIE>
 
 Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.)
 
 =item DESTROY this
+X<DESTROY>
 
 This method will be triggered when the tied variable needs to be destructed.
 As with the scalar tie class, this is almost never needed in a
@@ -467,6 +491,7 @@ just leave it out.
 =back
 
 =head2 Tying Hashes
+X<hash, tying>
 
 Hashes were the first Perl data type to be tied (see dbmopen()).  A class
 implementing a tied hash should define the following methods: TIEHASH is
@@ -552,6 +577,7 @@ Here are the methods for the DotFiles tied hash.
 =over 4
 
 =item TIEHASH classname, LIST
+X<TIEHASH>
 
 This is the constructor for the class.  That means it is expected to
 return a blessed reference through which the new object (probably but not
@@ -592,6 +618,7 @@ in question.  Otherwise, because we didn't chdir() there, it would
 have been testing the wrong file.
 
 =item FETCH this, key
+X<FETCH>
 
 This method will be triggered every time an element in the tied hash is
 accessed (read).  It takes one argument beyond its self reference: the key
@@ -624,6 +651,7 @@ more efficient).  Of course, because dot files are a Unixy concept, we're
 not that concerned.
 
 =item STORE this, key, value
+X<STORE>
 
 This method will be triggered every time an element in the tied hash is set
 (written).  It takes two arguments beyond its self reference: the index at
@@ -671,6 +699,7 @@ The clobber method is simply:
     }
 
 =item DELETE this, key
+X<DELETE>
 
 This method is triggered when we remove an element from the hash,
 typically by using the delete() function.  Again, we'll
@@ -697,6 +726,7 @@ In this example, we have chosen instead to return a value which tells
 the caller whether the file was successfully deleted.
 
 =item CLEAR this
+X<CLEAR>
 
 This method is triggered when the whole hash is to be cleared, usually by
 assigning the empty list to it.
@@ -717,6 +747,7 @@ dangerous thing that they'll have to set CLOBBER to something higher than
     }
 
 =item EXISTS this, key
+X<EXISTS>
 
 This method is triggered when the user uses the exists() function
 on a particular hash.  In our example, we'll look at the C<{LIST}>
@@ -730,6 +761,7 @@ hash element for this:
     }
 
 =item FIRSTKEY this
+X<FIRSTKEY>
 
 This method will be triggered when the user is going
 to iterate through the hash, such as via a keys() or each()
@@ -743,6 +775,7 @@ call.
     }
 
 =item NEXTKEY this, lastkey
+X<NEXTKEY>
 
 This method gets triggered during a keys() or each() iteration.  It has a
 second argument which is the last key that had been accessed.  This is
@@ -759,6 +792,7 @@ thing, but we'll have to go through the LIST field indirectly.
     }
 
 =item SCALAR this
+X<SCALAR>
 
 This is called when the hash is evaluated in scalar context. In order
 to mimic the behaviour of untied hashes, this method should return a
@@ -784,10 +818,12 @@ referenced by C<$self-E<gt>{LIST}>:
     }
 
 =item UNTIE this
+X<UNTIE>
 
 This is called when C<untie> occurs.  See L<The C<untie> Gotcha> below.
 
 =item DESTROY this
+X<DESTROY>
 
 This method is triggered when a tied hash is about to go out of
 scope.  You don't really need it unless you're trying to add debugging
@@ -812,6 +848,7 @@ each() function to iterate over such.  Example:
     untie(%HIST);
 
 =head2 Tying FileHandles
+X<filehandle, tying>
 
 This is partially implemented now.
 
@@ -839,6 +876,7 @@ In our example we're going to create a shouting handle.
 =over 4
 
 =item TIEHANDLE classname, LIST
+X<TIEHANDLE>
 
 This is the constructor for the class.  That means it is expected to
 return a blessed reference of some sort. The reference can be used to
@@ -847,6 +885,7 @@ hold some internal information.
     sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
 
 =item WRITE this, LIST
+X<WRITE>
 
 This method will be called when the handle is written to via the
 C<syswrite> function.
@@ -858,6 +897,7 @@ C<syswrite> function.
     }
 
 =item PRINT this, LIST
+X<PRINT>
 
 This method will be triggered every time the tied handle is printed to
 with the C<print()> function.
@@ -867,6 +907,7 @@ the print function.
     sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
 
 =item PRINTF this, LIST
+X<PRINTF>
 
 This method will be triggered every time the tied handle is printed to
 with the C<printf()> function.
@@ -880,6 +921,7 @@ passed to the printf function.
     }
 
 =item READ this, LIST
+X<READ>
 
 This method will be called when the handle is read from via the C<read>
 or C<sysread> functions.
@@ -894,6 +936,7 @@ or C<sysread> functions.
     }
 
 =item READLINE this
+X<READLINE>
 
 This method will be called when the handle is read from via <HANDLE>.
 The method should return undef when there is no more data.
@@ -901,12 +944,14 @@ The method should return undef when there is no more data.
     sub READLINE { $r = shift; "READLINE called $$r times\n"; }
 
 =item GETC this
+X<GETC>
 
 This method will be called when the C<getc> function is called.
 
     sub GETC { print "Don't GETC, Get Perl"; return "a"; }
 
 =item CLOSE this
+X<CLOSE>
 
 This method will be called when the handle is closed via the C<close>
 function.
@@ -914,12 +959,14 @@ function.
     sub CLOSE { print "CLOSE called.\n" }
 
 =item UNTIE this
+X<UNTIE>
 
 As with the other types of ties, this method will be called when C<untie> happens.
 It may be appropriate to "auto CLOSE" when this occurs.  See
 L<The C<untie> Gotcha> below.
 
 =item DESTROY this
+X<DESTROY>
 
 As with the other types of ties, this method will be called when the
 tied handle is about to be destroyed. This is useful for debugging and
@@ -938,11 +985,13 @@ Here's how to use our little example:
     print <FOO>;
 
 =head2 UNTIE this
+X<UNTIE>
 
 You can define for all tie types an UNTIE method that will be called
 at untie().  See L<The C<untie> Gotcha> below.
 
 =head2 The C<untie> Gotcha
+X<untie>
 
 If you intend making use of the object returned from either tie() or
 tied(), and if the tie's target class defines a destructor, there is a