From c25c5c3c87d89b68324dc98b7c8aaabc750c7cec Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Thu, 29 Apr 1999 22:53:00 +0000 Subject: perl5.005_03 (stock) --- gnu/usr.bin/perl/pod/perltie.pod | 66 +++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 18 deletions(-) (limited to 'gnu/usr.bin/perl/pod/perltie.pod') diff --git a/gnu/usr.bin/perl/pod/perltie.pod b/gnu/usr.bin/perl/pod/perltie.pod index c6eb7156ce3..665265818d3 100644 --- a/gnu/usr.bin/perl/pod/perltie.pod +++ b/gnu/usr.bin/perl/pod/perltie.pod @@ -23,7 +23,7 @@ Now you can. The tie() function binds a variable to a class (package) that will provide the implementation for access methods for that variable. Once this magic has been performed, accessing a tied variable automatically triggers -method calls in the proper class. All of the complexity of the class is +method calls in the proper class. The complexity of the class is hidden behind magic methods calls. The method names are in ALL CAPS, which is a convention that Perl uses to indicate that they're called implicitly rather than explicitly--just like the BEGIN() and END() @@ -180,17 +180,26 @@ TIESCALAR classes are certainly possible. =head2 Tying Arrays A class implementing a tied ordinary array should define the following -methods: TIEARRAY, FETCH, STORE, and perhaps DESTROY. +methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY. -B: Tied arrays are I. They are also distinctly lacking -something for the C<$#ARRAY> access (which is hard, as it's an lvalue), as -well as the other obvious array functions, like push(), pop(), shift(), -unshift(), and splice(). +FETCHSIZE and STORESIZE are used to provide C<$#array> and +equivalent C access. + +The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE are required if the perl +operator with the corresponding (but lowercase) name is to operate on the +tied array. The B class can be used as a base class to implement +these in terms of the basic five methods above. + +In addition EXTEND will be called when perl would have pre-extended +allocation in a real array. + +This means that tied arrays are now I. The example below needs +upgrading to illustrate this. (The documentation in B is more +complete.) For this discussion, we'll implement an array whose indices are fixed at its creation. If you try to access anything beyond those bounds, you'll -take an exception. (Well, if you access an individual element; an -aggregate assignment would be missed.) For example: +take an exception. For example: require Bounded_Array; tie @ary, 'Bounded_Array', 2; @@ -594,9 +603,9 @@ or have auxiliary state to clean up. Here's a very simple function: =back -Note that functions such as keys() and values() may return huge array -values when used on large objects, like DBM files. You may prefer to -use the each() function to iterate over such. Example: +Note that functions such as keys() and values() may return huge lists +when used on large objects, like DBM files. You may prefer to use the +each() function to iterate over such. Example: # print out history file offsets use NDBM_File; @@ -611,8 +620,8 @@ use the each() function to iterate over such. Example: This is partially implemented now. A class implementing a tied filehandle should define the following -methods: TIEHANDLE, at least one of PRINT, PRINTF, READLINE, GETC, or READ, -and possibly DESTROY. +methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC, +READ, and possibly CLOSE and DESTROY. It is especially useful when perl is embedded in some other program, where output to STDOUT and STDERR may have to be redirected in some @@ -632,6 +641,17 @@ hold some internal information. sub TIEHANDLE { print "\n"; my $i; bless \$i, shift } +=item WRITE this, LIST + +This method will be called when the handle is written to via the +C function. + + sub WRITE { + $r = shift; + my($buf,$len,$offset) = @_; + print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset"; + } + =item PRINT this, LIST This method will be triggered every time the tied handle is printed to @@ -654,15 +674,18 @@ passed to the printf function. print sprintf($fmt, @_)."\n"; } -=item READ this LIST +=item READ this, LIST This method will be called when the handle is read from via the C or C functions. sub READ { - $r = shift; - my($buf,$len,$offset) = @_; - print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset"; + my $self = shift; + my $$bufref = \$_[0]; + my(undef,$len,$offset) = @_; + print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset"; + # add to $$bufref, set $len to number of characters read + $len; } =item READLINE this @@ -670,7 +693,7 @@ or C functions. This method will be called when the handle is read from via . The method should return undef when there is no more data. - sub READLINE { $r = shift; "PRINT called $$r times\n"; } + sub READLINE { $r = shift; "READLINE called $$r times\n"; } =item GETC this @@ -678,6 +701,13 @@ This method will be called when the C function is called. sub GETC { print "Don't GETC, Get Perl"; return "a"; } +=item CLOSE this + +This method will be called when the handle is closed via the C +function. + + sub CLOSE { print "CLOSE called.\n" } + =item DESTROY this As with the other types of ties, this method will be called when the -- cgit v1.2.3