5 Tie::Handle, Tie::StdHandle - base class definitions for tied handles
14 sub READ { ... } # Provide a needed method
15 sub TIEHANDLE { ... } # Overrides inherited method
24 This module provides some skeletal methods for handle-tying classes. See
25 L<perltie> for a list of the functions required in tying a handle to a package.
26 The basic B<Tie::Handle> package provides a C<new> method, as well as methods
27 C<TIEHANDLE>, C<PRINT>, C<PRINTF> and C<GETC>.
29 For developers wishing to write their own tied-handle classes, the methods
30 are summarized below. The L<perltie> section not only documents these, but
31 has sample code as well:
35 =item TIEHANDLE classname, LIST
37 The method invoked by the command C<tie *glob, classname>. Associates a new
38 glob instance with the specified class. C<LIST> would represent additional
39 arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
40 complete the association.
42 =item WRITE this, scalar, length, offset
44 Write I<length> bytes of data from I<scalar> starting at I<offset>.
46 =item PRINT this, LIST
48 Print the values in I<LIST>
50 =item PRINTF this, format, LIST
52 Print the values in I<LIST> using I<format>
54 =item READ this, scalar, length, offset
56 Read I<length> bytes of data into I<scalar> starting at I<offset>.
64 Get a single character
70 =item OPEN this, filename
76 Specify content is binary
84 Return position in the file.
86 =item SEEK this, offset, whence
94 Free the storage associated with the tied handle referenced by I<this>.
95 This is rarely needed, as Perl manages its memory quite well. But the
96 option exists, should a class wish to perform specific actions upon the
97 destruction of an instance.
101 =head1 MORE INFORMATION
103 The L<perltie> section contains an example of tying handles.
114 # "Grandfather" the new, a la Tie::Hash
118 if (defined &{"{$pkg}::new"}) {
119 carp "WARNING: calling ${pkg}->new since ${pkg}->TIEHANDLE is missing"
124 croak "$pkg doesn't define a TIEHANDLE method";
130 if($self->can('WRITE') != \&WRITE) {
131 my $buf = join(defined $, ? $, : "",@_);
132 $buf .= $\ if defined $\;
133 $self->WRITE($buf,length($buf),0);
136 croak ref($self)," doesn't define a PRINT method";
143 if($self->can('WRITE') != \&WRITE) {
144 my $buf = sprintf(shift,@_);
145 $self->WRITE($buf,length($buf),0);
148 croak ref($self)," doesn't define a PRINTF method";
154 croak "$pkg doesn't define a READLINE method";
160 if($self->can('READ') != \&READ) {
166 croak ref($self)," doesn't define a GETC method";
172 croak "$pkg doesn't define a READ method";
177 croak "$pkg doesn't define a WRITE method";
182 croak "$pkg doesn't define a CLOSE method";
185 package Tie::StdHandle;
187 @ISA = 'Tie::Handle';
193 my $fh = do { \local *HANDLE};
195 $fh->OPEN(@_) if (@_);
199 sub EOF { eof($_[0]) }
200 sub TELL { tell($_[0]) }
201 sub FILENO { fileno($_[0]) }
202 sub SEEK { seek($_[0],$_[1],$_[2]) }
203 sub CLOSE { close($_[0]) }
204 sub BINMODE { binmode($_[0]) }
208 $_[0]->CLOSE if defined($_[0]->FILENO);
212 sub READ { read($_[0],$_[1],$_[2]) }
213 sub READLINE { my $fh = $_[0]; <$fh> }
214 sub GETC { getc($_[0]) }
219 print $fh substr($_[1],0,$_[2])