1package Tie::Handle; 2 3=head1 NAME 4 5Tie::Handle - base class definitions for tied handles 6 7=head1 SYNOPSIS 8 9 package NewHandle; 10 require Tie::Handle; 11 12 @ISA = (Tie::Handle); 13 14 sub READ { ... } # Provide a needed method 15 sub TIEHANDLE { ... } # Overrides inherited method 16 17 18 package main; 19 20 tie *FH, 'NewHandle'; 21 22=head1 DESCRIPTION 23 24This module provides some skeletal methods for handle-tying classes. See 25L<perltie> for a list of the functions required in tying a handle to a package. 26The basic B<Tie::Handle> package provides a C<new> method, as well as methods 27C<TIESCALAR>, C<FETCH> and C<STORE>. The C<new> method is provided as a means 28of grandfathering, for classes that forget to provide their own C<TIESCALAR> 29method. 30 31For developers wishing to write their own tied-handle classes, the methods 32are summarized below. The L<perltie> section not only documents these, but 33has sample code as well: 34 35=over 36 37=item TIEHANDLE classname, LIST 38 39The method invoked by the command C<tie *glob, classname>. Associates a new 40glob instance with the specified class. C<LIST> would represent additional 41arguments (along the lines of L<AnyDBM_File> and compatriots) needed to 42complete the association. 43 44=item WRITE this, scalar, length, offset 45 46Write I<length> bytes of data from I<scalar> starting at I<offset>. 47 48=item PRINT this, LIST 49 50Print the values in I<LIST> 51 52=item PRINTF this, format, LIST 53 54Print the values in I<LIST> using I<format> 55 56=item READ this, scalar, length, offset 57 58Read I<length> bytes of data into I<scalar> starting at I<offset>. 59 60=item READLINE this 61 62Read a single line 63 64=item GETC this 65 66Get a single character 67 68=item DESTROY this 69 70Free the storage associated with the tied handle referenced by I<this>. 71This is rarely needed, as Perl manages its memory quite well. But the 72option exists, should a class wish to perform specific actions upon the 73destruction of an instance. 74 75=back 76 77=head1 MORE INFORMATION 78 79The L<perltie> section contains an example of tying handles. 80 81=cut 82 83use Carp; 84 85sub new { 86 my $pkg = shift; 87 $pkg->TIEHANDLE(@_); 88} 89 90# "Grandfather" the new, a la Tie::Hash 91 92sub TIEHANDLE { 93 my $pkg = shift; 94 if (defined &{"{$pkg}::new"}) { 95 carp "WARNING: calling ${pkg}->new since ${pkg}->TIEHANDLE is missing" 96 if $^W; 97 $pkg->new(@_); 98 } 99 else { 100 croak "$pkg doesn't define a TIEHANDLE method"; 101 } 102} 103 104sub PRINT { 105 my $self = shift; 106 if($self->can('WRITE') != \&WRITE) { 107 my $buf = join(defined $, ? $, : "",@_); 108 $buf .= $\ if defined $\; 109 $self->WRITE($buf,length($buf),0); 110 } 111 else { 112 croak ref($self)," doesn't define a PRINT method"; 113 } 114} 115 116sub PRINTF { 117 my $self = shift; 118 119 if($self->can('WRITE') != \&WRITE) { 120 my $buf = sprintf(@_); 121 $self->WRITE($buf,length($buf),0); 122 } 123 else { 124 croak ref($self)," doesn't define a PRINTF method"; 125 } 126} 127 128sub READLINE { 129 my $pkg = ref $_[0]; 130 croak "$pkg doesn't define a READLINE method"; 131} 132 133sub GETC { 134 my $self = shift; 135 136 if($self->can('READ') != \&READ) { 137 my $buf; 138 $self->READ($buf,1); 139 return $buf; 140 } 141 else { 142 croak ref($self)," doesn't define a GETC method"; 143 } 144} 145 146sub READ { 147 my $pkg = ref $_[0]; 148 croak "$pkg doesn't define a READ method"; 149} 150 151sub WRITE { 152 my $pkg = ref $_[0]; 153 croak "$pkg doesn't define a WRITE method"; 154} 155 156sub CLOSE { 157 my $pkg = ref $_[0]; 158 croak "$pkg doesn't define a CLOSE method"; 159} 160 1611; 162